Re: Gerrit, GitButler, and Jujutsu projects collaborating on change-id commit footer

From: Patrick Steinhardt <ps@pks.im>
Date: Apr 3, 2025, 09:09 UTC
Message-ID: <Z-5QR57zgSsm6jNP@pks.im>
In-Reply-To: <CAESOdVAspxUJKGAA58i0tvks4ZOfoGf1Aa5gPr0FXzdcywqUUw@mail.gmail.com>

Hi Martin,

On Wed, Apr 02, 2025 at 11:48:01AM -0700, Martin von Zweigbergk wrote:

Show 19 quoted lines

> Hi,
> 
> The Gerrit, GitButler, and Jujutsu projects all have a concept of
> a "change id", and it behaves in a similar way between the three
> tools. The change id is conceptually associated with a commit.
> It follows a commit as its rewritten (e.g. by amending and
> rebasing). The three projects currently store and format the
> change id differently. We would like to unify that so we can
> interoperate better. We hope the Git project is also interested
> in preserving and using this header.
> 
> There are many benefits to having a change id even if it's just
> local. I mentioned some in my email to this mailing list in [1].
> For example, it enables
> `git rebase main <change ID>; git switch <change ID>` without
> requiring the user to look up the hash of the rewritten commit.
> If the change id also transferred between repos and preserved by
> a forge (such as Gerrit), it enables the change id to be used to
> identify a code review.

Agreed, change IDs solve a couple of issues that many users face:

  - You can reliably track how a patch evolves over time. This helps
    various different tools to track identity of commits, like for
    example forges, but also tools like git-range-diff(1).

  - It becomes trivial to see whether a commit has been cherry-picked
    into another branch. We do have git-cherry(1) to do that right now,
    but that command is based on heuristics and fails as soon as the
    patch itself needed to be adapted.

  - Working with history rewrites becomes easier in the general case as
    you don't have to adapt to constantly changing commit IDs.

The mere fact that different tools eventually ended up with similar designs around change IDs is a good indicator that there is a real need for them out there.

Show 25 quoted lines

> Here's how the change ids are currently stored and formatted:
> 
>  * Gerrit currently stores change ids in a commit trailer called
>    `Change-Id`. It always starts with the letter 'I' and is
>    followed by 40 hex digits. For example:
>    `Change-Id: Ib563e78c3fedcff262255fa025441daa3202311b`.
> 
>  * GitButler currently stores change ids in a commit footer
>    called `gitbutler-change-id` (older versions used
>    `change-id`). It's written as 32 hex digits separated by
>    dashes as in the UUID  format. For example:
>    `gitbutler-change-id  7d0fbc63-032d-413c-8ae8-610fbeb713c0`.
> 
>  * Jujutsu currently stores change ids in a local storage outside
>    of the Git repo and is therefore not part of the Git commit
>    id. It is stored as 16 bytes. It is rendered to the user as
>   "reverse hex" using 'z' through 'k' as hex digits ('z' = 0,
>   'k' = 15). This allows even short prefixes to be distinguished
>    from commit  ids, which is a very useful property when used in
>    the CLI.
> 
> As mentioned, the three projects would like to use the same
> storage and format. I think we have a consensus to store it in a
> Git commit header called `change-id` as a 32 reverse-hex digis.
> For example: `change-id ywlktllmukprnxnmzzprukpuwyztylwt`.

I don't mind the actual format too much at this point, so I won't comment on this part.

Show 10 quoted lines

> There is a design doc [2] about the impact on Gerrit and how to
> handle various cases where the client doesn't understand the
> `change-id` header. That also includes some discussion about
> whether cherry-picking should preserve the change id or create a
> new one. I think there is a lot of value in having a
> standardized header regardless of what we decide about
> cherry-picks.
> 
> So, to be clear, this is mostly a heads up at this point; we don't
> depend on any immediate changes from the Git project.

Scott has already been reaching out to me before your mail, and I also mentioned to him that I have been thinking about the problem of change IDs for quite a while already. This has mostly been triggered by Jujutsu and how it uses change IDs, which is one of the good improvements over Git from my perspective.

While there may not be a need to do anything in Git itself I would think that supporting change IDs natively in Git would still be sensible. Sure, you can emulate them via commit trailers. But I don't consider trailers to be particularly great as a storage format for this metadata. After all, you will want to filter the commit graph by change ID for some of the usecases, and doing that based on a loosely-defined format probably isn't great.

So what would it take to get change IDs into Git? I think the most important items would be:

  - Generating and writing change IDs in commands that support them.
    This includes e.g. git-commit(1), git-commit-tree(1), git-merge(1),
    git-merge-tree(1). This should of course be completely optional and
    probably be disabled by default.

  - Making tools that rewrite commits aware of change IDs so that they
    know to retain change IDs. This involves e.g. git-cherry-pick(1),
    git-rebase(1), git-replay(1).

  - Extending revisions to allow specifying commits by change ID.

  - Allowing us to filter commit graphs by change ID.

I don't think any of these should be particularly hard to do. Sure, addressing and filtering commits by change IDs would be slowish at first because we have to basically read all commits, but this is something that can be sped up via indices.

The biggest question is of course backwards compatibility -- can we introduce a change ID into the commit metadata without breaking existing users? I guess you'll already have a lot of experience with this given that you essentially already inject change IDs into metadata, and tools generally handle this just fine?

I'd certainly be happy to help out with an effort to introduce change IDs into Git if the community is amenable to such a proposal.

Patrick

NB: I'm also quite happy that Jujutsu brings a bit of a new contender
    to Git into the picture. It has a lot of nice ideas, and in the best
    case Git might be able to learn a few nice tricks from JJ. After
    all, I think we can all benefit from some friendly competition.