Formats and compatibility

Synck 0.2 and 0.3 use one repository format, format 7. This page helps you tell what a particular repository directory holds, choose the matching commands, and understand what changes between releases.

What do I have?

Look at .synck/config.json, and at what else is in and beside .synck:

config.json Other signs What it is Use
"authority":"INDEPENDENT_LOCAL" .synck/checkout.json, and files beside .synck A repository with a checkout, from synck init or synck repository checkout Synck basics
an origin entry No repository.sqlite3 in .synck, unless it also says "hold":true A clone: another working tree of the repository at origin Clones and alternatives
"authority":"FOLLOWER" Nothing beside .synck An export or copy, read-only Reading
"authority":"LOCAL" An activated repository Taking over

storage_mode says how content is stored, CHUNKED or WHOLE_FILE. It does not change which commands apply. See Storage space.

Which commands go with which

With a checkout Without a checkout
Inspect changes status, diff —
Record changes commit, mv, duplicate, adopt, and the repository write commands create-file, save-file, duplicate, import-email, create-chat, append-chat once activated
Work side by side clone, pull, push, resolve —
Read history log, show, history, versions, item ..., repository log item ... --through, repository log
Verify fsck or repository verify repository verify DIRECTORY
Back up archive or repository archive repository archive --path DIRECTORY

Commands that work on files refuse a repository without a checkout, and say what to do instead:

synck: this is a complete repository without a checkout; read it with synck item and synck repository commands (synck repository log lists its history), or enable file editing with synck repository checkout

Similar names, different operations

A few command names are close enough to confuse:

Command What it produces
synck repository import SOURCE NEW A verified copy of a repository. No new commit
synck export PATH NEW One file’s committed content, by path
synck item export ITEM NEW One file’s content by path or item ID, or an email’s original message by item ID
synck repository import-email FILE An email record in the repository, from an .eml or .msg file
synck export-tree REVISION NEW Plain files and folders at a revision, without history
synck archive NEW and synck repository archive NEW Another repository, ready to open
synck clone REPOSITORY NEW Another working tree of the same repository, sharing its history
synck duplicate PATH NEW_PATH A copy of a file or folder inside the same repository, with a new identity

Other format versions

Before 1.0, each release reads only its own repository format. Format 6 belongs to Synck 0.1; format 7 to Synck 0.2 and 0.3. A directory in any other format is refused, and nothing in it is changed:

synck: unsupported repository format 6; Synck 0.3.0 requires format-7. Open format 6 with Synck 0.1.x, export its working files, and initialize a new repository with this release.

There is no converter. To carry the files of a format-6 repository forward, use Synck 0.1 to write its latest tree to a new directory, with synck export-tree HEAD ../plain-files. Then use the current release to run synck init and synck commit in that directory. The files’ bytes transfer; the old history, chats, email, item identities and named versions do not. Keep the original repository, and a Synck 0.1 binary to read it, if those matter.

Synck 0.3 opens repositories written by 0.2 unchanged. A chunked repository’s object store is the exception: 0.3 upgrades it to version 2 when it first opens it, and Synck 0.2 cannot open a store that 0.3 has written. Repositories written by untagged development builds are disposable.

A format-7 configuration without storage_mode is read as WHOLE_FILE, and opening it does not rewrite the file.

Never change format_version or storage_mode by hand to make a command accept a directory. That changes nothing about the data and bypasses every check.

Separate version numbers

Several independent things carry version numbers, and they do not move together:

Version Example Changes when
The Synck release synck 0.3.0 Any release
Repository format format_version 7 in config.json The on-disk layout changes
Commit header format format_version 6 inside every commit The way a commit ID is computed changes; see Commit identity
Object store version 2 in object-store.sqlite3 The chunk database changes
JSON output schema "schema_version": 5 The shape of --json output changes

A new release of the tool does not, by itself, change any of the others.

Compatibility promises

Synck is pre-1.0. Each release reads only its own repository format, as described above, and the Rust interfaces of its library may still change between releases. Within a format, stored data is held to a stricter standard:

  • Accepted history is never rewritten by an upgrade. Commit IDs, event bytes, item IDs and content hashes stay exactly as they are.
  • Formats change only explicitly, with a new version number, never by reinterpreting existing data. An upgrade within a format, such as the object store’s, is automatic and never drops data.
  • Unknown data is reported, not discarded. A reader that meets an event or item type it does not understand says so, and still preserves, verifies and copies it.
  • The canonical encodings are tested. The source ships canonical test vectors for events, commits and the file profile. Implementations, including future versions of Synck itself, must reproduce them byte for byte.

Use synck --help to confirm which commands your installed binary has. A locally built binary from an older checkout can report the same version number and still lack newer commands.