These are key-value structures data that can be included on a commit when it is created. These are used by some systems for attaching metadata. For example, Gerrit uses this for attaching its Change-Id.
Basically the original rendering makes me look incompetent to a casual skimmer. Plus tools like JetBrains IDEs can suss out what comments belong to what DDL anyway.
I love PostgreSQL content. I once used them in a commercial product where table and column comments would contain metadata. The product is now dead. I took this event as a cautionary tale that when we feel super empowered as developers, we often miss the market.
I used git notes for marking which of my commits in my branch I had run the unit tests for (and thus my script would skip those). This was useful when working with open source upstream where you want the massage the branch to perfection with git rebase -i.
It seems git trailers would now be the better place to put that information.
Regarding change ids: I wish git itself had those, as then also the tooling would understand them. Identifying commits by their commit messages is fragile, in particular when you may update those for an MR. While commit id truly identifies the commit in a unique way, it is not a useful identifier when the same changes could be moved on top of some other commit.
edit: Oh it looks like they are actually part of the commit, whereas notes aren't, so it wouldn't be a good replacement for my use.
> Regarding change ids: I wish git itself had those, as then also the tooling would understand them. Identifying commits by their commit messages is fragile, in particular when you may update those for an MR. While commit id truly identifies the commit in a unique way, it is not a useful identifier when the same changes could be moved on top of some other commit.
One trick for running tests in rebase-heavy workflows is to use the tree hash of the commit as the cache key, rather than attach metadata the commit itself.
- That way, tests will be skipped when the contents of the commit are the same, while remaining insensitive to things like changes to the commit message or squashes.
- But they'll re-run in situations like reordering commits (for just the reordered range, and then the cache will work again for any unchanged commits after that). I think that's important because notes will follow the commits around as they're rewritten, even if the logical contents are now different due to reordering? Amending a commit or squashing two non-adjacent commits may also have unexpected behavior if it merges the notes from both sides and fails to invalidate the cache?
I've also seen use-cases might prefer to use/add other things to the cache key:
- The commit message: my most recent workflow involves embedding certain test commands in the message, so I actually do want to re-run the tests when the test commands change.
- The patch ID: if you specifically don't want to re-run tests when you rebase/merge with the main branch, or otherwise reorder commits.
Unfortunately, I don't have a good solution for those at present.
I like the idea of conventional commits, but the lack of many useful categories is a real `chore:` to where I end up making my own, which tooling of course doesn’t recognize. The codification of something called conventional commits strikes me as kind of counterintuitive anyway.
Side note: I really miss Gerritt from my time working at GOOG, but man is its deployment story kinda crap in the 2020s. I tried to run an instance locally and was hoping to integrate it with my github hosted repo ended up just frustrated.
Is there anything equivalent -- that handles tracking changes over commits etc better than GH -- that is more actively developed and friendly for integration with GH? I hate GH's code review tools with the heat of 10,000 suns.
GitLab is actively developing native support for stacked diff workflows. CLI support for creating stacks landed in GitLab 17, and now they’re working on the code review workflow for it.
To be honest, though, I find it easiest to create several branches with Jujutsu and then manually chain the MRs. That’s what glab does under the hood with glab stack commands. Looking forward to the code review tools in a future version.
For GitHub, though, I think Graphite is the best tool I’ve looked at so far, but I use GitLab at work so I’m not the best judge of GitHub tools for lack of experience using them at scale.
I think phabricator was doing a decent job at it while it lasted, don't know where they are at since IIRC it got abandoned and then forked.
The best way to track meta history is to have it baked into the VCS, so here Mercurial is king, and heptapod (a friendly fork of Gitlab meant to support Mercurial repos and concepts) apparently does a good job at it since it's used for Mercurial's own development (after they transitioned from mailing lists to Gerrit? to phabricator to Heptapod)
While I mostly try to go with the flow, I do get frustrated that there are more natural places to integrate with a issue tracking system like trailers, but they are so far off issue trackers’ happy path that it’s not worth it.
I think the problem is exacerbated by the fact that issue trackers follow fashion; and it’s more common that you are using the flavor of the week; and that flavor isn’t close to feature complete; and new features get added at a glacial pace.
I suppose this is a long winded way of stating how annoyed I am with branch names derived from linear ticket’s titles for tracking purposes, and I wish I could use some other form of metadata to associate commits with an issue, so that I could have more meaningful PR titles (enforced that I must use the linear branch name as the title).
Though I’ll admit that it’s an issue of a size that’s more appropriate to gripe about on the internet than try to change.
Everything you are arguing against is convention, not intrinsic. If you have a better way of doing things, do it that way. Or convince your employer to do it that way.
TIL the `--trailer` CLI option. I used to edit the commit message in a text editor and manually add the trailers (which works for GitHub `Co-Authored-By`).
being able to use them with `git log` format is pretty cool.
Yeah I love trailers. I remember trying to use notes for certain things, and they were just kind of a pain (though I cannot remember exactly what roadblocks I hit). Trailers met my needs nicely.
Sounds really cool, but how do notes play together with the "history rewriting" features (amend, rebase, etc) where you effectively replace a commit with a modified copy? It sounds as if the notes are attached to a specific commit (or tree or blob) ID. Are git rebase etc smart enough to also copy over the notes to the new commit, or will they just vanish?
What happens on interactive rebases, e.g. if I squash multiple commits into a single one?
I see the same problem with attaching notes to blobs and trees: It's not doing what you might think it does: It feels like it would attach metadata to a file or directory in the repo, but it really attaches the metadata to some specific content:
E.g. if you have a blob that encodes the string "Hello world!" and attach the note to it, would git associate that note with all files that have that content?
Also, if you change one file to "Hello, world!", would it lose the notes?
By default no copying will be done. While `notes.rewrite.amend` and `notes.rewrite.rebase` are true you also need `notes.rewriteRef` which tells it what notes refs should be rewritten. And it has no value by default. (you can set it to a glob copy over all notes refs)
I've been using git for probably 10 years and I didn't know git notes existed. Cool!
> Here is a plea for all forges: make code review metadata available offline, inside git.
I think this will fall on deaf ears as far as commercial forges like GitHub go, since as you yourself observe:
> But much of the value of git repos ends up locked into forges, like GitHub.
For-profit enterprises are not generally excited about commoditising their own value-add. This is not a jab at GitHub -- I think GitHub do everything right (offer a great service, a very generous free tier, and make it possible to extract all your data via API if you want to shift providers). It's just the nature of any commercial operation.
Git notes are only cool if you frequently add text to a commit after the commit has happened and visible to others.
The Acked-By and mailing list discussion link examples don't seem to be good examples. Both of these are likely already known when the commit is made. And git commit message basically can have an unlimited length, so you could very well copy all the discussions about the commit that happened on a forge into the commit message itself.
One use case I think might be a better example is to add a git note to a commit that has later been reverted.
The common failure mode is commit messages proudly proclaiming they fixed a bug that they did not. And linking knock-on bugs created by their fixes to one bug.
Maybe I’m weird that way. I’ve had too many coworkers who don’t really even look at annotations to remind themselves why this code was written in the first place. They will just yolo and hope nobody ties the problems back to them.
But once you’ve dealt with an irate customer who waited impatiently for a bug to be fixed, and only to have the bug be reintroduced a short time later, you may become more circumspect about bug fixes.
There’s often a refactor needed to fix multiple bugs at once. There’s often refactor can open up new feature opportunities, or performance improvements.
> The Acked-By and mailing list discussion link examples don't seem to be good examples. Both of these are likely already known when the commit is made.
Discussion regarding a commit (is: review) and acknowledgment of a commit cannot happen before the commit has been made.
> One use case I think might be a better example is to add a git note to a commit that has later been reverted.
Commit messages are better for this use case. When you got blame a file, it shows the latest changes for that file. If a commit reverts changes from another commit, the newer commit that reverts the older commit will show up in the blame.
> Discussion regarding a commit (is: review) and acknowledgment of a commit cannot happen before the commit has been made.
It can't happen before the commit on a feature branch, but it can happen before merging the commit back to the main development branch. Given that a rebase or merge commit is already frequently necessary to integrate changes from a feature branch after review is finished, I don't see why this type of info couldn't be added (or even required to exist) before merging.
You’re treating a commit as an atom, which is not true in patch based git situations like Linux.
Most of the rest of us do not work this way, but they still do. The rest of us also only have to deal with three way merges most of the time, instead of octopus merges. Though I jokingly call, “fixing an incorrect three way merge” a “five way merge” because you end up doing a star shaped pattern of diffs to re-resolve the code to retain the intents of all three versions. A to merge, B to merge, merge to HEAD~, A to HEAD~ and B to HEAD~
There are many "Git's coolest, most unloved feature", e.g.: bisect, pickaxe, reflog, range-diff, archive, annotated tags, etc. Sadly they are often forgotten as many people thing of Git only as a glorified Google Drive...
Git notes is redundant since you need a higher-level project management tool to track features anyway. Roadmaps, feature hierarchy and non-technical details. Think of any big tracker or Jira.
I think that's fine. Unix philosophy is to focus on one thing and do that well.
A project management tool that uses Notes would make IDE integration easier though.
I vaguely recall dismissing Notes as a solution to my problems. I may be recollecting some of this wrong, but IIRC the problem with Notes is that they aren’t batteries included. It’s easier to cajole devs into using new tools if the setup is simple and it doesn’t complicate their workflow. Notes fails this litmus test. Set it on by default and make it come down with pull and up with push instead of a separate activity.
There are many uses for Git notes even though you might use a project management tool. Particularly all those things which are relevant for developers only, or that the developers can use as the data source for "higher-level" goals.
I use a lot of features of my tools only when the shit hits the fan. People appreciate me doing it quickly. What they don’t appreciate is when I get mad at them for polluting those tools during their normal activities. Like destroying git history by renaming files incorrectly.
It’s hard to explain to them that things like “mis en place” aren’t OCD but table stakes for sophisticated activities.
When I presented most of the ones that I listed to other people they started to say how it would be great if they know these features before, and started to use immediately.
So, yet I understand that some tools do too much, I don't think that this is the case here.
Git notes were used at the LibreOffice project to track, for each commit to the Apache OpenOffice repository (which they mirrored as a branch on LibreOffice's git repository), whether that commit was not relevant (for instance, changes to the build system which LibreOffice had long replaced with a better one), duplicated an already existing change on LibreOffice (often from many years earlier), or, the least common case, that it was accepted into LibreOffice (and which commit did the cherry-pick). You can still see it for itself at https://cgit.freedesktop.org/libreoffice/core/log/?h=aoo/tru... (that git front-end still displays notes).
(They stopped tracking these changes a few years ago, probably because the pace of changes to Apache OpenOffice slowed down to a trickle, and there's no longer much to be gained by cherry-picking these few changes.)
Readit News
https://alchemists.io/articles/git_trailers
These are key-value structures data that can be included on a commit when it is created. These are used by some systems for attaching metadata. For example, Gerrit uses this for attaching its Change-Id.
https://www.postgresql.org/docs/17/sql-comment.html
This allows you to attach text to various database objects in PostgreSQL.
I wish PostgreSQL had a feature that was more like structured key-value database object metadata that could be edited.
Compare:
https://github.com/jchester/spc-kit/blob/eb2de71d815b0057e20...
To:
https://github.com/jchester/spc-kit/blob/main/sql/02-spc-int...
Basically the original rendering makes me look incompetent to a casual skimmer. Plus tools like JetBrains IDEs can suss out what comments belong to what DDL anyway.
I don't know why they mandate it to be the last trailer unless it's for regex reasons
It seems git trailers would now be the better place to put that information.
Regarding change ids: I wish git itself had those, as then also the tooling would understand them. Identifying commits by their commit messages is fragile, in particular when you may update those for an MR. While commit id truly identifies the commit in a unique way, it is not a useful identifier when the same changes could be moved on top of some other commit.
edit: Oh it looks like they are actually part of the commit, whereas notes aren't, so it wouldn't be a good replacement for my use.
Projects for which mutable changes are a unit of work are working on standardising that: https://lore.kernel.org/git/CAESOdVAspxUJKGAA58i0tvks4ZOfoGf...
They don't need git support, but it might eventually become first-class.
- That way, tests will be skipped when the contents of the commit are the same, while remaining insensitive to things like changes to the commit message or squashes.
- But they'll re-run in situations like reordering commits (for just the reordered range, and then the cache will work again for any unchanged commits after that). I think that's important because notes will follow the commits around as they're rewritten, even if the logical contents are now different due to reordering? Amending a commit or squashing two non-adjacent commits may also have unexpected behavior if it merges the notes from both sides and fails to invalidate the cache?
- This is how my `git test` command works https://github.com/arxanas/git-branchless/wiki/Command:-git-...
---
I've also seen use-cases might prefer to use/add other things to the cache key:
- The commit message: my most recent workflow involves embedding certain test commands in the message, so I actually do want to re-run the tests when the test commands change.
- The patch ID: if you specifically don't want to re-run tests when you rebase/merge with the main branch, or otherwise reorder commits.
Unfortunately, I don't have a good solution for those at present.
I'm a big fan of conventional commits, and trailers seem like a better way of adding such metadata.
Is adding them manually to the commit message functionally equivalent to using the `--trailer` flag?
Yes. The flag is perfect for scripts but it's exactly equivalent to adding the text manually.
Is there anything equivalent -- that handles tracking changes over commits etc better than GH -- that is more actively developed and friendly for integration with GH? I hate GH's code review tools with the heat of 10,000 suns.
To be honest, though, I find it easiest to create several branches with Jujutsu and then manually chain the MRs. That’s what glab does under the hood with glab stack commands. Looking forward to the code review tools in a future version.
For GitHub, though, I think Graphite is the best tool I’ve looked at so far, but I use GitLab at work so I’m not the best judge of GitHub tools for lack of experience using them at scale.
The best way to track meta history is to have it baked into the VCS, so here Mercurial is king, and heptapod (a friendly fork of Gitlab meant to support Mercurial repos and concepts) apparently does a good job at it since it's used for Mercurial's own development (after they transitioned from mailing lists to Gerrit? to phabricator to Heptapod)
I think the problem is exacerbated by the fact that issue trackers follow fashion; and it’s more common that you are using the flavor of the week; and that flavor isn’t close to feature complete; and new features get added at a glacial pace.
I suppose this is a long winded way of stating how annoyed I am with branch names derived from linear ticket’s titles for tracking purposes, and I wish I could use some other form of metadata to associate commits with an issue, so that I could have more meaningful PR titles (enforced that I must use the linear branch name as the title).
Though I’ll admit that it’s an issue of a size that’s more appropriate to gripe about on the internet than try to change.
being able to use them with `git log` format is pretty cool.
Lack of support was a big problem.
https://forgejo.org/2025-01-release-v10-0/#new-features
https://codeberg.org/forgejo/forgejo/pulls/4753
What happens on interactive rebases, e.g. if I squash multiple commits into a single one?
I see the same problem with attaching notes to blobs and trees: It's not doing what you might think it does: It feels like it would attach metadata to a file or directory in the repo, but it really attaches the metadata to some specific content:
E.g. if you have a blob that encodes the string "Hello world!" and attach the note to it, would git associate that note with all files that have that content?
Also, if you change one file to "Hello, world!", would it lose the notes?
This is configurable. By default, amend and rebase operations will copy them forward. See git-config(1) under `notes.rewrite`.
> Here is a plea for all forges: make code review metadata available offline, inside git.
I think this will fall on deaf ears as far as commercial forges like GitHub go, since as you yourself observe:
> But much of the value of git repos ends up locked into forges, like GitHub.
For-profit enterprises are not generally excited about commoditising their own value-add. This is not a jab at GitHub -- I think GitHub do everything right (offer a great service, a very generous free tier, and make it possible to extract all your data via API if you want to shift providers). It's just the nature of any commercial operation.
The Acked-By and mailing list discussion link examples don't seem to be good examples. Both of these are likely already known when the commit is made. And git commit message basically can have an unlimited length, so you could very well copy all the discussions about the commit that happened on a forge into the commit message itself.
One use case I think might be a better example is to add a git note to a commit that has later been reverted.
Maybe I’m weird that way. I’ve had too many coworkers who don’t really even look at annotations to remind themselves why this code was written in the first place. They will just yolo and hope nobody ties the problems back to them. But once you’ve dealt with an irate customer who waited impatiently for a bug to be fixed, and only to have the bug be reintroduced a short time later, you may become more circumspect about bug fixes.
There’s often a refactor needed to fix multiple bugs at once. There’s often refactor can open up new feature opportunities, or performance improvements.
Discussion regarding a commit (is: review) and acknowledgment of a commit cannot happen before the commit has been made.
> One use case I think might be a better example is to add a git note to a commit that has later been reverted.
Commit messages are better for this use case. When you got blame a file, it shows the latest changes for that file. If a commit reverts changes from another commit, the newer commit that reverts the older commit will show up in the blame.
It can't happen before the commit on a feature branch, but it can happen before merging the commit back to the main development branch. Given that a rebase or merge commit is already frequently necessary to integrate changes from a feature branch after review is finished, I don't see why this type of info couldn't be added (or even required to exist) before merging.
Most of the rest of us do not work this way, but they still do. The rest of us also only have to deal with three way merges most of the time, instead of octopus merges. Though I jokingly call, “fixing an incorrect three way merge” a “five way merge” because you end up doing a star shaped pattern of diffs to re-resolve the code to retain the intents of all three versions. A to merge, B to merge, merge to HEAD~, A to HEAD~ and B to HEAD~
I think that's fine. Unix philosophy is to focus on one thing and do that well.
I vaguely recall dismissing Notes as a solution to my problems. I may be recollecting some of this wrong, but IIRC the problem with Notes is that they aren’t batteries included. It’s easier to cajole devs into using new tools if the setup is simple and it doesn’t complicate their workflow. Notes fails this litmus test. Set it on by default and make it come down with pull and up with push instead of a separate activity.
It’s hard to explain to them that things like “mis en place” aren’t OCD but table stakes for sophisticated activities.
So, yet I understand that some tools do too much, I don't think that this is the case here.
Shameless plug: I recently did a webinar on how the pickaxe options are better than `git-blame`) that you can find here: https://nofluffjuststuff.com/webinar/142/level_up_your_git_g... (Note: It requires you to provide an email address).
(They stopped tracking these changes a few years ago, probably because the pace of changes to Apache OpenOffice slowed down to a trickle, and there's no longer much to be gained by cherry-picking these few changes.)