Backup and recovery

A version-control system protects you against your own mistakes: an edit you regret, a file you deleted. It does not protect you against losing the disk it lives on. For that you need copies somewhere else. This chapter covers making those copies correctly, checking them, and what happens when something goes wrong halfway through an operation.

What a recovery copy needs

A copy is only useful for recovery if it has both halves of a repository:

  • the history, meaning every commit and event, in the SQLite database; and
  • the content that history refers to: every version of every file and every message body, in the object store.

A folder of today’s files has neither half. A copy of the database without the objects can tell you a file once had 52,500 EUR in it, but cannot give you the file. Synck’s backup commands always produce both halves together and verify them before they finish.

Making a backup

From inside a repository’s folder, synck archive writes a complete copy to a new destination:

$ synck archive /backups/notes-2026-10-26
archived /backups/notes-2026-10-26
$ synck repository verify /backups/notes-2026-10-26
{"repo_id":"01a17955-e227-774e-bc2c-4e127ae64aea","terminal_repo_seq":4,"commits":4,"items":3,"blobs":3,"bodies":0}

For a repository without a checkout, or from anywhere else, name it with --path: synck repository archive /backups/launch-2026-10-26 --path launch-project. The two commands produce the same result.

The destination must not exist yet; Synck never overwrites anything. The archive holds the repository’s entire committed history and all the content it needs, and it is verified before it appears. It does not contain uncommitted changes, so commit first if you want them included.

The archive is not a compressed file and needs no unpacking. It is an ordinary complete repository without a checkout. A copy keeps the repository’s storage layout unless you pass --storage-mode. Copies, refreshes and trust explains exactly what a copy preserves and what to do if copying fails.

Restoring from a backup

Leave the backup as it is, make a copy of it, and check the copy out:

$ synck repository import /backups/notes-2026-10-26 ~/restored-notes
{"imported":"/home/alex/restored-notes","schema_version":1}
$ synck repository checkout ~/restored-notes --author "Alex"
{"authority":"INDEPENDENT_LOCAL","checkout_paths":[],"repo_id":"01a17955-e227-774e-bc2c-4e127ae64aea","schema_version":1}
$ cd ~/restored-notes
$ synck log --oneline
4 | 2026-10-26 18:50 +01:00 | Alex | File the notes under meetings
3 | 2026-10-26 18:50 +01:00 | Alex | Move the meeting to 11
2 | 2026-10-26 18:50 +01:00 | Alex | Record the meeting time
1 | 2026-10-26 18:50 +01:00 | Alex | Initialize Synck repository

The restored repository has the same repository ID, item IDs and history as the original, and its folder holds the files as of the latest commit. Carry on working there exactly as before. Editing files in a complete repository describes checkouts in detail, including checking out only some folders.

Never copy .synck by hand

It is tempting to back up a repository by copying its folder with a file manager, rsync, or a cloud-sync client. Do not rely on that. .synck contains a live SQLite database. A plain file copy taken while Synck is writing, or one that copies the database and the objects at slightly different moments, can be inconsistent, and nothing would warn you until you tried to restore it.

The archive command takes Synck’s lock, read a consistent snapshot, verify the result, and only then publish it. Let them do the copying, and then back up the finished archive however you like, including with rsync or cloud storage.

For the same reason, do not keep a live repository inside a folder that a sync client such as Dropbox, OneDrive or iCloud Drive manages. The client may upload a half-written database, or “restore” an old one on top of a new one.

A simple routine

Synck’s commands make copies correct. Making them regularly and keeping them safe is up to you. A routine that works:

  1. Archive on a schedule into a new, dated destination each time, such as /backups/notes-2026-10-26.
  2. Verify each archive right after making it, with synck repository verify.
  3. Keep several generations, not just the latest. A problem you discover late may already be in the newest copy.
  4. Keep at least one copy on a different machine or medium from the original. A copy on the same disk does not survive the disk.
  5. Practise a restore now and then. A backup you have never restored is a hope, not a plan.
  6. Protect the copies. They contain your entire history, deleted material included.

In this chapter

Page What it covers
Checking integrity fsck and repository verify, what they check, and what to do when they fail
When an operation is interrupted How Synck recovers from crashes, power loss and full disks
Storage space Seeing what history costs, removing unreferenced data, and compact storage
Previous
Taking over as the writer
Next
Checking integrity