gitgit-notes

Git notes details

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

Questions:

  1. notes seem not to create a commit, so how the push (example) is possible for them? what is the mechanism underneath it? what is note addition conceptually if not a commit?
  2. where can I see my push'ed notes on Github UI?
  3. is there any relation between Github commit comments people can make and notes functionality?
  4. if Github comments are notes how can I fetch them and see on them on my local comp via git log?
  5. if Github comments are not notes, what they are and is it possible to fetch them?
  6. are notes mergeable? how?
  7. are there any caveats of resolving conflicts for edited notes?
  8. are there any other problems/difficulities with notes?

thanks

Solution

  • 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.