Every commit grit commit creates can carry a change-id header: an opaque token that names the same logical change across rewrites (amend, grit history edits, and future rebases). Commits that never received the header still have a derived id (Jujutsu-compatible) computed from the commit object id. Grit never rewrites a commit solely to add a header.
Header format
- On disk: a normal commit header line
change-id <value>(before anygpgsigblock). - Legacy name:
gitbutler-change-id <value>is still read for compatibility; new writes usechange-idonly. - Random ids use reverse-hex: 16 bytes encoded as 32 characters in the alphabet
k–z(each nibblenmaps to'z' - n).
System git treats the line like any other commit header: it round-trips through clone and fetch, survives git cat-file -p, and passes git fsck --strict. Git’s %(trailers) pretty-format does not surface change-id (it is not a Git trailer), so use cat-file or grit’s JSON when you need the stored value.
Interop with Jujutsu, GitButler, and Gerrit
| Tool | How it relates |
|---|---|
Jujutsu (jj) |
Derives a change id from the commit id with the same algorithm grit uses when no header is present. After grit stores a derived id on rewrite, jj and grit agree on the logical change. |
| GitButler | Historically wrote gitbutler-change-id; grit reads that name and writes change-id on new commits. Stacks and virtual branches can key off the same string grit shows in log and --json. |
| Gerrit | Uses Change-Id in the commit message for review matching. Grit’s header is separate (object header, not message footer). Repos imported from Gerrit keep their message trailers; grit adds its own header only on commits it creates. |
Configuration
| Key | Default | Effect |
|---|---|---|
grit.changeIds |
true |
When false, new commits omit the header (byte-identical with plain Git). Existing headers are preserved; history rewrites still copy them but do not invent derived ids. |
grit.testing.changeId |
unset | Test-only: content-hash makes ids deterministic; any other non-empty value is used verbatim. |
Disable headers when an importer rejects extra commit lines:
$ grit config grit.changeIds false
Display and JSON
Human grit log (default format) shows the short commit id, then change and the first eight reverse-hex characters of the stable id, then author, date, and subject. --oneline omits the change column.
--json on log, show, revs, and status includes:
| Field | Meaning |
|---|---|
change_id |
Stable id (stored header or derived from oid). |
change_id_stored |
true when change_id came from a change-id / gitbutler-change-id header in the object. |
Mutation commands (commit, pick, revert, merge, pull, history) report change_id on the commits they create. grit commit --json sets change_id to the stored header value or JSON null when the header is absent (for example with grit.changeIds=false).
Which commits get ids
- New ids: ordinary commits, the initial commit, merge conclusions, pick, revert, and commits inserted during a history rewrite.
- Same id kept: amend, history reword/fixup/squash/drop/replay when the logical change survives.
- Derived id stored on rewrite: headerless commits (for example from plain
git commit) receive a storedchange-idequal to the derived value the first time grit rewrites them.
Pick and revert always allocate a new id; they never copy the source commit’s id.
Revisions
After refs and abbreviated object ids, grit accepts change ids as revision tokens:
- Alphabet: reverse-hex tokens use
k–z, length 4–32. Such tokens are resolved as change-id prefixes, not Git object ids. - Lookup: grit walks commits reachable from refs and
HEAD, matchesresolved_change_id(stored or derived), and requires a unique prefix. - Composition: suffixes work as usual —
\<cid\>~1,\<cid\>^, ranges, peel operators, and:pathforms compose on the resolved commit. - Precedence: a branch or tag with the same name wins over a change-id token.
Examples:
$ grit show krrtwksq --json
$ grit log yrwyvtvk -n 1 --json
$ grit history reword krrtwksq -m "new subject"
Ambiguous prefixes fail with a list of candidate commits (same as ambiguous short oids).
Library API
For embedders, see the library guide on change ids (ChangeId, ChangeIdPolicy, header helpers, and lookup).