Commit identity and the three coordinates

Synck uses three different kinds of number to talk about history, and mixing them up is the most common source of confusion. This page explains each one, and shows you how to compute a commit ID yourself, so you can see that there is nothing hidden in it.

Three coordinates, three questions

Coordinate Example Question it answers
Commit ID sha256:009693a7…a31008 Which change is this, exactly?
Item sequence (item_seq) 2 Where is this event in one item’s history?
Repository sequence (repo_seq) 3 Where was this commit placed in this repository’s overall history?

The example is the edit that moved the meeting to 11 in Your first repository: the second event in the notes file’s history, recorded in the repository’s third commit. In a small repository the two sequences can look related, but that is a coincidence, and it ends as soon as more than one item is involved. In the sample repository, the third message in the chat is the chat’s event 5 but the repository’s commit 8.

Where you meet them:

  • Commit IDs are printed by commit, log and show. You can pass them as revisions.
  • Item sequences appear in synck versions and --events output. You select file versions with --item-seq.
  • Repository sequences are the numbers at the start of each log entry. You use them as revisions in commands such as show and diff, and with --through in synck item.

Computing a commit ID by hand

A commit ID is a SHA-256 hash of a small JSON header, and the header contains a hash of the commit’s events. Here is commit 3 from Your first repository, with its one event:

$ synck show 3 --events
3 | 2026-11-04T00:19:26.346268+00:00 | Alex | 1 change | 1 event | Move the meeting to 11
    commit sha256:009693a7d491a1d9108824055563103bc580b528f532b47d0b2d889b9ba31008
    0 | FILE::SET_CONTENT | item 01a1a3ec-c77c-71da-b4aa-47c7536b1e50 | item-seq 2
        {"base_seq":1,"event_type":"FILE::SET_CONTENT","item_id":"01a1a3ec-c77c-71da-b4aa-47c7536b1e50","metadata_id":"sha256:27be5e44fce5544bce742a19e84223e6a7bf90d577023113b074620cfba1061c","set_content":{"bytes":"sha256:54b5e89382d5bd75aaad652ca43cc9b844e1b5f8b73a0aac462a9b20a2bb731a"}}

The JSON line is the event’s canonical form, the exact bytes Synck hashes and stores. The recipe is:

  1. Hash each event’s canonical bytes with SHA-256.
  2. Put one byte in front of each hash, 0 for an item event and 1 for a ref event, and hash the concatenation, in order: that is the events_digest.
  3. Build the commit header and write it as canonical JSON.
  4. Hash the header. That is the commit ID.

As a short Python script, commit_id.py:

import hashlib, json, sys

# Usage: synck show REVISION --events | python3 commit_id.py AUTHOR "MESSAGE"
author, message = sys.argv[1], sys.argv[2]
events = [line.strip().encode() for line in sys.stdin if line.strip().startswith("{")]

# Each event's hash, after one byte: 0 for an item event, 1 for a ref event.
def family(event):
    return b"\x01" if "owner_item_id" in json.loads(event) else b"\x00"

framed = b"".join(family(e) + hashlib.sha256(e).digest() for e in events)
header = {
    "object_type": "vcs_commit",
    "format_version": 6,
    "author_id": author,
    "committer_id": author,
    "occurred_at": None,
    "message": message,
    "event_count": len(events),
    "events_digest": "sha256:" + hashlib.sha256(framed).hexdigest(),
}
canonical = json.dumps(header, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
print(canonical)
print("sha256:" + hashlib.sha256(canonical.encode()).hexdigest())

Run it:

$ synck show 3 --events | python3 commit_id.py Alex "Move the meeting to 11"
{"author_id":"Alex","committer_id":"Alex","event_count":1,"events_digest":"sha256:59ca544d672bf1e14bc8799568f188dd813b2f61e7b62e004c54c3b7ce06082d","format_version":6,"message":"Move the meeting to 11","object_type":"vcs_commit","occurred_at":null}
sha256:009693a7d491a1d9108824055563103bc580b528f532b47d0b2d889b9ba31008

The result is the commit ID Synck printed. It works for commits with several events, and for commits with ref events, too. Commit 1 created .synckignore and its first named version:

$ synck show 1 --events | python3 commit_id.py Alex "Initialize Synck repository"
...
sha256:e1ec96111cce5fc03af27e5e1b8959c80a4c112d7c874b81cf4a6c996cbc30fb

The file content is identified the same way. The bytes entry in the event is the SHA-256 of the file’s bytes:

$ printf 'Meet at 11.\n' | shasum -a 256
54b5e89382d5bd75aaad652ca43cc9b844e1b5f8b73a0aac462a9b20a2bb731a  -

The metadata_id names a small stored record with the file’s size. It is hashed the same way, so it too is fixed by the event.

So the commit ID depends on the event, the event names the content’s hash, and the hash depends on every byte of the file. Change one byte anywhere and the commit ID changes. That chain is what fsck and repository verify walk.

The script is a teaching aid with two simplifications. First, Synck’s canonical JSON is RFC 8785, which agrees with Python’s sorted, compact output for headers like this one but has exact rules for unusual numbers and characters. Second, it assumes the committer is the author and that the commit has no origin timestamp, which is true of every commit the synck tool makes from a working tree.

What is in the hash, and what is not

The commit header contains exactly:

Field
object_type Always vcs_commit, so a commit header can never be mistaken for another kind of hashed object
format_version Which header layout this is: always 6
author_id The author string
committer_id The service or tool that recorded it, as distinct from the author
occurred_at When the change originally happened, if it was recorded somewhere else first, or null
message The message, or null
event_count, events_digest The events, in order

Just as deliberately, these are not part of the ID:

  • the repository ID and the repository sequence;
  • the acceptance time, meaning when this repository recorded the commit;
  • the operation ID, which is used to recognize a retried request.

Each of these omissions is a design decision, explained below.

No parent, no global head

A Git commit names its parent, and through it the entire chain before it. A Synck commit does not. Nothing in its header refers to earlier commits.

That is what lets independent changes to different items be accepted concurrently. If every commit had to name the latest commit before it, every writer in a repository would have to agree on the latest commit, and they would all queue behind one global “head”, even when one is saving a document and the other is posting a chat message. Synck orders each item’s events through that item’s own sequence and base_seq instead. System design follows that through.

The cost is that a commit ID alone does not tell you where the commit sits in history, or even which repository it belongs to. The same content could be accepted in two repositories and have the same ID in both. Placement is the job of the repository sequence.

Repository sequences come afterwards

Commits are accepted first and placed afterwards. A separate step, the sequencer, assigns each accepted commit the next repository sequence, in a way that guarantees anyone scanning the history in sequence order never skips a commit that was accepted earlier. Those numbers are what log shows and what --through selects.

Two consequences:

  • Sequences have no gaps. Positions run 1, 2, 3 and so on, one per commit, and a repository with a gap is invalid. Position N - 1 is always the commit before N.
  • A commit can briefly have no sequence. Between acceptance and sequencing, a commit is part of the history but not yet in the repository’s order. In a local repository that window is a moment, unless the process is interrupted. That is the state synck repository finalize completes.

A hash is not a signature

A commit ID proves what a commit contains. It does not prove who accepted it, or that it belongs to a particular repository: anyone can construct a header with any author and hash it. Proof of authority or inclusion has to come from outside the commit, from the system that accepted it, or from how you received the copy. Author and committer are recorded as separate fields so that “who made this change” and “which system recorded it” can both be preserved, but neither is authenticated by Synck.