Object IDs and hashing

In short: the server computes every content ID, in server/src/hash_utils.rs. Files, trees and commits get Git object IDs (20-byte SHA-1), built with the gix crate. Operations and views get the first 16 bytes of a SHA-1 over a custom length-prefixed encoding. The client computes none of them: it takes whatever ID the write RPC returns. Trees and files get the same IDs jj's GitBackend would give them. Commits never do, because the change-id header is spelled differently. Several jj-only commit fields, such as conflict terms beyond the first, predecessors and signatures, aren't hashed at all. Two different jj commits can therefore share an ID, and the second write silently replaces the first.

This page describes upstream at the pinned commit with jj-lib 0.43.0 and gix 0.68.0 (server/Cargo.toml). For how jj itself names objects, see /jj/commits, /jj/trees and /jj/operations. Those pages describe jj's own pinned version, which is newer than 0.43.0.

Every ID

The lengths come from the shared constants in common/src/lib.rs, which the client reports to jj-lib through commit_id_length and change_id_length (source). Every ID travels as raw bytes in the protos. jj displays commit, operation and view IDs as lowercase hex, and change IDs in its reversed z–k alphabet.

The root IDs aren't hashes of anything. They're agreed constants: no root commit, operation or view is ever written to the server, and both sides recognise the all-zero IDs on read. Operation and view IDs are 16 bytes here. jj's own SimpleOpStore uses 64 (simple_op_store.rs).

Git-compatible hashing

All three Git hashes end in the same call, gix::objs::compute_hash(Kind::Sha1, kind, &buf). It hashes Git's object header ("<kind> <decimal length>\0") followed by buf, exactly as git hash-object does. Only how buf is built differs.

Files: compute_git_blob_hash

Lines 89–93. buf is the file content, unchanged. The client reads the whole file into memory and sends it in a single WriteFile (source), so the ID is exactly git hash-object of the file. Executability isn't part of the blob. It lives in the tree entry.

Trees: compute_git_tree_hash

Lines 95–143. For each TreeEntry in the request:

1. Pick a Git mode and a 20-byte object ID from the entry's value (lines 101–120):

   Value	gix EntryKind	Mode written	ID used
   File, executable = false	Blob	100644	the file ID
   File, executable = true	BlobExecutable	100755	the file ID
   TreeId	Tree	40000	the subtree ID
   SymlinkId	Link	120000	the symlink ID
   ConflictId, or no value at all	Blob	100644	20 zero bytes

   The File's copy_id is never hashed.
2. Convert the ID with gix::hash::ObjectId::try_from. If it isn't exactly 20 bytes, the entry is silently dropped from the hash, though it's still stored with the tree (lines 121–127).
3. Sort the gix::objs::tree::Entry values with sort_unstable, which uses Git's tree order: a directory sorts as if its name ended in /. So a.txt comes before directory a, which comes before a0 (lines 130–131).
4. Serialise the gix::objs::Tree with WriteTo: for each entry, the mode in ASCII, a space, the name, a NUL byte, then the 20 raw ID bytes. Hash that as Kind::Tree (lines 133–142).

The client never sends a ConflictId. Trees in jj-lib 0.43.0 have no conflict values, and tree_entry_to_proto refuses only Git submodules (source). The zero-ID fallback is reached only by a request that some other client built.

Commits: compute_git_commit_hash

Lines 42–87 build a gix::objs::Commit from the proto Commit, then serialise it with WriteTo and hash it as Kind::Commit. Field by field:

WriteTo lays these out in Git's order: tree, each parent, author, committer, the extra headers, a blank line, then the message. A signature line is name <email> seconds ±hhmm.

Worked example: a one-file commit

A commit whose only parent is the root, containing one file hello.txt with the six bytes hello\n. Author and committer are both Alice <alice@example.com> at 1759492800 seconds in UTC−4. The change ID is the bytes 10 11 … 1f and the description is Add hello\n. The client writes the file, then the tree, then the commit, and the server hashes each. Every ID below was computed by running the same gix 0.68.0 calls as hash_utils.rs, and checked with git hash-object.

Change any field the commit hash ignores, such as the predecessors, a second tree term or the milliseconds of a timestamp, and the ID stays 2b6bbf38…. With an empty author and committer name, both lines read JJ_EMPTY_STRING <alice@example.com> and the ID becomes c020c94bcb0ed4afe8a748df01d35c352b2a5995.

