Inside .synck

Everything Synck knows about a repository lives in one directory, .synck. Nothing is hidden elsewhere: no global database, no cache in your home folder, no registry. This page opens it up, so you know what you are backing up and why the rule is “look, but do not touch”.

Inspect freely, never modify. Reading these files, for example with sqlite3 -readonly or shasum, is safe. Changing them in any way bypasses every guarantee Synck makes.

What is in it

Every repository has the same history database. How content is stored depends on its storage mode, and a repository with a checkout has a few extra entries for its working tree:

.synck/
├── config.json                format, identity, authority, storage mode
├── repository.sqlite3         history, metadata and current state
├── object-store.sqlite3       content as compressed chunks   (CHUNKED)
├── objects/                   content as hash-named files    (WHOLE_FILE; empty otherwise)
├── lock
├── repository.state.sqlite3   cache: the history index
│
│   only with a checkout:
├── checkout.json              selected paths and the commit the files are based on
├── repository.local.sqlite3   cache: which file on disk is which item
├── monitor.lock               the optional background monitor
└── tmp/                       partial writes

SQLite may also keep -wal and -shm files next to a database. They are part of SQLite’s normal operation, and they hold recent writes, which is one more reason never to copy .synck by hand.

config.json

The configuration identifies the repository and states its format. A repository created with synck init:

{"storage_mode":"CHUNKED","format_version":7,"repo_id":"01a1a3ec-c5dc-744d-84ea-895e8e2ef7ae","author":"Alex","authority":"INDEPENDENT_LOCAL"}

A repository freshly exported or copied:

