Git notes details

Question

I\'ve read this and this but still see them as obscure. By far understood:

• creation (git notes add -m \"a note\")
• notes are namespaced
<

Answer 1

I wrote about them more here, as part of my git tip of the week series.

http://alblue.bandlem.com/2011/11/git-tip-of-week-git-notes.html

The notes themselves are blobs that are stored in a separate ref file (refs/notes/commits) and are organised by the commit that they are pointing to (so git ls-tree refs/notes/commits) gives a tree object (think: directory and content) where each directory name is the thing they are pointing to and each value is a blob containing the notes message itself.

You can see Gerrit's use of review notes in the JGit review tree (which uses refs/notes/review instead of refs/notes/commit but essentially exactly the same principle) in GitHub by going here:

https://github.com/eclipse/jgit/tree/refs/notes/review

Since it's also a ref, and the delta to the file content are stored with commits, you can see the individual notes being changed, for example:

https://github.com/eclipse/jgit/commit/de70108c883afe563a48352c05cdd440c25f58cc

Note that the name of the file is shown as the path of the object; in the above case, de70... is the commit that added the message, but the content of the commit is changing a file 3a/bf... which corresponds to this commit:

https://github.com/eclipse/jgit/commit/3abf35bc0fc7a1c130e8fec42083ffd21c342129

And if you chase the review link there to the original Gerrit source:

https://git.eclipse.org/r/#/c/54632/

you see that the review data corresponds with that of the notes element.

As for whether they merge cleanly - since each note corresponds to each commit, and each commit is immutable once change, and the note commit is on a per-directory/file basis, you can easily have multiple notes for different commits overlapping without fear of merge conflict. However if two programs/processes update the same commit note then you may have merge problems that need to be resolved in the same way as any other DVCS merge.

Generally speaking, programs that need to store orthogonal information should use their own notes space, like Gerrit does for refs/notes/review. So if you have refs/notes/program1 and refs/notes/program2 you will never get a collision.