Skip to content

Adding Notes

git notes is a command that allows you to add, inspect, and manage additional information (referred to as notes) toobjects without altering the objects themselves. This is particularly useful for attaching metadata like comments, code reviews, or documentation to objectss without changing their hash (which would occur if you amend or edit them directly). It is a lesser-known yet powerful feature of git, often overshadowed by its challenging usability. Git notes allow users to append metadata to commits, blobs, and trees in git without altering the original objects. This feature is highly versatile, enabling a range of applications from tracking time per commit, adding review and testing information, to facilitating fully distributed code reviews. Despite their potential, git notes suffer from limited adoption and usability issues, as seen in GitHub discontinuing their display in 2014.

Use Cases for Git Notes

  • Adding documentation to commits (e.g., explaining why a specific change was made).
  • Code reviews and feedback without altering the commit.
  • Tracking external information (e.g., bug tracker IDs or task numbers) linked to a commit.
  • Tracking time per commit without altering the commit.

Adding Notes to Commits

You can add notes to any commit using the git notes add command. By default, notes are added to the most recent commit.

Example 1: Adding a Note to the Latest Commit

First, create a new commit:

git commit -m "Initial commit"

Now, add a note to this commit:

git notes add -m "This is an extra explanation for the initial commit."

You can inspect the note with:

git log --show-notes

Output:

commit <hash>
Author: Your Name <you@example.com>
Date:   <date>

    Initial commit

Notes:
    This is an extra explanation for the initial commit.

Example 2: Adding Notes to a Specific Commit

To add a note to a specific commit, you need to specify the commit hash:

git notes add -m "Fixes bug #1234." <commit_hash>

Now if you check the logs:

git log --show-notes

You’ll see:

commit <commit_hash>
Author: Your Name <you@example.com>
Date:   <date>

    Some previous commit message

Notes:
    Fixes bug #1234.

Viewing Notes

To view notes attached to commits, use:

git log --show-notes

Alternatively, to view the note for a specific commit:

git notes show <commit_hash>

Editing Notes

If you need to modify a note after it’s been created, use:

git notes edit <commit_hash>

This will open your default editor where you can modify the note.

Removing Notes

To delete a note from a commit:

git notes remove <commit_hash>

Listing All Notes

To list all notes in your repository:

git notes list

This will display all the commit hashes along with their associated notes.

Merging Notes

When collaborating on a project, different contributors might add notes to the same commit. Git provides a way to merge these notes.

Example: Merging Notes

First, fetch the notes from the remote repository:

git fetch origin refs/notes/*:refs/notes/*

Then, merge the notes from another branch:

git notes merge

Splitting Notes by Ref Namespace

You can have multiple sets of notes for the same commit by specifying different namespaces. By default, notes are saved under the refs/notes/commits reference, but you can store them elsewhere using the --ref option.

Example: Using a Custom Namespace for Notes

Add notes under a different reference (e.g., refs/notes/review):

git notes --ref=review add -m "This commit has passed the review." <commit_hash>

To view these notes:

git log --show-notes=review

This allows you to have multiple categories of notes, such as code reviews or documentation, without conflicting with one another.

Notes with Multiple Lines

If you want to add a note with multiple lines, use:

git notes add

This will open the default editor, where you can write your multi-line note.

Alternatively, you can use:

git notes add -m "First line" -m "Second line"

Storing Notes in Remote Repositories

By default, notes are not pushed to remotes. You need to explicitly push and fetch notes.

Example: Pushing Notes to a Remote

To push notes to a remote repository:

git push origin refs/notes/commits

Example: Fetching Notes from a Remote

To fetch notes from a remote:

git fetch origin refs/notes/commits:refs/notes/commits

Why Git Notes Face Usability Challenges

Despite their potential, Git notes have limited adoption due to usability challenges and limited toolchain support. For example, GitHub supported displaying notes for a time, but discontinued this feature in 2014 due to low usage and technical limitations.

  • Lack of visibility: Notes are not shown in a default git log output unless explicitly requested with git log --show-notes. This can make them "invisible" to most users unless they are aware of the feature.

  • Not synchronized by default: Notes are not pushed or fetched by default when collaborating with remote repositories. Developers must manually handle pushing and fetching notes using commands like git push origin refs/notes/commits and git fetch origin refs/notes/commits:refs/notes/commits.

  • Toolchain integration: Many popular Git hosting services (e.g., GitHub, GitLab) and GUIs do not natively support Git notes in their interfaces. This limits their visibility and usefulness in typical workflows, which focus more on commit messages and branch structures.

Conclusion

git notes provides a flexible way to attach additional metadata to commits without modifying them. This feature is particularly useful for attaching comments, reviews, or documentation to commits, and can be customized by namespaces for different purposes. It’s also a great way to keep a clean history while still having the context you need.