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,logandshow. You can pass them as revisions. - Item sequences appear in
synck versionsand--eventsoutput. You select file versions with--item-seq. - Repository sequences are the numbers at the start of each
logentry. You use them as revisions in commands such asshowanddiff, and with--throughinsynck 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:
- Hash each event’s canonical bytes with SHA-256.
- 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. - Build the commit header and write it as canonical JSON.
- 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 - 1is always the commit beforeN. - 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 finalizecompletes.
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.