Git needs a way to annotate previous commits, without changing their contents and force-pushing. It’s good that commits are immutable, but we need the ability to add more information to old commits much later.
For example, if last year I made a change and explained the reason in a commit message,
and this year I realize that my reasoning was completely wrong,
I want to be able to add a message for myself next year
when I might be doing a git blame and finding the inaccurate explanation in last year’s message.
(It goes without saying that it’s possible to change that commit from last year and that doing so has other extremely inconvenient effects.)
And TIL that Git has had this feature for over 15 years, but that its implementation is fatally flawed.
git note was added in Git 1.6.6
which was released in 2009!
And it’s still part of Git today.
It lets you add annotations to previous comits,
without changing their hash.
Which is great!
Except:
- Notes are not pushed or pulled by default.
- Notes are not supported in certain major web UIs
Which is really too bad.
Writing notes
git notes add -m "Your note" SOME_SHA
You can also append to an existing note with git notes append.
Pushing and pulling
To push local notes:
git push origin 'refs/notes/*'
To pull notes from the remote:
git fetch origin 'refs/notes/*:refs/notes/*'
You can configure git to always pull and push notes:
git config --add remote.origin.fetch +refs/notes/*:refs/notes/*
git config --add remote.origin.push refs/notes/*:refs/notes/*
Command line suppport
Notes are shown by default in git show and git log.
Web UI support
GitHub has added and then later dropped support for displaying notes.
GitLab does not support notes.
Gitea does support notes, though there isn’t any official documentation or issue on this as far as I can tell; see this screenshot. This may imply support in GOGS and/or Forgejo as well, but I haven’t checked.
Sourcehut seems to use it to sign releases according to its documentation, but I’m not sure if or how notes are displayed in the Sourcehut UI.