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.