Obscure git commands: git notes

I have previously written about the awesome but less known git bisect command and the rather obscure git interpret-trailer command. Today I thought I’d share another obscure git command that I stumbled upon during my research: git notes.

Adding notes to git commits without changing the commit

git-notes - Add or inspect object notes

Adds, removes, or reads notes attached to objects, without touching the objects themselves.

That is the beginning of the man-page. So, git notes can be used to add some information to a commit, without changing the commit itself. The documentation gives example: You could add a note to a commit that indicates who tested the commit:

$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
$ git show -s 72a144e
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

    Tested-by: Johannes Sixt <j6t@kdbg.org>

I would think that the most common use-case for git notes is to add release info to your commits that can then be automatically used to create a list of release notes. Of course, you can also do that by agreeing on specially formatted release message, for example by using git interpret-trailer. But not all developers are great a writing helpful release that can be easily understood by regular people. Using git notes for this purpose does make this whole process more flexible. But there are drawbacks with this approach (see below).

Adding binary files as notes!?

The strangest feature of git notes is the ability to add binary files as notes. That means you could, for example, add the compiled executable of a commit as a note to that commit. I cannot really think of a sensible use-case, but again, here is the example from the documentation:

$ cc *.c
$ blob=$(git hash-object -w a.out)
$ git notes --ref=built add --allow-empty -C "$blob" HEAD

I would be curious if anybody has come up with a real use-case for this scenario.

Drawbacks of using git notes

For some use-cases, notes can be pretty useful. But one problem with git notes is that not many GUI tools seem to support it. For example, I checked if Jetbrain’s IDEs (IntelliJ, PyCharm etc.) support it, and there is an open issue from 2016 with only 8 up-votes for this feature. So it’s not likely to be implemented any time soon. If your team’s favorite git tool doesn’t support notes, than you will probably not easily convince your team to adopt this feature.

Another drawback of git notes for teams is that they are not automatically shared. You need to push them separately and that is not as straight forward as one would hope, judging from the comments to this answer on stackoverflow.

See also