Formats and compatibility
Every Synck repository uses one format, format 6. 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 whether ordinary files sit beside .synck:
config.json |
Other signs | What it is | Use |
|---|---|---|---|
"authority":"INDEPENDENT_LOCAL" and a checkout entry |
Files beside .synck |
A repository with a checkout, from synck init or synck repository checkout |
Synck basics |
"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, and the repository write commands |
create-file, save-file, create-chat, append-chat once activated |
| 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_ID NEW |
One file’s content, or an email’s original message, by item ID |
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 |
Other format versions
Synck opens format 6 only. A directory with any other format_version is
refused, and nothing in it is changed:
synck: unsupported repository format; format 6 is required
A format-6 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.1.0 |
Any release |
| Repository format | format_version 6 |
The on-disk layout changes |
| Commit header format | format_version 2 to 5 inside a commit |
A commit carries different kinds of content; see Commit identity |
| 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 0.1 is the first public release, and its library API is pre-1.0: Rust interfaces may still change between releases. 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 through explicit, versioned migrations, such as automatic in-place upgrades that are safe to repeat, or verified copies into a new destination. A migration never silently 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.