# Change ids

> Stable change identifiers on commits, Git interop, and revision selection.

Every commit [`grit commit`](https://grit-scm.com/docs/commit/index.md) creates can carry a **`change-id`** header: an opaque token that names the same logical change across rewrites (amend, [`grit history`](https://grit-scm.com/docs/history/index.md) 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 any `gpgsig` block).
- Legacy name: `gitbutler-change-id <value>` is still read for compatibility; new writes use `change-id` only.
- Random ids use **reverse-hex**: 16 bytes encoded as 32 characters in the alphabet `k`–`z` (each nibble `n` maps 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`](https://grit-scm.com/docs/config/index.md) | `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:

```console
$ grit config grit.changeIds false
```

## Display and JSON

**Human [`grit log`](https://grit-scm.com/docs/log/index.md)** (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`](https://grit-scm.com/docs/log/index.md) omits the change column.

**[`--json`](https://grit-scm.com/docs/commands/README.md/index.md#commit-json-object-commitjson)** on [`log`](https://grit-scm.com/docs/log/index.md), [`show`](https://grit-scm.com/docs/show/index.md), [`revs`](https://grit-scm.com/docs/revs/index.md), and [`status`](https://grit-scm.com/docs/status/index.md) 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`](https://grit-scm.com/docs/commit/index.md), [`pick`](https://grit-scm.com/docs/pick/index.md), [`revert`](https://grit-scm.com/docs/revert/index.md), [`merge`](https://grit-scm.com/docs/merge/index.md), [`pull`](https://grit-scm.com/docs/pull/index.md), [`history`](https://grit-scm.com/docs/history/index.md)) report `change_id` on the commits they create. [`grit commit --json`](https://grit-scm.com/docs/commit/index.md) 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 stored `change-id` equal 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`, matches [`resolved_change_id`](https://docs.rs/grit-lib/latest/grit_lib/change_id/fn.resolved_change_id.html) (stored or derived), and requires a unique prefix.
- **Composition:** suffixes work as usual — `\<cid\>~1`, `\<cid\>^`, ranges, peel operators, and `:path` forms compose on the resolved commit.
- **Precedence:** a branch or tag with the same name wins over a change-id token.

Examples:

```console
$ 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](https://grit-scm.com/docs/library/change-ids/index.md) (`ChangeId`, `ChangeIdPolicy`, header helpers, and lookup).
