Complete repositories

Every Synck repository is a complete repository: it holds a project’s entire retained history, together with every byte that history refers to, in one directory that opens with nothing but the synck tool. The repository you create with synck init is one. So is what SynckHub produces when a workspace is exported, and that is the reason Synck exists: your data, with its history, in your hands.

This chapter is about repositories you did not create in place: exports and copies, which arrive without a checkout.

This chapter explains how to work with one. If you have not done so yet, follow the short Opening a complete repository tutorial first. It uses a downloadable sample, and so does this chapter.

What “complete” means

A complete repository is more than a backup of today’s files. It contains:

every retained commit and event, for every item, from the first to the checkpoint at which it was exported;
every kind of item the project used: files and folders, but also chats, email, posts, tasks and task lists, records, calendars, calls and time tracking;
every byte that history refers to: all earlier versions of every file, superseded message texts, attachments, and the content of items that were later moved to the trash or deleted.

Synck calls that last set the history’s closure. A repository is complete only when the closure is entirely present. Synck checks that before it creates a copy, and synck repository verify checks it whenever you ask. If even one historical file version is missing, verification fails. A copy with gaps would look fine until the day you needed the missing piece.

Where complete repositories come from

There are three sources:

An export. SynckHub can export a workspace’s repository as a complete repository. The export captures one consistent checkpoint, including restricted and deleted history, so it is a sensitive artifact. How you request an export depends on how your organization runs SynckHub.
A copy of another complete repository, made with synck repository import or synck repository archive. Copies are exact: same repository ID, same item IDs, same authors and timestamps, and the same bytes.
Your own computer. synck init creates one with a checkout. See Your first repository.

Whatever the source, an export or copy is a snapshot at a point in time. It contains everything up to its checkpoint and nothing after. To catch up with a source that is still in use, you get a newer copy. See Copies, refreshes and trust.

What is inside

A complete repository on disk looks like this:

launch-project/
└── .synck/
    ├── config.json          format, repository ID, authority, storage mode
    ├── repository.sqlite3   history, current state and indexes
    ├── objects/             every file version and message body,
    │   ├── 47b256a9…            named by the SHA-256 of its bytes
    │   └── …                    (whole-file storage)
    ├── object-store.sqlite3 the same content in compressed chunks
    │                            (chunked storage; replaces objects/)
    └── lock                 coordinates Synck processes

There is no export manifest, no archive format to unpack and no conversion step. The directory is the repository. Opening it means reading SQLite and files. Inside .synck takes the layout apart in detail.

Three states: follower, independent, writer

Every complete repository records an authority in its config.json, and the authority decides what you can do with it:

                       ┌──▶ INDEPENDENT_LOCAL    after: synck repository checkout
                       │    your own editable copy; the source may carry on
                       │
 export or copy ──▶ FOLLOWER
                    read, verify, copy
                       │
                       └──▶ LOCAL                after: synck repository activate --source-retired
                            the successor writer, once the source is retired

Follower. Every export and every copy starts here. You can read every item at any point in history, verify the repository, extract files and make further copies. You cannot change it. Being given a copy does not make you its writer.

Independent local copy. synck repository checkout writes the repository’s files and folders to disk and lets you edit and commit them, like the repository synck init creates, which starts in this state too. You become the author of a separate line of history that starts from the export. The original keeps going in SynckHub, and the two never rejoin. Use this when you want to keep working locally from an export. See Editing files in a complete repository.

Local writer. synck repository activate --source-retired declares that the original writer, usually the SynckHub service that hosted the project, is permanently gone, and that this copy now continues its history. Use this when the source has been shut down and this repository is its successor. See Taking over as the writer.

Copying a repository always produces a follower, whatever state the original was in. Authority and checkouts are local decisions about one directory. They do not travel with copies.

What a complete repository does not include

A complete repository preserves data. It does not carry the services that used to act on that data. Reading saved email gives you the messages, bodies and attachments, but not a mail server. Reading a chat gives you its messages, but not notifications or presence. Permissions recorded in the data are not enforced locally: anyone who can read the directory can read everything in it. Questions and answers covers these boundaries.

In this chapter

Page	What it covers
Reading items and history	Listing, reading every item type, extracting files and reading the past
Copies, refreshes and trust	Making copies, refreshing them safely, and what verification proves
Editing files in a complete repository	Full and partial checkouts, and committing changes
Taking over as the writer	Activation and the typed write commands, after the source is gone

Committing large folders

Reading items and history