Operations and views

Operations and views have no Git equivalent, so hash_utils.rs serialises them by hand into a byte buffer, then hashes that buffer as if it were a Git blob: compute_hash(Sha1, Kind::Blob, &buf), which is SHA-1 over "blob <len>\0" plus the buffer. It keeps the first 16 bytes (OPERATION_ID_LENGTH, VIEW_ID_LENGTH).

The length-prefix helpers

append_length_prefixed_bytes writes the byte count as an 8-byte little-endian u64, then the bytes. append_length_prefixed_str does the same for a string's UTF-8 bytes. The doc comment gives the reason: without a length, two adjacent fields "foo" + "bar" and "foob" + "ar" would produce the same bytes. With it, a reader always knows where one variable-length field ends and the next begins. Fixed-width fields (the two i64 times and the is_snapshot byte) are written raw, little-endian. Maps are walked in sorted key order (via a BTreeMap or an explicit sort), because protobuf map iteration order isn't fixed (line 145).

hash_operation

Lines 146–176. Field by field, in this order:

commit_predecessors_set (whether jj recorded predecessors at all) isn't hashed, so an operation with no predecessor map and one with an empty map get the same ID. The metadata's time-zone offsets never reach the server: the proto has no field for them, and the client reads them back as zero (source).

hash_view

Lines 178–225, in this order, with no counts anywhere:

1. head_ids, sorted, each length-prefixed.
2. wc_commit_ids sorted by workspace name: the name, then the commit ID, both length-prefixed.
3. local_bookmarks sorted by name: the name, then the target's removes (sorted), then its adds (sorted), each commit ID length-prefixed.
4. remote_bookmarks sorted by key: the key, is_tracked as one byte, then the target as above if there is one.

How far the encoding avoids ambiguity

Length prefixes make each field unambiguous, which is the case the doc comment guards against. They don't make the whole buffer unambiguous. Neither function writes how many items a list or map holds, or which section an item belongs to, and the optional workspace name has no presence flag. So two different values can serialise to identical bytes, and therefore share an ID. Both cases below were checked by reimplementing the two functions byte for byte:

• Views. View A has one workspace, default, at commit W, and no bookmarks. View B has no workspaces and a local bookmark named default at W. Both have head W. A's working-copy section and B's bookmark section write the same two fields, so the bytes match (diagram below).
• Operations. One operation has workspace A, the attribute B = C and no predecessors. Another, otherwise identical, has no workspace, the attribute A = B, and a predecessor entry for a commit whose ID is the three bytes C. Each writes the same three length-prefixed strings in a row.

Both examples need unusual inputs, and nothing in normal jj use is known to produce them. The consequence would be the same as for commits, though: the server stores by ID with a plain map insert, so the second write replaces the first. Writing a count before each list, and a presence byte before the workspace name, would close the gap.

Agreement with the client

The client never computes a content hash. Every write method sends the object and builds its ID from the bytes the server returns: files (line 305), trees (line 395), commits (lines 458–459), views (line 294) and operations (line 335). Nothing checks a returned ID's length or recomputes it. For commits, commit_to_proto always sends an empty commit_id (source). The server hashes only when that field is empty, and otherwise stores the commit under whatever ID the request names (source). This client never takes that path, but the server doesn't verify anyone who does.

The client does assume four IDs without asking the server. Each must match what the server does:

The server rebuilds every ID from content. So two clients that write the same file, tree or commit get the same ID, and the second write replaces an identical entry. jj-lib keeps the Commit value it passed in, not one read back from the server, as the client returns it unchanged alongside the server's ID (source).

Compared with jj's GitBackend

jj-lib's GitBackend also writes commits, trees and blobs as Git objects with gix, so the formats look alike. For jj's own backends, see /jj/backends, which describes jj's own pinned version. The comparison here is against git_backend.rs at v0.43.0, the version this project builds against.

A repository moved between the two backends would keep its file and tree IDs, but every commit would get a new ID.

Edge cases

No upstream test targets hash_utils.rs. The server's only test checks that it starts, and the CLI tests reach the hashing only indirectly. The one ID they assert is the root commit's 40 zeros (source). None of the behaviour above is pinned by a test.