Copies, refreshes and trust

A complete repository is only useful as a safeguard if you have a good copy when you need it. This page covers making copies, keeping them current, and deciding how much to trust a copy that came from someone else.

Making a copy

Synck has two commands that copy a complete repository. They produce the same result, a new, ready-to-open complete repository, and differ only in how you name the source:

$ synck repository import launch-project my-copy
{"imported":"my-copy","schema_version":1}
$ synck repository archive /backups/launch-2026-10-25 --path my-copy
{"archive":"/backups/launch-2026-10-25","schema_version":1}

import SOURCE DESTINATION is the natural way to bring a repository you received into your own storage. archive DESTINATION --path SOURCE reads more naturally when you are backing up a repository you already work with. In either case:

  • The destination must not exist. Synck never merges into, or overwrites, an existing directory.
  • The copy is exact. It has the same repository ID, the same item IDs, the same authors, timestamps and messages, and byte-for-byte the same content. The copy adds no commit, and neither command needs an author.
  • The copy is verified before it appears. Synck locks the source, takes a consistent snapshot with SQLite’s backup mechanism, copies the required objects into a private staging directory, and verifies the complete history and its closure there. Only then does it move the staging directory into place.
  • The copy is a follower. Checkout settings and writer activation are never copied. A copy of an activated or checked out repository starts as a plain, read-only follower again.

A copy keeps its source’s storage layout, whole files or compressed chunks. Add --storage-mode CHUNKED or --storage-mode WHOLE_FILE to either command to choose the layout of the copy instead. The content and every ID are the same in both layouts; only the files inside .synck differ. The source is never changed.

Always copy with these commands rather than with a file manager, cp or a sync tool. A plain file copy of a live SQLite database can miss recent writes or capture a half-written state, and nothing would tell you.

Refreshing a copy

A copy is frozen at its checkpoint. If the source keeps changing, as a SynckHub workspace does, your copy falls behind. There is no incremental update and no merge. To refresh, take a fresh export and make a new copy beside the old one:

$ synck repository import exports/launch-2026-11-01 launch-2026-11-01
$ synck repository verify launch-2026-11-01

Once the new copy has verified, switch to it, and only then delete the old one if you want to. If anything goes wrong while making the new copy, the old one is untouched and still complete. Keeping a few dated copies costs little and protects you against discovering a problem late.

Your recovery point is always the newest complete copy you hold. Anything written to the source after that copy’s checkpoint is not in it. No tool can recover it later from your copy.

What verification does and does not prove

synck repository verify is thorough:

$ synck repository verify my-copy
{"repo_id":"01a174b7-8a7d-74e0-b0d7-81b1dcfa6ccd","terminal_repo_seq":8,"commits":8,"items":4,"blobs":3,"bodies":3}

It replays every commit and event, checks every structural rule, recomputes every commit ID, rebuilds each item’s current state and compares it with what is stored, checks the history index, and reads every object in the closure and compares it with its hash. If a single byte of a historical file version has changed, it fails:

$ synck repository verify tampered-copy
synck: integrity error: blob digest mismatch

What verification establishes is internal consistency: everything the history refers to is present and is exactly what the history says it is.

It does not establish origin. Hashes are not signatures. Someone who can produce a repository can produce a different, equally consistent one. Author names are labels, not authenticated identities. So:

  • Trust a copy because of how you received it: you exported it yourself, it came over a channel you trust, or you compared its repository ID and terminal_repo_seq with what the producer told you through another channel.
  • Do not treat verify passing as proof that the content is genuine or that the export was authorized.

Protect copies as sensitive data

A complete repository contains the entire retained history, including deleted items, earlier versions, and items that were restricted to certain people in the application. Synck does not enforce the application’s permissions on a local directory: anyone who can read the files can read all of it.

Store and send complete repositories as you would the most sensitive thing in them: encrypted storage, restricted backups, careful sharing.

When copying fails

Copying is all or nothing:

  • If anything fails before the copy is published, for example because an object is missing or a check fails, the destination is never created. If the process was killed, a private staging directory may be left next to the destination. It is safe to delete, and the next attempt does not reuse it.
  • If the copy was published but the final disk flush failed, Synck says so explicitly: the copy exists, but it may not survive a crash or power loss. Run synck repository verify on it, and make another copy to a new destination if you are in doubt. Do not assume that nothing was created.
Previous
Reading items and history
Next
Editing files