Image of git notes | Enhance Git Commit Messages with Notes

ADVERTISEMENT

Table of Contents

Introduction

Git commits are useful for helping developers understand why a change was made, however, there are times the developer needs to add extra information that was not captured in the commit message. This poses a problem since commit messages are a part of the commit's actual content and can not be modified easily without rewriting history. This is where Git notes come in.

In this article, we will discuss what Git notes are and how to use them in your Git workflow.

What are Git notes and why use them?

Git notes are a way to add extra information to a commit without changing the commit message or modifying the history of the commit. Changes to a commit message modifies the SHA-1 hash.

Git notes can be used to add extra information to a commit that can be shared with other users, without changing the commit itself.

Git notes example

To view an added Git note and other information about the commit, you run can simply run the git log command:

commit 22e53c7fdff5c1854ded11f23630f582a118989a (HEAD -> main)
Author: Teniola Olowookere <90247181+Teniola-theDev@users.noreply.github.com>
Date:   Fri Oct 7 21:56:22 2022 +0100

    Initial commit

Notes:
    This is a test note attached to this commit.

If a note exists for this commit it will be displayed below the commit message.

The 40-digit string that follows "commit" is the commit-id. The commit message is "Initial commit" and the Git note added to the commit is "This is a test note attached to this commit."

Where are Git notes stored?

By default, Git notes are stored in a separate, special Git ref of the repository located in the at the path .git/refs/notes.

Note that this is not a branch ref, so when you run the git branch command, it does not show up. This is because the git branch command lists the .git/refs/heads by default and not .git/refs/notes.

How to use Git Notes

There are quite a number of things you can do with Git notes:

  • Create Git notes
  • Edit Git notes
  • Append Git notes
  • Copy Git notes
  • Delete Git notes
  • Show Git notes
  • View Git notes in Github

Letโ€™s discuss each of these options one by one.

Create Git notes

You can choose to create a git note for your most recent commit by running:

$ git notes add -m "message"

You can also choose to create a git note for a specific commit by running:

$ git notes add -m "message" <commit-id>

Append Git notes

Appending notes in Git is similar to editing, but in this case, a new note message is added to the targeted commit and the existing git note is retained.

To do this, run:

$ git notes append -m "message" <commit-id>

If the commit ID is not specified, the message will be appended to the git note of the most recent commit.

Copy Git notes from A to B

To copy a note to a commit that does not have an existing git note , you run:

$ git notes copy <commit-id A> <commit-id B>

Where A is where you are copying from and B is where you are copying to.

If the commit you are copying to (commit B) has an existing note, you would have to overwrite the existing git note in commit B by adding the force flag -f:

$ git notes copy -f <commit-id A> <commit-id B>

Delete Git notes

To delete git notes, you run this command:

$ git notes remove <commit-id>
Removing note for object HEAD

You can omit the commit-id if you are deleting the note on the HEAD commit, which is usually the tip of the currently checked out branch.

You can also delete multiple notes just by specifying multiple commit IDs in one command.

Show Git notes

To display only the git note of a specified commit (without including other information like the commit-id, commit message), run:

$ git notes show <commit-id>
<git notes message on the last commit>

You can omit the commit-id to display the git note on the most recent commit.

Are Git notes pushed and pulled?

When you add git notes to a commit and push that commit to a remote repo, the git notes do not appear in the remote. This is because git notes are neither pushed nor pulled by default, just like Git tags.

To push all existing git notes to an example remote repository on GitHub, run:

$ git push origin refs/notes/commits
Enumerating objects: 6, done.
Counting objects: 100% (6/6), done.
Delta compression using up to 4 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (5/5), 631 bytes |
78.00 KiB/s, done.
Total 5 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (2/2), completed with 1 local object.
To https://github.com/Teniola-theDev/git-notesv1.git
   3b958c8..a13a224  refs/notes/commits -> refs/notes/commits

To pull down all existing git notes from the remote to your local repository, run:

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

How to view notes on Github?

In the past, GitHub supported the display of notes, but this was changed after GitHub updated its UI so now, git notes are no longer visible.

Summary

Git notes are one of Github's highly useful but under-utilized features. In this article, we took a closer look at this feature and its commands.

We covered what Git notes are and how to create, edit and append to one. We also explained how to copy one git note to another and how to delete one or multiple git notes.

Finally, we covered how to push and pull git notes to and from remote repositories, while also touching on whether it's possible to see your git notes in Github.

Git notes are very helpful when it comes to adding extra information to a commit, and it can often be less tedious than editing a commit message which modifies Gitโ€™s history.

Next Steps

If you're interested in learning more about how Git works under the hood, check out our Baby Git Guidebook for Developers, which dives into Git's code in an accessible way. We wrote it for curious developers to learn how Git works at the code level. To do this, we documented the first version of Git's code and discuss it in detail.

We hope you enjoyed this post! Feel free to shoot me an email at jacob@initialcommit.io with any questions or comments.

References

  1. SHA-1 Hash Wikipedia - https://en.wikipedia.org/wiki/SHA-1
  2. Git SCM Docs, Git notes - https://git-scm.com/docs/git-notes

Final Notes