16

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

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

Max
  • 1,741
  • 3
  • 23
  • 40
  • 1
    See also http://stackoverflow.com/a/18279951/6309 for a concrete illustration on how notes are working. – VonC Jan 21 '16 at 07:52

1 Answers1

21

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.

AlBlue
  • 23,254
  • 14
  • 71
  • 91
  • Al, thanks a lot for comprehensive answer and article. 1) I've not seen */tree/* urls before (normally the dropdown in Github shows me only branches/tags items. How do you navigate to this tree view from top level https://github.com/eclipse/jgit ? 2) Al do you know if there is any connection between notes and peers comments on commit? Can we pull peers comments? – Max Aug 28 '15 at 11:36
  • The /tree/ view is the default one, and you get that when you click on a branch/tag. The top-level view https://github.com/eclipse/jgit is in fact an alias for https://github.com/eclipse/jgit/tree/master. You can pull notes down (as per my block) by pulling refs/notes/ to your local repository. – AlBlue Aug 28 '15 at 11:42
  • Sorry, Al, I meant `refs` urls. not `tree` urls – Max Aug 28 '15 at 11:48
  • 3
    @AlBlue is it possible that gihub has dropped support for notes? I don't see notes attached to example you give in the answer. E.g. I don't see any notes in https://github.com/eclipse/jgit/commit/de70108c883afe563a48352c05cdd440c25f58cc – Michael_Scharf Aug 06 '16 at 01:05
  • The 'notes' refspace has different subdirectories, and the default one for commits is `refs/notes/commits` I believe (https://git-scm.com/docs/git-notes). The Gerrit Review system uses `refs/notes/review` instead, so I don't know if GitHub's web-based interface would see them – particularly since I don't know if the refs/notes space is mirrored to GitHub. However, when I answered this question it's possible that GitHub updated their UI not to show it any more ... – AlBlue Aug 08 '16 at 08:54
  • 1
    @Michael_Scharf: GitHub's post on dropping notes support: https://github.blog/2010-08-25-git-notes-display/ (see 2014 update: "Displaying Git notes on GitHub is no longer supported.") – nishanthshanmugham Feb 11 '23 at 22:15