Named versions

Every commit that changes a file creates a new version of it, and most of those versions are routine: a typo fixed, a paragraph moved. A few matter more, such as the draft that went to the client, the figures the board approved, or the contract that was signed. Named versions let you mark those, so they stand out from the rest of the file’s history.

If you use SynckHub, these are the same version labels you see there. A complete repository exported from SynckHub carries them too.

Labels, kinds and descriptions

A named version points at one stored version of one file. It has:

a kind, either major or minor;
a label computed from the kinds, such as 0.01, 1.00 or 1.02;
an optional description;
a permanent version ID.

Labels count like this, in order: each major version increments the number before the dot and resets the part after it; each minor version increments the part after the dot. So minor, minor, major, minor gives 0.01, 0.02, 1.00, 1.01.

Because labels are computed, they can change when you promote, demote or remove a version. The version ID never changes. Scripts should use version IDs.

Every new file starts with one

When you commit a new file, Synck automatically gives its first content a minor named version:

$ synck version list proposal/draft.txt
0.01 01a17498-6fed-77b1-b18a-75e7b2e4719c LIVE MINOR INTERNAL 2 1 2026-10-25T19:45:09.619568981+00:00 sha256:87428fc5…cf25c7 2 -

The columns are the label, the version ID, its state, its kind, the label source, the file version it points to (an item sequence, as listed by synck versions), its position in the label history, when that file version was recorded, the content hash (shortened here), the size, and the description (- when there is none).

Naming a version

synck version create labels the file’s current committed content as a minor version, unless you choose otherwise:

$ synck version create proposal/draft.txt --major --description "Sent to client" -m "Mark the version sent to the client"
committed sha256:2468d12061e16cb0d86d2a55e1ce813493d0e0940b189376b1f17d97023aa3fe
$ synck version list proposal/draft.txt
0.01 01a17498-6fed-77b1-b18a-75e7b2e4719c LIVE MINOR INTERNAL 2 1 2026-10-25T19:45:09.619568981+00:00 sha256:87428fc5…cf25c7 2 -
1.00 01a17498-ef27-7602-ad71-753684277e6f LIVE MAJOR INTERNAL 6 2 2026-10-25T19:45:42.185154616+00:00 sha256:9149a163…4c1043 6 Sent to client

--major makes it a major version. Minor is the default.
--description is shown with the version. It describes the version.
-m is the commit message. It explains this change to the history.
--item-seq N labels an earlier version instead of the current one.

Each version of a file can carry at most one label:

$ synck version create proposal/draft.txt --item-seq 6 -m "Name it again"
synck: file revision 6 already has a live named version

Naming a version is recorded as a commit, so it appears in the log, but it does not change the file. The commit shows 0 changes because no file or folder changed:

$ synck log -n 1
13 | 2026-10-25 20:45 +01:00 | Alex | 0 changes | Mark the version sent to the client

Changing a named version

Each of these records a commit and leaves the file itself untouched:

$ synck version set-description proposal/draft.txt 01a17498-6fed-77b1-b18a-75e7b2e4719c --description "Original outline" -m "Describe the outline"
$ synck version promote proposal/draft.txt 01a17498-6fed-77b1-b18a-75e7b2e4719c -m "Make the outline a major version"
$ synck version demote proposal/draft.txt 01a17498-6fed-77b1-b18a-75e7b2e4719c -m "Make it minor again"

An empty --description "" clears the description. Promoting and demoting change the kind, and therefore the labels of the versions after it.

Restoring a named version

synck version restore copies a named version’s content into your working tree. It changes the file, not the history, so you review and commit the result like any other edit:

$ synck version restore proposal/draft.txt 01a17498-6fed-77b1-b18a-75e7b2e4719c
restored proposal/draft.txt from named version 01a17498-6fed-77b1-b18a-75e7b2e4719c
$ synck status
M proposal/draft.txt

This replaces your uncommitted edits to that file, if you had any.

Removing a label

synck version tombstone removes a label permanently:

$ synck version tombstone proposal/draft.txt 01a17498-6fed-77b1-b18a-75e7b2e4719c -m "Drop the outline label"
$ synck version list proposal/draft.txt
1.00 01a17498-ef27-7602-ad71-753684277e6f LIVE MAJOR INTERNAL 6 2 2026-10-25T19:45:42.185154616+00:00 sha256:9149a163…4c1043 6 Sent to client

Only the label goes. The file version it pointed to is still in the file’s history and can still be exported or restored by item sequence. The removal itself stays visible with --all:

$ synck version list proposal/draft.txt --all
- 01a17498-6fed-77b1-b18a-75e7b2e4719c TOMBSTONED MINOR INTERNAL 2 4 2026-10-25T19:45:09.619568981+00:00 sha256:87428fc5…cf25c7 2 Original outline
1.00 01a17498-ef27-7602-ad71-753684277e6f LIVE MAJOR INTERNAL 6 2 2026-10-25T19:45:42.185154616+00:00 sha256:9149a163…4c1043 6 Sent to client

A tombstoned label cannot be changed, restored or brought back with revert. If you removed one by mistake, create a new label on the same file version.

How it works

Named versions are stored in a separate ledger attached to the file, its ref ledger, rather than as changes to the file itself. That is why labelling a version does not create a new file version, and why a file’s item sequence does not move when you name, describe or remove one. Items, events and commits shows the underlying events.

Undoing things

Email and chats