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:
bytesfor a file, andsourcefor an email’s original message or an attachment, refer to the raw bytes, stored exactly as they were saved.d6057b02…isbudget.csv.bodyrefers 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
lockis the file that commands lock to get exclusive access. It is always empty. Locks belong to running processes and vanish with them.monitor.lockbelongs 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.jsonorname-repair.jsonlappear only while an operation is in progress or was interrupted. They are how recovery knows what to finish. conflicts.jsonlists the files a pull merged that still need a decision. It exists only until they are resolved.agent-locks.sqlite3holds the reservations made withsynck lock.pins/in a repository, andheld.jsonin a held clone, track the commits a held clone has not pushed yet, so thatgckeeps 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.