https://dotat.at/@/2025-09-11-cover-letter.html
Although it looks really good, I have not yet tried the Jujutsu (jj)
version control system, mainly
because it's not yet clearly superior to Magit.
But I have been following jj discussions with great interest.
One of the things that jj has not yet tackled is how to do better than
git refs / branches / tags. As I underestand it, jj currently has
something like Mercurial bookmarks, which are more like raw git ref
plumbing than a high-level porcelain feature. In particular, jj lacks
signed or annotated tags, and it doesn't have branch names that
always automatically refer to the tip.
This is clearly a temporary state of affairs because jj is still
incomplete and under development and these gaps are going to be
filled. But the discussions have led me to think about how git's
branches are unsatisfactory, and what could be done to improve them.
branch
One of the huge improvements in git compared to Subversion was git's
support for merges. Subversion proudly advertised its support for
lightweight branches, but a branch is not very useful if you can't
merge it: an un-mergeable branch is not a tool you can use to help
with work-in-progress development.
The point of this anecdote is to illustrate that rather than trying to
make branches better, we should try to make merges better and branches
will get better as a consequence.
Let's consider a few common workflows and how git makes them all
unsatisfactory in various ways. Skip to cover
letters and previous branch below
where I eventually get to the point.
merge
A basic merge workflow is,
- create a feature branch
- hack, hack, review, hack, approve
- merge back to the trunk
The main problem is when it comes to the merge, there may be conflicts
due to concurrent work on the trunk.
Git encourages you to resolve conflicts while creating the merge
commit, which tends to bypass the normal review process. Git also
gives you an ugly useless canned commit message for merges, that hides
what you did to resolve the conflicts.
If the feature branch is a linear record of the work then it can be
cluttered with commits to address comments from reviewers and to fix
mistakes. Some people like an accurate record of the history, but
others prefer the repository to contain clean logical changes that
will make sense in years to come, keeping the clutter in the code
review system.
rebase
A rebase-oriented workflow deals with the problems of the merge
workflow but introduces new problems.
Primarily, rebasing is intended to produce a tidy logical commit
history. And when a feature branch is rebased onto the trunk before it
is merged, a simple fast-forward check makes it trivial to verify that
the merge will be clean (whether it uses separate merge commit or
directly fast-forwards the trunk).
However, it's hard to compare the state of the feature branch before
and after the rebase. The current and previous tips of the branch
(amongst other clutter) are recorded in the reflog of the person who
did the rebase, but they can't share their reflog. A force-push erases
the previous branch from the server.
Git forges sometimes make it possible to compare a branch before and
after a rebase, but it's usually very inconvenient, which makes it
hard to see if review comments have been addressed. And a reviewer
can't fetch past versions of the branch from the server to review them
locally.
You can mitigate these problems by adding commits in --autosquash
format, and delay rebasing until just before merge. However that
reintroduces the problem of merge conflicts: if the autosquash doesn't
apply cleanly the branch should have another round of review to make
sure the conflicts were resolved OK.
squash
When the trunk consists of a sequence of merge commits, the
--first-parent log is very uninformative.
A common way to make the history of the trunk more informative, and
deal with the problems of cluttered feature branches and poor rebase
support, is to squash the feature branch into a single commit on the
trunk instead of mergeing.
This encourages merge requests to be roughly the size of one commit,
which is arguably a good thing. However, it can be uncomfortably
confining for larger features, or cause extra busy-work co-ordinating
changes across multiple merge requests.
And squashed feature branches have the same merge conflict problem as
rebase --autosquash.
fork
Feature branches can't always be short-lived. In the past I have
maintained local hacks that were used in production but were not (not
yet?) suitable to submit upstream.
I have tried keeping a stack of these local patches on a git branch
that gets rebased onto each upstream release. With this setup the
problem of reviewing successive versions of a merge request becomes
the bigger problem of keeping track of how the stack of patches
evolved over longer periods of time.
cover letters
Cover letters are common in the email patch workflow that predates
git, and they are supported by git format-patch. Github and other
forges have a webby version of the cover letter: the message that
starts off a pull request or merge request.
In git, cover letters are second-class citizens: they aren't stored in
the repository. But many of the problems I outlined above have neat
solutions if cover letters become first-class citizens, with a Jujutsu
twist.
A first-class cover letter starts off as a prototype for a merge
request, and becomes the eventual merge commit.
Instead of unhelpful auto-generated merge commits, you get helpful
and informative messages. No extra work is needed since we're
already writing cover letters.
Good merge commit messages make good --first-parent logs.
The cover letter subject line works as a branch name. No more need
to invent filename-compatible branch names!
Jujutsu doesn't make you name branches, giving them random names
instead. It shows the subject line of the topmost commit as a
reminder of what the branch is for. If there's an explicit cover
letter the subject line will be a better summary of the branch as
a whole.
I often find the last commit on a branch is some post-feature
cleanup, and that kind of commit has a subject line that is never
a good summary of its feature branch.
As a prototype for the merge commit, the cover letter can contain
the resolution of all the merge conflicts in a way that can be
shared and reviewed.
In Jujutsu, where conflicts are first class, the cover letter
commit can contain unresolved conflicts: you don't have to clean
them up when creating the merge, you can leave that job until
later.
If you can share a prototype of your merge commit, then it becomes
possible for your collaborators to review any merge conflicts and
how you resolved them.
To distinguish a cover letter from a merge commit object, a cover
letter object has a "target" header which is a special kind of parent
header. A cover letter also has a normal parent commit header that
refers to earlier commits in the feature branch. The target is what
will become the first parent of the eventual merge commit.
previous branch
The other ingredient is to add a "previous branch" header, another
special kind of parent commit header. The previous branch header
refers to an older version of the cover letter and, transitively, an
older version of the whole feature branch.
Typically the previous branch header will match the last shared
version of the branch, i.e. the commit hash of the server's copy of
the feature branch.
The previous branch header isn't changed during normal work on the
feature branch. As the branch is revised and rebased, the commit hash
of the cover letter will change fairly frequently. These changes are
recorded in git's reflog or jj's oplog, but not in the "previous
branch" chain.
You can use the previous branch chain to examine diffs between
versions of the feature branch as a whole. If commits have
Gerrit-style or jj-style change-IDs then it's fairly easy to find and
compare previous versions of an individual commit.
The previous branch header supports interdiff code
review,
or allows you to retain past iterations of a patch series.
workflow
Here are some sketchy notes on how these features might work in
practice.
One way to use cover letters is jj-style, where it's convenient to
edit commits that aren't at the tip of a branch, and easy to reshuffle
commits so that a branch has a deliberate narrative.
When you create a new feature branch, it starts off as an empty
cover letter with both target and parent pointing at the same
commit.
Alternatively, you might start a branch ad hoc, and later cap it
with a cover letter.
If this is a small change and rebase + fast-forward is allowed,
you can edit the "cover letter" to contain the whole change.
Otherwise, you can hack on the branch any which way. Shuffle the
commits that should be part of the merge request so that they
occur before the cover letter, and edit the cover letter to
summarize the preceding commits.
When you first push the branch, there's (still) no need to give it
a name: the server can see that this is (probably) going to be a
new merge request because the top commit has a target branch and
its change-ID doesn't match an existing merge request.
Also when you push, your client automatically creates a new
instance of your cover letter, adding a "previous branch" header
to indicate that the old version was shared. The commits on the
branch that were pushed are now immutable; rebases and edits
affect the new version of the branch.
During review there will typically be multiple iterations of the
branch to address feedback. The chain of previous branch headers
allows reviewers to see how commits were changed to address
feedback, interdiff style.
The branch can be merged when the target header matches the
current trunk and there are no conflicts left to resolve.
When the time comes to merge the branch, there are several options:
For a merge workflow, the cover letter is used to make a new
commit on the trunk, changing the target header into the first
parent commit, and dropping the previous branch header.
Or, if you like to preserve more history, the previous branch
chain can be retained.
Or you can drop the cover letter and fast foward the branch on to
the trunk.
Or you can squash the branch on to the trunk, using the cover
letter as the commit message.
questions
This is a fairly rough idea: I'm sure that some of the details won't
work in practice without a lot of careful work on compatibility and
deployability.
Do the new commit headers ("target" and "previous branch") need to
be headers?
What are the compatibility issues with adding new headers that
refer to other commits?
How would a server handle a push of an unnamed branch? How could
someone else pull a copy of it?
How feasible is it to use cover letter subject lines instead of
branch names?
The previous branch header is doing a similar job to a remote
tracking branch. Is there an opportunity to simplify how we keep a
local cache of the server state?
Despite all that, I think something along these lines could make
branches / reviews / reworks / merges less awkward. How you merge
should me a matter of your project's preferred style, without
interference from technical limitations that force you to trade off
one annoyance against another.
There remains a non-technical limitation: I have assumed that
contributors are comfortable enough with version control to use a
history-editing workflow effectively. I've lost all perspective on how
hard this is for a newbie to learn; I expect (or hope?) jj makes it
much easier than git rebase.
![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
jack