{"storage_mode":"WHOLE_FILE","format_version":7,"repo_id":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","authority":"FOLLOWER"}

authority is FOLLOWER for an export or copy, INDEPENDENT_LOCAL for a repository created with synck init or after a checkout, or LOCAL after activation. A writer also records an author. A configuration without storage_mode means WHOLE_FILE. A clone names the folder of the repository it was cloned from in origin, and a held clone adds "hold":true. The file never contains credentials or account details.

A checkout keeps its changing state apart, in checkout.json:

{"paths":[],"hidden_files":"ignore","baseline":4}

paths lists the selected folders, and an empty list means everything. baseline is the commit the working files are based on. Copies never carry the file, which is why a copy is never a checkout.

repository.sqlite3: the history

The history database holds the engine’s vcs_ tables, which are the same in every Synck repository:

Table Holds Authoritative?
vcs_commits One row per commit: ID, author, committer, message, times, repository sequence Yes
vcs_events One row per item event: its item, item sequence, type and canonical JSON Yes
vcs_ref_events Events in items’ ref ledgers Yes
vcs_metadata_objects The metadata objects that events refer to, such as sizes and titles Yes
vcs_checkpoints, vcs_history_generations The sealed position of each commit in the repository’s order Yes
vcs_federation_domains Positions in externally sequenced (federated) streams Yes, preserved exactly by copies
vcs_items Each item’s current type, name, parent, key, link, lifecycle and latest sequences Derived, kept in step with history in the same transaction
vcs_repo_activity_heads The sequencer’s position Derived

“Authoritative” means the history is those rows, together with the content they reference. Everything else is derived from them and is checked against them by fsck and repository verify. If derived state is damaged, it can be rebuilt. If authoritative state is damaged, only a good copy can help.

The two other databases are caches. repository.state.sqlite3 holds the history index, a tree of snapshots that makes reads of old states fast. repository.local.sqlite3 holds a checkout’s own bookkeeping, such as which file on disk is which item and the result of the last scan. Neither is part of the repository: copies leave them out, and Synck rebuilds either one when it is missing.

You can read the events of any repository directly:

$ sqlite3 -readonly .synck/repository.sqlite3 "SELECT payload FROM vcs_events WHERE event_type = 'CHAT::MESSAGE::CREATE' ORDER BY item_seq LIMIT 1;"
{"base_seq":2,"event_type":"CHAT::MESSAGE::CREATE","item_id":"01a1a3eb-972f-7227-8c51-fe4369603984","set_content":{"body":"sha256:8e5ca7ca640fbada24bf63b58ffee2759182e59a9442ac98e2dc24c25596d157"}}

And the metadata they refer to. A metadata object begins with the same 49-byte header as a message body, and the JSON follows it:

$ sqlite3 -readonly .synck/repository.sqlite3 "SELECT CAST(substr(payload, 50) AS TEXT) FROM vcs_metadata_objects WHERE object_id = unhex('5bfdbbeb6da5446f393b2b28772696beb19ca06d5462f80a659dbc61606a3bf5');"
{"title":"Launch review"}

Whole-file content

With WHOLE_FILE storage, all content lives in one directory, .synck/objects/. The sample repository uses it. Each file is named by the SHA-256 of its exact stored bytes, with no subdirectories and no compression:

$ ls .synck/objects
3b7ad68c69fb5dc4c83f4e87949324a80fa4084fde364edec0821bc5be3ea1ac
65d1490153c828ac1dde577ddd8a9806f0b4288e47e0f4541f0f8545a2ff51f8
8e5ca7ca640fbada24bf63b58ffee2759182e59a9442ac98e2dc24c25596d157
d6057b02c87e36a0294aa1c310e09a1c457a7d21a3aa16dd53066745a1900cd2
dce64fbd23ae5587537da30ed34c8c46845776f561397f7bd7e9a8cded20f8c3
fdfdf64e89e31bbe76af72e4df33950552d618c1d77b2b2e76b79e857c6e8043

That makes the store checkable with nothing but standard tools:

$ shasum -a 256 .synck/objects/d6057b02c87e36a0294aa1c310e09a1c457a7d21a3aa16dd53066745a1900cd2
d6057b02c87e36a0294aa1c310e09a1c457a7d21a3aa16dd53066745a1900cd2  .synck/objects/d6057b02c87e36a0294aa1c310e09a1c457a7d21a3aa16dd53066745a1900cd2

Two kinds of content share this directory, and the role in the event’s set_content says which is which:

  • bytes for a file, and source for an email’s original message or an attachment, refer to the raw bytes, stored exactly as they were saved. d6057b02… is budget.csv.
  • body refers to an encoded body: the text of a message, comment or post.

How a body is encoded

Here is Sam’s first message, the object that the event above refers to:

$ O=.synck/objects/8e5ca7ca640fbada24bf63b58ffee2759182e59a9442ac98e2dc24c25596d157
$ wc -c < $O
87
$ head -c 15 $O
SYNCK_OBJECT_V1
$ od -A d -t x1 -j 15 -N 34 $O
0000015    00  01  29  9e  af  bf  a3  c9  df  62  45  96  77  ad  9f  d3
0000031    5d  78  12  18  1a  5e  a4  45  e8  36  92  48  84  f4  ad  86
0000047    88  59
0000049
$ tail -c +50 $O
Please check the budget before Friday.

A body is four parts:

 SYNCK_OBJECT_V1 \0 │ 01 (UTF-8) │ 32 random bytes (salt) │ UTF-8 text
 ──── 16 bytes ──── │ ─ 1 byte ─ │ ────── 32 bytes ────── │ the rest

The salt makes every body unique, even when two messages say the same thing. Without it, anyone holding a list of hashes could test whether a repository contains a message such as “yes” by hashing guesses. The cost is that identical messages are not deduplicated. The salt is not encryption. The text is in plain sight, as you just saw. Copies must keep the salt exactly, because the ID and every commit above it depend on it. Metadata objects are salted the same way, for the same reason.

Which decoder applies is always decided by the role in the event, never by looking at the bytes. A file that happens to begin with SYNCK_OBJECT_V1 is still read as a file. The object’s ID is always the SHA-256 of its stored bytes, whatever its form, so any reader can check any object without knowing what it is.

Chunked content

With CHUNKED storage, the same content lives in a second database, object-store.sqlite3, as chunks:

Table Holds
blobs One row per stored object, identified by the SHA-256 of its full stored bytes
chunks Content-defined chunks, each identified by the hash of its bytes, compressed with zstd when that helps
chunk_bases For a chunk stored as a delta, the chunk it is a delta against
blob_chunks Which chunks, in which order, make up each object
store_identity Which repository this store belongs to

The identities do not change: an object ID is still the SHA-256 of the complete stored bytes, and a body is still encoded exactly as above before it is chunked. Reading reassembles the chunks and checks both every chunk and the SHA-256 of the whole. Storage space explains when each layout is the better choice.

The other entries

  • lock is the file that commands lock to get exclusive access. It is always empty. Locks belong to running processes and vanish with them.
  • monitor.lock belongs to the optional background monitor.
  • tmp/ holds partial writes. Synck empties it at the start of each command.
  • Intent records such as move.json, revert.json, recover.json, pull.json or name-repair.jsonl appear only while an operation is in progress or was interrupted. They are how recovery knows what to finish.
  • conflicts.json lists the files a pull merged that still need a decision. It exists only until they are resolved.
  • agent-locks.sqlite3 holds the reservations made with synck lock.
  • pins/ in a repository, and held.json in a held clone, track the commits a held clone has not pushed yet, so that gc keeps their content.

Intent records, checkout.json, conflicts.json and agent-locks.sqlite3 are not caches. Deleting one loses work in progress.

Why not simply files?

It is fair to ask why a version-control tool keeps history in SQLite rather than in plain files, as Git does. The short answer is transactions. A commit must update the history, the current-state tables and the item sequences together, or not at all, and it must reject a stale change in the same step. SQLite gives exactly that, on every platform, in a single well-documented file format that any language can read. Content is kept apart from the history, either as plain hash-named files or in a separate chunk database, so a repository’s history can be read and checked without touching its largest part.