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.
"The web interface to the version control system doesn't parse the here-string correctly" isn't really a criticism of the PostgreSQL extension. It's a bug in the syntax highlighting.
The COMMENT feature isn't even a good choice for a VIEW, PROCEDURE, or FUNCTION, each of which already supports comments inline in the object definition on the server. No, the main benefits are adding comments to objects that DON'T retain them, like a TABLE, COLUMN, CONSTRAINT, ROLE, etc.
Since the project consists of multiple SQL files already, a workaround might be to split out all the “comment on” statements from each file into new files following them.
So in file 02-… you have your “create schema”, “create view” and so on. And then in file 03-… you have only the “comment on” statements that go with the things from file 02. And then file 04-… contains “create schema” and “create view” and so on, and file 05-… has the “comment on” statements for file 04-….
And in addition you could then add dash dash comments in 02 and 04 referring to files 03 and 05. And in file 03 and 05 at the top mention that these are valid SQL for PostgreSQL and that GitHub has trouble rendering them properly.
It’s a bit messy of course, but that’s why I say it’s a possible workaround rather than a great solution. Could be worth considering and trying, anyway.
I hate it. I used it to have carefully curated metadata (sources etc) to my collection of tens of tables, and someone else took backup/restore of the database and all this was lost.
with supabase it is almost essential. But adding comments with migrations is somewhat tedious, unless you're writing actual sql. Like, you know, with supabase.
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.
In my case I wanted to invalidate the notes when rearranging commits, because changing order could introduce bugs, but also have a single command that ensures that all my commits are tested before sending pull request. I think maybe it used to work that way (remove notes upon rebasing) out of the box that time, but if not, then I suspect I simply added the git commit id to the note, which can be effectively used for validity checking.
Of course, if the notes mechanism didn't exist, then I could have just used a local file.. But it's nice to see the messages in the git log.
But yeah, both kinds of keys would be useful for this purpose, depending on the exact needs.
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.
Well, they're just commonly used commit types. I don't follow the "spec" strictly and have my own conventions as well. I don't use any tooling that reads them, and I'd probably write my own if needed.
I mainly find them helpful for sticking to atomic commits. If a change doesn't align with the commit type, or it touches too many parts of the codebase, that means it should be in a separate commit.
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.
Putting stacked diffs aside, I'd frankly just be happy with the ability to track comments across different commit hashes. This is something neither GitLab or GitHub can do:
1. "Please change this"
2. <I change it, and force-push the change [cuz I don't like a messy git history]>
3. Comment keeps association with the original line and/or its new replacement.
Gerrit has no problem w/ this flow. GH and GL both can't do it.
GH wants to force you to put a pile of "fix" commits in and then either do a merge commit (eww) or squash the whole thing into one commit (not ideal in some cases).
Gerrit uses a “Change-Id” trailer with a unique value. When you “fix up” a commit, the commit SHA changes but the change id remains the same. That’s how it can identify different commits with the same change id as patchsets of the same change.
This is based on what I remember (haven’t used gerrit in a while), so it may not be accurate.
I used gerrit in my previous job and miss using it. Would definitely prefer it over GitHub which is more popular (and convenient of course, can’t deny that).
Your understanding of the Change-Id footer sounds like it matches mine.
I’d note that it works that way presently, but the teams behind git, gerrit, jj-vcs, and a couple of other relevant stakeholders have an email thread going in which, from what I understand, they discuss standardizing on the approach taken by jj-vcs:
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)
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.
That's a UI problem with git making it hard to find hidden commits (pre-rebase). The commits aren't destroyed, they are hidden. The Jujutsu CLI is nice because it fixes this UI problem.
Not only that. Git doesn't appear to have any internal link between the hidden pre-rebase commits and the post-rebase commits, which hurts its ability to copy later commits across that rebase.
Yes, you're supposed to avoid moving later commits across a rebase... but the reason you're supposed to avoid that is because git is so bad at it.
I don't think I agree with this take, at least not completely. I tend to commit quite frequently when working on a feature branch in ways that wouldn't be desirable to include in the history of the main development branch, and I take advantage of the fact that rebase lets me clean everything up beforehand into whatever commits I actually want afterwards (which I usually do two separate times, once before opening a review so I can ensure that the diffs help make things easier to read, e.g. if I need to include changes from another branch or make changes in the codebase that aren't directly related to what I'm working on but still are useful for my changes for some reason), and then again after the review is complete if I needed to make additional changes that don't belong in a separate commit (because I find that reviews are cleaner when rebases don't take place during them, and a review that requires more than one or two follow-up commits generally tends to be due to issues that need to be addressed with an offline discussion that I can come back afterwards with structural changes that make the existing diff less relevant). Having to preserve the exact history of commits during my development would be a bad thing in my opinion, since it would either require including lots of small unhelpful commits into the history of the main development branch or discourage committing as often, either of which I think would be a mistake.
Where I agree with your take partially is that the UX for all of this in git is not great, and that ends up meaning that most people don't actually use git in this way. If the process of manually structuring the commits to clean up history on a feature branch were more intuitive, then I'd predict the issues of history-destroying rebases to essentially be moot; everyone would just present the commits for review exactly as we'd want them before review, and then we'd fast-forward merge into the main development branch without any issue. The problem is that doing this sort of restructuring after the fact isn't actually easy to learn how to do because of the poor ergonomics of the git CLI, so it's both tedious and error-prone for almost everyone. My perspective is that most of the concern around messing with history in git comes from being burnt by changes that were not intended by the one making them, and that workflows that avoid it (like merge commits) are essentially a compromise to avoid that risk by accepting a certain amount of cruft in the history of the main development branch. I don't blame anyone for using them, since the problems that make the rebase workflow harder are very real, but I don't think that the fact that rebase changes history is the real issue as much as it provides a mechanism for the actual underlying issues to manifest.
You do whatever you want on your own repository, but as soon as you make anything public, for me, it is here to stay, I consider every push to be pulled by someone else, and if you rebase or do anything to change your history, you have just created a new branch, even if you pretend it doesn't exist anymore using a push --force.
Git is a decentralized version control system. It is effectively a blockchain like Bitcoin but without the consensus mechanism, and just like transactions are final on the Bitcoin network, pushed commits are final in git. You can agree to use one branch over another, but if you are using git as designed (i.e. as a decentralized system), it can be confusing. Merge commits are how you can resolve that confusion.
I guess we just fundamentally disagree with how using git should work. I don't agree at all that using git for a public repo somehow implies that you're committing to preserving every single branch in perpetuity just because the tool can support it. If it's confusing, I'd argue it's from mistakenly inferring that others are conveying intent by publishing public feature branches.
That's my core complaint about git's history-destroying behavior. Git wants you to make a clean history, but it also has awful behavior when you modify history that you've started collaborating with people upon.
It is a fundamental flaw. Either git needs to work better at using the history in all of its warty and real glory (for example offering a separate mutable presentation-layer commit-log in front of the immutable data-layer commit-log), or needs to provide better automation and mapping concepts that allow you handle incoming code that has a different history from the current branch.
Git doesn't what you to have a clean history. Git just stores all the commits in a DAG structure, and then gives you a lot of freedom in what you make of it.
The git UI however is notoriously terrible, so your complain about presentation is probably justified, but it git itself offers facilities to keep a clean history without clobbering branches without changing the fundamentals.
For example, you can decide to make your clean branches only out of merge commits, so if you look only at the clean branches you will have the nice history you expect, but each commit will have a reference to a parallel ugly branch so you can see everything if you want to, without rewriting. To avoir conflicts polluting your clean branch, first merge the clean branch into the ugly branch, resolve the conflicts and do everything you need to do to stay up to date, then merge back into the clean branch, with a nice merge commit message. The clean branches merge commits are your "presentation layer".
It won't be mutable, but mutable anything is a problem in a distributed system like git that gives you availability but as per the CAP theorem, not consistency.
My problem is that so many of git's features feel like they just aren't designed to accommodate history rewriting.
Like if I have branch X and branch Y, and X is 1 commit ahead of Y, but I alter the comment of a commit in Y, now X is one or more commits behind Y and will not recognize identical code-changes as identical.
It gets worse if you squash a commit, where you start getting conflicts during merges and rebases even though the code-changes are the same.
I understand why these problems happen, and the ways to prevent it (don't rebase anything pushed), but it still underscores the fact that git doesn't properly accommodate its own love of rewriting history.
If git had a proper synced graph of history-rewriting actions (commit A was rewritten into commit B) then it would be able to provide better responses when doing a merge or reflist across rewritten branches.
Yep, I don't disagree with you about that. To me, the cost of having to stick with a workflow that prevents it (which you describe) is still worth it to have a clean history without merge commits, but I totally understand that this is a matter of personal preference, and having a consistent workflow for everyone working on a project together matters more. Right now, I'm working on a team that uses merge commits for the first time in a while, and it's definitely taking a bit of time to get used to again, but I'm still committing to it (pun intended!)
Basically, the fact that any kind of tweaking to the history in terms of comments or grouping together related commits into a single commit changes the hashes. This means that git's normally useful ability to check "hey is commit X in the history of both branches A and B" is broken.
That's a huge usability problem with git. Even as simple as a "rebase on merge" or "squash on merge" automation makes it impractical to push your topic-branch and keep working locally on that same branch while your topic-branch is being reviewed and tested, because git doesn't retain any concept of the fact that "this block of commits has been transformed into that block of commits and so you can consider them one-and-the-same".
I'm the git sme at my office and I deeply resent the amount of time I have to spent training juniors and students around git's jagged edges.
Ideally git should have a proper in-repo objects that reify a relationship between rebased/squashed/amended/etc commits and their predecessors and exposes that when you ask things like "hey is commit X in ref Y?" it could say "no, but there is a modified version of that commit".
Ah. I know about this. I’m used to people meaning different things when they say history destruction.
There’s also a fun loophole where you can edit other people’s commits when doing a merge and attribute bugs to someone else. I caught someone doing this once (they were terrible at git) on account of I was the one who reviewed the code that got changed, and I specifically looked for that class of bug before approving it. Git blame and the commit history no longer agreed and I was able to show what happened.
Rebase creates an entire new branch and drops the previous one, it is a form of history destruction.
Commits are actually snapshots of the entire repository, not just diffs, so even if the diff is the same, if the base is different, it is not the same commit. And when you rebase, all the old commits will stay there until you run the garbage collector, and only if they don't have a head.
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~
I'm not really sure what you mean by this. Git treats commits as atomic (unchangeable), and thus they are atoms (indivisible). This is not really related to patches, unless you're referring to partially applying patch series. Can you elaborate on what you mean?
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.
Seems like a chicken-and-egg problem. Not enough people know about them because they aren't supported by most providers, and because people don't know about them, there's no pressure for providers to add support for them.
i use git notes pretty heavily in my current role. started as an experiment to keep track of internal code reviews without flooding the commit message or making PRs for everything. i tag every commit with context what tickets it maps to, infra constraints, links to incident threads if it's a fix. all lives in the repo. this avoids the need to grep slack or jira just to know why a line changed. nce you start using it at scale, you realise how little you need the platform UI at all. we keep talking about reproducibility in builds, but never in intent. maybe this is where that starts
haha wait do you actually read long commit messages( more than a line) all the way through? like line-by-line, imo commit msg = tweet, git note = blog post.
In my line of work a bug could cost multiple millions. I do read them. I write long ones. I would love if my colleagues started writing longer ones too.
Most of the times, the commit message is 10+ lines while the change itself is -1/+1.
We use GitHub for repo hosting and a separate issue tracker to coordinate changes. It bothers me a lot that GitHub UI doesn't render markdown for commit messages. We all write really detailed and nicely formatted commit messages, and had to work out a commit message sync so the issue tracker can display related commit messages in full Markdown glory.
That seems more complicated than just adding the info in the commit message. It's not like Git doesn't have flags for trimming commit messages when reading them (--oneline).
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.
Yes, this makes more sense now. Unfortunately I was already a heavy user of log, so then only new part is the term used for the flags. Somehow I've never seen it before
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.)
It is not coolest most unloved feature. It is a gimmick feature that could have been cool in some really specific cases like team of only developers running the whole company.
Whatever is needed goes into commit message and referencing tickets in separate system is a feature not a bug - because JIRA or any other system is used to communicate with non developers. Like business analysts don't get access to code or repositories at all for example or support people don't get access to the repositories and code.
Yeah I can see how one could write front end to get the notes visible/editable by non developers but it still does not make any sense because BA/Support others don't care about specific commits and a single feature might fit into a commit but most likely does not. Even more fun is when you have multi repo and your feature touches couple services then git notes are quite useless because then you really need reference to outside system.
> business analysts don't get access to code or repositories at all for example or support people don't get access to the repositories and code.
Yes, but isn't it insane? What is the benefit from treating your own product as a black box? Yet that's mainstream. Sometimes I have the analyst (not on my team, but from a team we share a monorepo with) asking me questions that can be answered literally with a line of code. And she's a technical kind, knows SQL and such. And we write very idiomatic, high level code. But still, culture cannot change itself until it dies due to inherent inefficiency.
I think you underestimate inefficiency of requiring all business analysts and employees to learn GIT. If not all employees than more employees. I can pick put up job ad for BA saying knows JIRA and I have dozens of applicants.
We had a technical guy once where I worked that wanted to force sales guys to use LaTex to write documentation and requirements in and store it in GIT. I feel bad for the guy as he was laughed out by sales guys and he did not understood why because those are such a great tools…
There’s plenty of data which is extra-commit (doesn’t belong in the commit messages but is relevant). Like if the tests passed[1], manual testing notes, iteration on code review, notes for code spelunking when you find a problematic 6+ month old commit.
Yeah but GIT notes are not the best tool for that unless you are single dev working on your project or you have team of only devs.
If you have manual testers they have their own set of tools and most of them don’t use or have working knowledge of GIT.
For code reviews everyone is using PRs and it is not because they don’t know about GIT notes but because no one is doing reviews per commit and there is no support for discussion and other tools that are baked in forges PR flows.
You can always use git notes for yourself but it is as I called it gimmick feature. I can make a bet you will use it for a week maybe couple weeks and then just stop because in description it sounds good but in practice - no one is using it.
> You can always use git notes for yourself but it is as I called it gimmick feature. I can make a bet you will use it for a week maybe couple weeks and then just stop because in description it sounds good but in practice - no one is using it.
I discovered notes from the man pages around 2020 but didn't use them as it was primarily a local repo feature. By default they don't get pushed or fetched. If course, one can configure it such that it's pushed and fetched, but that's a team decision and mine didn't vote for it.
I feel like notes needs a more similar default to tags' updated defaults today: fetched/pulled by default but not pushed by default. It is useful to keep personal tags and personal notes and some people have workflows involving those, but once tags/notes are in the upstream repository, it should maybe be assumed that everyone should know about them.
Yeah I think that's a pretty big issue. Not going to be fun using git notes for code review if they get lost every time you squash or recreate commits.
One thing that would be really useful though - if you could somehow use git notes to tell Git not to download some blobs by default that would be great. It would solve the "someone added 100 MB of binary files to this project 5 years ago and then deleted them" problem.
That would be too useful though so I wont hold by breath.
I wrote a little tool for versioning based on conventional commits that uses git note for a version override. In case you want to force a specific version instead of the one autodetected, you can add a git note with the version you want.
This was useful when migrating a piece of functionality into its own repo and you want to preserve history. Adding these forced version tags into commits would be quite messy in the new repo where you switch to a new versioning scheme.
I use Git Notes all the time. It doesn’t look like the article mentions that you can attach the notes to emails you send out with git-format-patch(1) and git-send-email(1). I use them for emails to attach comments on patches that shouldn’t go into the commit message:
I did <insert research notes> and found no other places in the code base where this needs to be fixed.
And as the cover letter for a single patch (if needed/not cowered by the commit message).
And also like a commit message on the iterations on the patches. So for a patch series that go over three versions the note may say what updates where done in versions 2 and 3.
And other than that I use notes for:
- Private notes on how I’ve manually tested the commit
- Link to CI
- A localized changelog for customers (who are not technical)
I think it would be interesting to add the prompt (or a summary of the prompt) as a note for each commit. This would allow the LLM to later reason about each line of code by going back and checking the notes to mine for requirements, and take those into account when changing the code again.
> I bet it already exists, but what about an issue tracker in plain text maintained by git itself?
I have an issue tracker file that can be added to a project. While it's technically plain text, the interface for the file ensures that a format is used, and the format ensures that changes reflect only a single ticket.
Just as long as no one edits the file using a different program, it will work just fine.
This would be a cool place for LLMs to store a summary of the prompts used to generate the code in order to make it easier for other LLMs and humans to pick up where they left off.
I've been thinking about this exact same problem. It would be great to store a log of how much time/tokens were spent reasoning, what was the reasoning path, why were certain decisions made, etc.
I don't know if rationale is something better suited for the git commit log, or tagged by code function to an external "rationale" system of record.
A few years ago I wrote a simple git "extension" that allows you to attach signatures to existing git commits, and allow for verification that a minimum number of signatures from relevant teams exist. This is possible because Git Notes allow you to attach and distribute arbitrary metadata with any commit ref.
I had a good use case at Our World In Data for the public data pipeline, where one repo had the pipeline and one git-lfs repo had the build output of the pipeline. A git note added to a commit to the code pipeline recorded the hash identifying the built data.
Overall it felt elegant, and needed no maintenance after setting it up, but honestly it was never used. I think the need to look back in time was rarer than expected, and git notes being hidden by default didn’t help for awareness.
Is there a list of not-really-known features of git (such as git notes, git trailers, etc.)? I have been using git for decades but I have not yet came across of these two.
In practice I get a lot of value out of referencing commit hashes. If I fix a problem I introduced in a previous commit (for example, commit bumped version, and I forgot to bump it somewhere), my fix will say "amends ab12cd34".
That way when I need to cherry-pick that commit, or do something similar (bump again), I can search for the hash of the commit I'm looking at to find what might be missing.
UI is worse than git-notes but no need for additional setup to sync them.
I tried using git notes for distributed secure reviews but hit some road block with merges. It is a good idea that has limitations that limit its adoption
OP suggested that they are unused because of the awkward interface but I find that if you were taking notes in text about a release, you can easily pipe those notes to Git Notes on commit. This seems easy to me. Am I missing something?
Because you would not want to write the whole git history starting from the commit you want to stash this info one everytime you want to stash additional info …
Appending information to the commit itself creates a new commit and all the commits that are based on the commit will also have to change consequently.
Yeah, git notes are AFAIK stashed into their own hidden branch, referencing the original commit by its hash. That is, the git note points to the commit, not the opposite.
Kind of. The structure is the same and you can check it out if you want, but it's actually a 3rd directory under "refs" - the other two being "heads" (branches) and "tags". That avoids special-casing with trying to hide branches or conflicting with a branch name a user might make.
This is great! And how did I not know about this? My favorite days are when I learn something new. Even better are when I learn that I was wrong and change my mind to improve my thinking. So meta!
Git notes would be ideal for annotating commits that contain commit hashes used as breadcrumbs to inform the developer (usually me months later) about context around previous work. These hashes might have changed due to a rebase or from using disk space optimization tools that rewrite history like these:
These methods are all uniquely terrible in various ways. Most likely user error on my part. I need this technique:
1. Choose a range of commit hashes (or hashes before a commit) and remove them. This can be useful when splitting repos, for example on projects that started as backend+frontend where the frontend is being forked off in a new repo and the older backend portion needs to be removed from it for security/privacy.
2. Rebase all branches (including those that crossed the deleted portion) to preserve their structure but start/end as recently as possible. Optionally discard branches that were created and merged entirely within the deleted ported, unless they're the trunk of other branches that merge after the deleted portion.
3. Search for old commit hashes in commit messages and update them to the new hashes while rebasing.
4. Bonus points for updating stashes (or other git features) having any commit hashes in their names. Also for importing/exporting a list of important commit hashes for use in project management, such as updating hashes in comments on kanban boards like Jira.
5. More bonus points for searching for large files (such as app.js or other build artifacts) so that they can be stripped from commits in branches, preferably not on a main trunk like master.
If you followed this far, I could also use a technique that rebases merged branches so that they form a series of D shapes instead of overlapping B shapes (this is useful during git bisect). Ideally this would happen automatically or be enforced via rules on sites like GitHub and GitLab. I always rebase my branches before merging, but others can't be bothered.
Where I'm going with this: I git reset and git cherry-pick constantly in my own branches before merging, so that each branch has a clean work history like the trunk. I think of this as quantum committing, because I keep exploring the problem space until I find a solution that collapses (merges) into the history.
The problem is that git GUIs are inadequate for this work. I need to be able to cut/copy/paste commits, drag and drop them for reordering, etc. It should also derive the commit diff needed to make a commit match a branch (or folder) rather than throwing a conflict in my face, so that it operates more like Apple's Time Machine. If I had this app, I could simply select all commits that I wanted to delete, it would ask me "this rewrites history, are you sure?", and then delete them and do the right thing for affected branches. It would also have infinite undo powered by git reflog.
The idea being that commit hashes should not take priority - it's all about the information. We should never be trapped by the state of the repo, because that creates anxiety.
So we're missing a tool to orchestrate git the way that Kubernetes orchestrates Docker.
Another little-known feature is git trailers:
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.
One more similar feature from a different system: PostgreSQL COMMENT
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.
It's a great feature, but GitHub's parser chokes on it.
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.
"The web interface to the version control system doesn't parse the here-string correctly" isn't really a criticism of the PostgreSQL extension. It's a bug in the syntax highlighting.
The COMMENT feature isn't even a good choice for a VIEW, PROCEDURE, or FUNCTION, each of which already supports comments inline in the object definition on the server. No, the main benefits are adding comments to objects that DON'T retain them, like a TABLE, COLUMN, CONSTRAINT, ROLE, etc.
Since the project consists of multiple SQL files already, a workaround might be to split out all the “comment on” statements from each file into new files following them.
So in file 02-… you have your “create schema”, “create view” and so on. And then in file 03-… you have only the “comment on” statements that go with the things from file 02. And then file 04-… contains “create schema” and “create view” and so on, and file 05-… has the “comment on” statements for file 04-….
And in addition you could then add dash dash comments in 02 and 04 referring to files 03 and 05. And in file 03 and 05 at the top mention that these are valid SQL for PostgreSQL and that GitHub has trouble rendering them properly.
It’s a bit messy of course, but that’s why I say it’s a possible workaround rather than a great solution. Could be worth considering and trying, anyway.
I love PostgreSQL COMMENT. I built a prototype app for a buddy with Supabase and added a COMMENT to every table.
I hate it. I used it to have carefully curated metadata (sources etc) to my collection of tens of tables, and someone else took backup/restore of the database and all this was lost.
with supabase it is almost essential. But adding comments with migrations is somewhat tedious, unless you're writing actual sql. Like, you know, with supabase.
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.
MS SQL has a similar feature called Extended Properties but the API is quite tedious.
I recently learned that GitHub uses it for an alternative to including [skip ci] for what I presume is easier removal by downstream consumers of the commit message https://docs.github.com/en/actions/managing-workflow-runs-an...
I don't know why they mandate it to be the last trailer unless it's for regex reasons
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.
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.
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?
- 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.
In my case I wanted to invalidate the notes when rearranging commits, because changing order could introduce bugs, but also have a single command that ensures that all my commits are tested before sending pull request. I think maybe it used to work that way (remove notes upon rebasing) out of the box that time, but if not, then I suspect I simply added the git commit id to the note, which can be effectively used for validity checking.
Of course, if the notes mechanism didn't exist, then I could have just used a local file.. But it's nice to see the messages in the git log.
But yeah, both kinds of keys would be useful for this purpose, depending on the exact needs.
Interesting, I wasn't familiar with this feature.
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?
> 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.
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.
Well, they're just commonly used commit types. I don't follow the "spec" strictly and have my own conventions as well. I don't use any tooling that reads them, and I'd probably write my own if needed.
I mainly find them helpful for sticking to atomic commits. If a change doesn't align with the commit type, or it touches too many parts of the codebase, that means it should be in a separate commit.
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.
Putting stacked diffs aside, I'd frankly just be happy with the ability to track comments across different commit hashes. This is something neither GitLab or GitHub can do:
1. "Please change this" 2. <I change it, and force-push the change [cuz I don't like a messy git history]> 3. Comment keeps association with the original line and/or its new replacement.
Gerrit has no problem w/ this flow. GH and GL both can't do it.
GH wants to force you to put a pile of "fix" commits in and then either do a merge commit (eww) or squash the whole thing into one commit (not ideal in some cases).
How does Gerrit manage this? Are the comments associated with the source content, instead of commits?
Gerrit uses a “Change-Id” trailer with a unique value. When you “fix up” a commit, the commit SHA changes but the change id remains the same. That’s how it can identify different commits with the same change id as patchsets of the same change.
This is based on what I remember (haven’t used gerrit in a while), so it may not be accurate.
I used gerrit in my previous job and miss using it. Would definitely prefer it over GitHub which is more popular (and convenient of course, can’t deny that).
Your understanding of the Change-Id footer sounds like it matches mine.
I’d note that it works that way presently, but the teams behind git, gerrit, jj-vcs, and a couple of other relevant stakeholders have an email thread going in which, from what I understand, they discuss standardizing on the approach taken by jj-vcs:
https://lore.kernel.org/git/CAESOdVAspxUJKGAA58i0tvks4ZOfoGf...
I’ve really enjoyed jj and im happy to see the community working together on these kinds of things.
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.
I’ve wanted to use them to keep track of whether a change was done by AI.
Lack of support was a big problem.
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.
This is fantastic. This could really beef up CI with ticket numbers and stuff.
oh I have use of that, never heard of it
Also supported by Forgejo since version 10 (released in January of this year):
https://forgejo.org/2025-01-release-v10-0/#new-features
https://codeberg.org/forgejo/forgejo/pulls/4753
That's neat, ty for sharing!
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?
> Are git rebase etc smart enough to also copy over the notes to the new commit...
This is configurable. By default, amend and rebase operations will copy them forward. See git-config(1) under `notes.rewrite`.
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)
Thanks for the warning! From the git docs:
> Set it to refs/notes/commits to enable rewriting for the default commit notes.
Why wouldn’t that at least be the default? Why is rewriting off by default in the first place?
Ah, ok. That sounds better. Thanks for the info!
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.
The history-destroying problems of rebasing are a rant on their own.
That's a UI problem with git making it hard to find hidden commits (pre-rebase). The commits aren't destroyed, they are hidden. The Jujutsu CLI is nice because it fixes this UI problem.
Not only that. Git doesn't appear to have any internal link between the hidden pre-rebase commits and the post-rebase commits, which hurts its ability to copy later commits across that rebase.
Yes, you're supposed to avoid moving later commits across a rebase... but the reason you're supposed to avoid that is because git is so bad at it.
Rebase itself is also often used to work around UI issues of git log to present a "clean history".
I don't think I agree with this take, at least not completely. I tend to commit quite frequently when working on a feature branch in ways that wouldn't be desirable to include in the history of the main development branch, and I take advantage of the fact that rebase lets me clean everything up beforehand into whatever commits I actually want afterwards (which I usually do two separate times, once before opening a review so I can ensure that the diffs help make things easier to read, e.g. if I need to include changes from another branch or make changes in the codebase that aren't directly related to what I'm working on but still are useful for my changes for some reason), and then again after the review is complete if I needed to make additional changes that don't belong in a separate commit (because I find that reviews are cleaner when rebases don't take place during them, and a review that requires more than one or two follow-up commits generally tends to be due to issues that need to be addressed with an offline discussion that I can come back afterwards with structural changes that make the existing diff less relevant). Having to preserve the exact history of commits during my development would be a bad thing in my opinion, since it would either require including lots of small unhelpful commits into the history of the main development branch or discourage committing as often, either of which I think would be a mistake.
Where I agree with your take partially is that the UX for all of this in git is not great, and that ends up meaning that most people don't actually use git in this way. If the process of manually structuring the commits to clean up history on a feature branch were more intuitive, then I'd predict the issues of history-destroying rebases to essentially be moot; everyone would just present the commits for review exactly as we'd want them before review, and then we'd fast-forward merge into the main development branch without any issue. The problem is that doing this sort of restructuring after the fact isn't actually easy to learn how to do because of the poor ergonomics of the git CLI, so it's both tedious and error-prone for almost everyone. My perspective is that most of the concern around messing with history in git comes from being burnt by changes that were not intended by the one making them, and that workflows that avoid it (like merge commits) are essentially a compromise to avoid that risk by accepting a certain amount of cruft in the history of the main development branch. I don't blame anyone for using them, since the problems that make the rebase workflow harder are very real, but I don't think that the fact that rebase changes history is the real issue as much as it provides a mechanism for the actual underlying issues to manifest.
You do whatever you want on your own repository, but as soon as you make anything public, for me, it is here to stay, I consider every push to be pulled by someone else, and if you rebase or do anything to change your history, you have just created a new branch, even if you pretend it doesn't exist anymore using a push --force.
Git is a decentralized version control system. It is effectively a blockchain like Bitcoin but without the consensus mechanism, and just like transactions are final on the Bitcoin network, pushed commits are final in git. You can agree to use one branch over another, but if you are using git as designed (i.e. as a decentralized system), it can be confusing. Merge commits are how you can resolve that confusion.
I guess we just fundamentally disagree with how using git should work. I don't agree at all that using git for a public repo somehow implies that you're committing to preserving every single branch in perpetuity just because the tool can support it. If it's confusing, I'd argue it's from mistakenly inferring that others are conveying intent by publishing public feature branches.
That's my core complaint about git's history-destroying behavior. Git wants you to make a clean history, but it also has awful behavior when you modify history that you've started collaborating with people upon.
It is a fundamental flaw. Either git needs to work better at using the history in all of its warty and real glory (for example offering a separate mutable presentation-layer commit-log in front of the immutable data-layer commit-log), or needs to provide better automation and mapping concepts that allow you handle incoming code that has a different history from the current branch.
Git doesn't what you to have a clean history. Git just stores all the commits in a DAG structure, and then gives you a lot of freedom in what you make of it.
The git UI however is notoriously terrible, so your complain about presentation is probably justified, but it git itself offers facilities to keep a clean history without clobbering branches without changing the fundamentals.
For example, you can decide to make your clean branches only out of merge commits, so if you look only at the clean branches you will have the nice history you expect, but each commit will have a reference to a parallel ugly branch so you can see everything if you want to, without rewriting. To avoir conflicts polluting your clean branch, first merge the clean branch into the ugly branch, resolve the conflicts and do everything you need to do to stay up to date, then merge back into the clean branch, with a nice merge commit message. The clean branches merge commits are your "presentation layer".
It won't be mutable, but mutable anything is a problem in a distributed system like git that gives you availability but as per the CAP theorem, not consistency.
My problem is that so many of git's features feel like they just aren't designed to accommodate history rewriting.
Like if I have branch X and branch Y, and X is 1 commit ahead of Y, but I alter the comment of a commit in Y, now X is one or more commits behind Y and will not recognize identical code-changes as identical.
It gets worse if you squash a commit, where you start getting conflicts during merges and rebases even though the code-changes are the same.
I understand why these problems happen, and the ways to prevent it (don't rebase anything pushed), but it still underscores the fact that git doesn't properly accommodate its own love of rewriting history.
If git had a proper synced graph of history-rewriting actions (commit A was rewritten into commit B) then it would be able to provide better responses when doing a merge or reflist across rewritten branches.
Yep, I don't disagree with you about that. To me, the cost of having to stick with a workflow that prevents it (which you describe) is still worth it to have a clean history without merge commits, but I totally understand that this is a matter of personal preference, and having a consistent workflow for everyone working on a project together matters more. Right now, I'm working on a team that uses merge commits for the first time in a while, and it's definitely taking a bit of time to get used to again, but I'm still committing to it (pun intended!)
Can you say more? I use rebase to avoid history destruction/obscuration. Do you mean squash? If so then I agree.
Basically, the fact that any kind of tweaking to the history in terms of comments or grouping together related commits into a single commit changes the hashes. This means that git's normally useful ability to check "hey is commit X in the history of both branches A and B" is broken.
That's a huge usability problem with git. Even as simple as a "rebase on merge" or "squash on merge" automation makes it impractical to push your topic-branch and keep working locally on that same branch while your topic-branch is being reviewed and tested, because git doesn't retain any concept of the fact that "this block of commits has been transformed into that block of commits and so you can consider them one-and-the-same".
I'm the git sme at my office and I deeply resent the amount of time I have to spent training juniors and students around git's jagged edges.
Ideally git should have a proper in-repo objects that reify a relationship between rebased/squashed/amended/etc commits and their predecessors and exposes that when you ask things like "hey is commit X in ref Y?" it could say "no, but there is a modified version of that commit".
Ah. I know about this. I’m used to people meaning different things when they say history destruction.
There’s also a fun loophole where you can edit other people’s commits when doing a merge and attribute bugs to someone else. I caught someone doing this once (they were terrible at git) on account of I was the one who reviewed the code that got changed, and I specifically looked for that class of bug before approving it. Git blame and the commit history no longer agreed and I was able to show what happened.
Rebase creates an entire new branch and drops the previous one, it is a form of history destruction.
Commits are actually snapshots of the entire repository, not just diffs, so even if the diff is the same, if the base is different, it is not the same commit. And when you rebase, all the old commits will stay there until you run the garbage collector, and only if they don't have a head.
Eh, squash has its place, too. Sometimes I made a simple typo, so I make another commit that fixes the typo and I squash the last two commits.
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~
I'm not really sure what you mean by this. Git treats commits as atomic (unchangeable), and thus they are atoms (indivisible). This is not really related to patches, unless you're referring to partially applying patch series. Can you elaborate on what you mean?
This guy explains it better than I could
https://news.ycombinator.com/item?id=44355218
Does the commit message itself affect the hash or is it separate and outside of the main system, like tags?
The commit message affects the hash.
Discussion can keep happening after the commit is created.
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.
You have to start a new service that offers that feature as one of its differentiators, then the competitors might add it (back) to catch up.
any reason why Forgejo/Codeberg couldn't/wouldn't adopt this?
The only git-notes related issue I found is https://codeberg.org/forgejo/forgejo/issues/6385. So, probably because nobody has raised it.
Seems like a chicken-and-egg problem. Not enough people know about them because they aren't supported by most providers, and because people don't know about them, there's no pressure for providers to add support for them.
i use git notes pretty heavily in my current role. started as an experiment to keep track of internal code reviews without flooding the commit message or making PRs for everything. i tag every commit with context what tickets it maps to, infra constraints, links to incident threads if it's a fix. all lives in the repo. this avoids the need to grep slack or jira just to know why a line changed. nce you start using it at scale, you realise how little you need the platform UI at all. we keep talking about reproducibility in builds, but never in intent. maybe this is where that starts
Shouldn’t that be the commit message ? Or is the goal to also link forward in time, such as “we realised this commit introduced bug #123” ?
haha wait do you actually read long commit messages( more than a line) all the way through? like line-by-line, imo commit msg = tweet, git note = blog post.
In my line of work a bug could cost multiple millions. I do read them. I write long ones. I would love if my colleagues started writing longer ones too.
Me too.
Most of the times, the commit message is 10+ lines while the change itself is -1/+1.
We use GitHub for repo hosting and a separate issue tracker to coordinate changes. It bothers me a lot that GitHub UI doesn't render markdown for commit messages. We all write really detailed and nicely formatted commit messages, and had to work out a commit message sync so the issue tracker can display related commit messages in full Markdown glory.
If you don't expect people to read commit messages, why would you expect that they'd read notes?
That seems more complicated than just adding the info in the commit message. It's not like Git doesn't have flags for trimming commit messages when reading them (--oneline).
This is a UI problem, not a lack-of-knowledge problem. If Github's UI surfaced notes they would instantly get much more usage.
Yeah I wish GitHub supported these
As described in the post they did in the past: https://github.blog/news-insights/git-notes-display/
It does not say why they got rid of it.
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.
In many cases this is because those features arent actually that useful and they are frivolities surrounding a workhorse.
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.
Ha, I expected to know the features you were going to list, but got surprise attacked by pickaxe. What the hell? I guess I shouldn’t be so confident
pickaxe isn't a Git command, rather, it's a set of flags that `git log` offers (specifically `-S` and `-G`).
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).
"Pickaxe" most often means those options. But it's also a (apparently legacy) command alias for git-blame.
Yes, this makes more sense now. Unfortunately I was already a heavy user of log, so then only new part is the term used for the flags. Somehow I've never seen it before
Once I started to use it I almost never used blame anymore
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.)
It is not coolest most unloved feature. It is a gimmick feature that could have been cool in some really specific cases like team of only developers running the whole company.
Whatever is needed goes into commit message and referencing tickets in separate system is a feature not a bug - because JIRA or any other system is used to communicate with non developers. Like business analysts don't get access to code or repositories at all for example or support people don't get access to the repositories and code.
Yeah I can see how one could write front end to get the notes visible/editable by non developers but it still does not make any sense because BA/Support others don't care about specific commits and a single feature might fit into a commit but most likely does not. Even more fun is when you have multi repo and your feature touches couple services then git notes are quite useless because then you really need reference to outside system.
> business analysts don't get access to code or repositories at all for example or support people don't get access to the repositories and code.
Yes, but isn't it insane? What is the benefit from treating your own product as a black box? Yet that's mainstream. Sometimes I have the analyst (not on my team, but from a team we share a monorepo with) asking me questions that can be answered literally with a line of code. And she's a technical kind, knows SQL and such. And we write very idiomatic, high level code. But still, culture cannot change itself until it dies due to inherent inefficiency.
I think you underestimate inefficiency of requiring all business analysts and employees to learn GIT. If not all employees than more employees. I can pick put up job ad for BA saying knows JIRA and I have dozens of applicants.
We had a technical guy once where I worked that wanted to force sales guys to use LaTex to write documentation and requirements in and store it in GIT. I feel bad for the guy as he was laughed out by sales guys and he did not understood why because those are such a great tools…
There’s plenty of data which is extra-commit (doesn’t belong in the commit messages but is relevant). Like if the tests passed[1], manual testing notes, iteration on code review, notes for code spelunking when you find a problematic 6+ month old commit.
[^1] https://news.ycombinator.com/item?id=44348438
Yeah but GIT notes are not the best tool for that unless you are single dev working on your project or you have team of only devs.
If you have manual testers they have their own set of tools and most of them don’t use or have working knowledge of GIT.
For code reviews everyone is using PRs and it is not because they don’t know about GIT notes but because no one is doing reviews per commit and there is no support for discussion and other tools that are baked in forges PR flows.
You can always use git notes for yourself but it is as I called it gimmick feature. I can make a bet you will use it for a week maybe couple weeks and then just stop because in description it sounds good but in practice - no one is using it.
> You can always use git notes for yourself but it is as I called it gimmick feature. I can make a bet you will use it for a week maybe couple weeks and then just stop because in description it sounds good but in practice - no one is using it.
I'll take that bet.
A 9 year old feature request for notes support in GitLab was closed recently
https://gitlab.com/gitlab-org/gitlab/-/issues/15029
You have to log in to read it unfortunately, but any gitlab.com account should work.
There's another issue with a more complete proposal
https://gitlab.com/gitlab-org/gitlab/-/issues/216351
To save people from wondering, it was closed for abandonment and not completion:
> This feature request is being closed as our current focus isn't in this area.
I discovered notes from the man pages around 2020 but didn't use them as it was primarily a local repo feature. By default they don't get pushed or fetched. If course, one can configure it such that it's pushed and fetched, but that's a team decision and mine didn't vote for it.
I feel like notes needs a more similar default to tags' updated defaults today: fetched/pulled by default but not pushed by default. It is useful to keep personal tags and personal notes and some people have workflows involving those, but once tags/notes are in the upstream repository, it should maybe be assumed that everyone should know about them.
What happens of you rebase a branch containing commits with notes attached?
Notes are copied to from the original to the rewritten commit by default. See https://git-scm.com/docs/git-notes#Documentation/git-notes.t... for details.
But I have this in my IRC logs:
Yeah I think that's a pretty big issue. Not going to be fun using git notes for code review if they get lost every time you squash or recreate commits.
One thing that would be really useful though - if you could somehow use git notes to tell Git not to download some blobs by default that would be great. It would solve the "someone added 100 MB of binary files to this project 5 years ago and then deleted them" problem.
That would be too useful though so I wont hold by breath.
Check the notes.rewrite config options in https://git-scm.com/docs/git-notes#Documentation/git-notes.t... Also notes.rewriteRef. You can use these to configure git to carry your notes across amend/rebase.
I wrote a little tool for versioning based on conventional commits that uses git note for a version override. In case you want to force a specific version instead of the one autodetected, you can add a git note with the version you want.
This was useful when migrating a piece of functionality into its own repo and you want to preserve history. Adding these forced version tags into commits would be quite messy in the new repo where you switch to a new versioning scheme.
Why did GitHub remove support for them, and how do we get this decision reversed?
I think the answer is in the link.
Making git notes more usable would make it easier to migrate from GitHub. It would make you less locked in.
I use Git Notes all the time. It doesn’t look like the article mentions that you can attach the notes to emails you send out with git-format-patch(1) and git-send-email(1). I use them for emails to attach comments on patches that shouldn’t go into the commit message:
And as the cover letter for a single patch (if needed/not cowered by the commit message).And also like a commit message on the iterations on the patches. So for a patch series that go over three versions the note may say what updates where done in versions 2 and 3.
And other than that I use notes for:
- Private notes on how I’ve manually tested the commit
- Link to CI
- A localized changelog for customers (who are not technical)
I think it would be interesting to add the prompt (or a summary of the prompt) as a note for each commit. This would allow the LLM to later reason about each line of code by going back and checking the notes to mine for requirements, and take those into account when changing the code again.
Or just put it in the commit message, after all, it is the human's description of what the commit is supposed to do
This seems an interesting thing to explore for adding extra context to coding agents.
I bet it already exists, but what about an issue tracker in plain text maintained by git itself?
See this recent discussion:
https://news.ycombinator.com/item?id=43971620
And less recently:
https://news.ycombinator.com/item?id=20318947
https://news.ycombinator.com/item?id=13732598
> I bet it already exists, but what about an issue tracker in plain text maintained by git itself?
I have an issue tracker file that can be added to a project. While it's technically plain text, the interface for the file ensures that a format is used, and the format ensures that changes reflect only a single ticket.
Just as long as no one edits the file using a different program, it will work just fine.
Don't think anyone uses it, though.
https://github.com/lelanthran/rotsit
Also checkout fossil-scm.org
Yeah, I was going to say, if you think this is cool wait till you get a look at fossil!
It's even got chat!
https://fossil-scm.org/home/doc/trunk/www/chat.md
This would be a cool place for LLMs to store a summary of the prompts used to generate the code in order to make it easier for other LLMs and humans to pick up where they left off.
I've been thinking about this exact same problem. It would be great to store a log of how much time/tokens were spent reasoning, what was the reasoning path, why were certain decisions made, etc.
I don't know if rationale is something better suited for the git commit log, or tagged by code function to an external "rationale" system of record.
A few years ago I wrote a simple git "extension" that allows you to attach signatures to existing git commits, and allow for verification that a minimum number of signatures from relevant teams exist. This is possible because Git Notes allow you to attach and distribute arbitrary metadata with any commit ref.
https://git.distrust.co/public/git-sig
I had a good use case at Our World In Data for the public data pipeline, where one repo had the pipeline and one git-lfs repo had the build output of the pipeline. A git note added to a commit to the code pipeline recorded the hash identifying the built data.
Overall it felt elegant, and needed no maintenance after setting it up, but honestly it was never used. I think the need to look back in time was rarer than expected, and git notes being hidden by default didn’t help for awareness.
Is there a list of not-really-known features of git (such as git notes, git trailers, etc.)? I have been using git for decades but I have not yet came across of these two.
In practice I get a lot of value out of referencing commit hashes. If I fix a problem I introduced in a previous commit (for example, commit bumped version, and I forgot to bump it somewhere), my fix will say "amends ab12cd34".
That way when I need to cherry-pick that commit, or do something similar (bump again), I can search for the hash of the commit I'm looking at to find what might be missing.
UI is worse than git-notes but no need for additional setup to sync them.
you kinda doing by hand what git commit --fixup could do for you, and what git rebase -i could pick up automatically.
Rebasing doesn't work in collaborative situations.
And if not rebasing, since --fixup does not include the hash only the commit message, it's bad for this.
I tried using git notes for distributed secure reviews but hit some road block with merges. It is a good idea that has limitations that limit its adoption
What are the limitations?
If note just for the last commit, would it easier just amend the last commit message to include any note? Don't need remember another command option.
The post links to a GitHub page, which contains this:
> I just blogged about the new git-notes functionality over at the [Pro Git blog](dead link)
The link is archived at https://web.archive.org/web/20100828155504/http://progit.org...
OP suggested that they are unused because of the awkward interface but I find that if you were taking notes in text about a release, you can easily pipe those notes to Git Notes on commit. This seems easy to me. Am I missing something?
Why would I choose to stash information like this in the git notes, versus just appending it to the commit message itself?
Because you would not want to write the whole git history starting from the commit you want to stash this info one everytime you want to stash additional info …
Appending information to the commit itself creates a new commit and all the commits that are based on the commit will also have to change consequently.
Ah; so notes don't impact the commit hash? That is a solid reason.
Yeah, git notes are AFAIK stashed into their own hidden branch, referencing the original commit by its hash. That is, the git note points to the commit, not the opposite.
Kind of. The structure is the same and you can check it out if you want, but it's actually a 3rd directory under "refs" - the other two being "heads" (branches) and "tags". That avoids special-casing with trying to hide branches or conflicting with a branch name a user might make.
Methinks Zawinski's Law of Software Envelopment finds some empirical support here.
This is great! And how did I not know about this? My favorite days are when I learn something new. Even better are when I learn that I was wrong and change my mind to improve my thinking. So meta!
Git notes would be ideal for annotating commits that contain commit hashes used as breadcrumbs to inform the developer (usually me months later) about context around previous work. These hashes might have changed due to a rebase or from using disk space optimization tools that rewrite history like these:
https://rtyley.github.io/bfg-repo-cleaner/
https://github.com/rtyley/bfg-repo-cleaner
https://github.com/newren/git-filter-repo
https://github.com/tiavision/GitRewrite
See also:
https://stackoverflow.com/questions/5613345/how-to-shrink-th...
https://stackoverflow.com/questions/1398919/make-git-consume...
https://stackoverflow.com/questions/2116778/reduce-git-repos...
https://stackoverflow.com/questions/3119850/is-there-a-way-t...
https://stackoverflow.com/questions/38789265/git-delete-some...
https://stackoverflow.com/questions/16057391/git-free-disk-s...
https://stackoverflow.com/questions/31423525/how-to-reduce-d...
https://stackoverflow.com/questions/16854425/compact-reposit...
https://stackoverflow.com/questions/13999191/trimming-huge-g...
https://stackoverflow.com/questions/4515580/how-do-i-remove-...
These methods are all uniquely terrible in various ways. Most likely user error on my part. I need this technique:
1. Choose a range of commit hashes (or hashes before a commit) and remove them. This can be useful when splitting repos, for example on projects that started as backend+frontend where the frontend is being forked off in a new repo and the older backend portion needs to be removed from it for security/privacy.
2. Rebase all branches (including those that crossed the deleted portion) to preserve their structure but start/end as recently as possible. Optionally discard branches that were created and merged entirely within the deleted ported, unless they're the trunk of other branches that merge after the deleted portion.
3. Search for old commit hashes in commit messages and update them to the new hashes while rebasing.
4. Bonus points for updating stashes (or other git features) having any commit hashes in their names. Also for importing/exporting a list of important commit hashes for use in project management, such as updating hashes in comments on kanban boards like Jira.
5. More bonus points for searching for large files (such as app.js or other build artifacts) so that they can be stripped from commits in branches, preferably not on a main trunk like master.
If you followed this far, I could also use a technique that rebases merged branches so that they form a series of D shapes instead of overlapping B shapes (this is useful during git bisect). Ideally this would happen automatically or be enforced via rules on sites like GitHub and GitLab. I always rebase my branches before merging, but others can't be bothered.
https://www.atlassian.com/git/tutorials/merging-vs-rebasing
Where I'm going with this: I git reset and git cherry-pick constantly in my own branches before merging, so that each branch has a clean work history like the trunk. I think of this as quantum committing, because I keep exploring the problem space until I find a solution that collapses (merges) into the history.
The problem is that git GUIs are inadequate for this work. I need to be able to cut/copy/paste commits, drag and drop them for reordering, etc. It should also derive the commit diff needed to make a commit match a branch (or folder) rather than throwing a conflict in my face, so that it operates more like Apple's Time Machine. If I had this app, I could simply select all commits that I wanted to delete, it would ask me "this rewrites history, are you sure?", and then delete them and do the right thing for affected branches. It would also have infinite undo powered by git reflog.
The idea being that commit hashes should not take priority - it's all about the information. We should never be trapped by the state of the repo, because that creates anxiety.
So we're missing a tool to orchestrate git the way that Kubernetes orchestrates Docker.
Coolest? It's just extra comments...
[dead]