What is Synck?
This chapter is about getting going. It starts with the ideas you need to use Synck well, then installs it and walks you through your first repository and your first complete repository. If you only read one conceptual page before you start, make it this one. Most confusion about Synck comes from expecting it to behave like some other tool.
About version control
A version-control system records changes to a set of things over time, so you
can see how they evolved and get back any earlier state. Most people first meet
it as copies with names like proposal-final-v3-REALLY-final.docx. That works
until you need to know which copy the client saw, or who changed the budget and
why.
Software developers solved this long ago with tools such as Git. Those tools are excellent at what they were built for: plain-text source code, edited by many people in parallel and combined later by merging lines of text.
Version control for knowledge work
Knowledge work has a different shape. A project consists of documents, but also of a review conversation, a task with an approval, a calendar of meetings and the email sent to the client. Several things follow from that:
- Much of it is not a file. A chat is a growing sequence of messages, not a document you save. A task has a state, an assignee and comments.
- Identity matters more than location. People rename and reorganize all the
time. A proposal that moved from
Drafts/toSent/is still the same proposal, with the same history. - Most of it cannot be merged. Two people’s edits to a spreadsheet or a slide deck cannot be combined line by line. What matters is that changes are accepted in a clear order and nothing is lost.
- The record outlives the tools. You might need the conversation that led to a decision years after you stopped paying for the application that hosted it.
Synck is designed for that shape. The rest of this page describes the handful of ideas it is built on.
Items have identity
Synck does not version a tree of paths. It versions items. A file, a folder, a chat, an email and a calendar are all items. Every item has a permanent ID that it keeps for life:
Repository
├── FOLDER Launch (a workspace) 01a1a3eb-9726-7013-bfd0-bb59a731f352
│ ├── FILE proposal.txt 01a1a3eb-9737-7051-8189-c2dc29a0d474
│ └── FILE budget.csv 01a1a3eb-974a-770b-91d3-a518ea5dbef8
│
└╌╌ CHAT "Launch review" 01a1a3eb-972f-7227-8c51-fe4369603984
a record: no folder and no name; "Launch review" is its title
Rename proposal.txt or move it into another folder and it is still item
01a1a3eb-9737-…, with its whole history attached. Delete it and create a new
file with the same name, and the new file is a different item. A path tells
you where an item is now. The ID tells you which item it is.
Tree items and records
Items come in two classes, and the difference matters as soon as you look past files.
Tree items are what a file system holds: folders and files. They have a parent folder (or sit at the top), a name that is unique among their live siblings, and a path. A checkout writes them to disk under exactly that name. Synck enforces the tree rules for them: a folder cannot contain itself, and two live items in the same folder cannot share a name.
Records are everything else: emails, chats, posts, calls, task lists and tasks, calendars and their events, contacts, structured databases and tables, and time-tracking records. A record has no parent folder, no name and no path, and it never appears on disk. Its item ID is its identity. The text people see, such as a chat called “Launch review” or an email’s subject, is its title, stored as data with the record. Two records can share a title.
A record can have two more things. A key makes it unique: at most one live record of a type has a given key. A link files it in one folder, the way a saved email can belong to a project. A link is filing, not placement: the record is still not inside the folder, a folder listing does not show it, and a checkout ignores it.
Smaller records inside an item, such as a chat’s messages, reactions and attachments, or an email’s attachments, are not items at all. They are subitems in their parent item’s history.
Workspaces
In SynckHub, work is organized into workspaces, which an organization may call cases, matters, deals, projects or engagements. A workspace is a folder whose metadata marks it as one, with its kind and its workflow state, and it holds the project’s files. The project’s other records are connected to it by links, not placement. SynckHub can file a team chat in its workspace, for example, so that access to the workspace can extend to the chat. The chat still never becomes a child of the folder. Direct messages and assistant conversations are not filed in a workspace at all.
History is a log of events
Every change to an item is an event: the file got new content, the folder was renamed, a message was added to the chat. Each item’s events form a single numbered line, its item sequence:
proposal.txt 1 FILE::CREATE ── 2 FILE::SET_CONTENT ── 3 FILE::SET_CONTENT
Launch review 1 CHAT::CREATE ── 2 CHAT::SET_PROFILE ── 3 MESSAGE ── 4 MESSAGE ── 5 MESSAGE
A commit groups one or more events, possibly for several items, into a single change that is accepted all at once or not at all. Creating a folder and the three files inside it is one commit; if any part is invalid, none of it is recorded. Every commit is identified by a SHA-256 hash of its exact content, so it can be checked later.
This is the biggest difference from Git. Git records snapshots of the whole tree and works out what changed between them. Synck records what happened to each item and can rebuild any state from that. Items, events and commits shows the real events behind a short session.
Nearly every operation is local
A Synck repository is a folder with a .synck directory inside it. Everything
Synck needs is there: the history in a SQLite database and the content in
an object store. Viewing history, comparing versions, extracting an old file
and verifying integrity all read local data. No account, server or network is
involved. Even reading a repository exported from SynckHub does not contact
SynckHub.
Synck has integrity
Every file version, message body and commit is identified by the SHA-256
hash of its exact bytes. synck fsck and synck repository verify recompute
those hashes and check the history’s structure. You cannot change a stored file,
a message or a past commit without the check noticing.
Hashes prove that the data is consistent. On their own, they do not prove who produced it. An author name in Synck is a label for attribution, not a login. Keep that distinction in mind when you receive a repository from someone else; copies you can trust discusses it in detail.
Synck only adds data
Accepted history is never rewritten. Editing a file adds a new version and leaves the old one in place. Deleting a file moves it to the trash, and you can recover it with its identity intact. Undoing a commit adds a new commit that reverses it. Because nothing is removed, an honest mistake is always recoverable.
The other side of this is that you cannot erase something from history by committing again. If you commit a secret, it stays in that repository’s history. Plan for that before you commit sensitive material.
One writer per item
Each item has exactly one writer authority that accepts its changes in order. In a folder you track on your own computer, that authority is the repository on your disk. In SynckHub, it is the server. History is a single line, and there are no branches.
Several people or agents can still work on one repository at once. synck clone gives each of them their own working tree on the same computer, and all
their commits go into the same line of history. synck pull brings a working
tree up to date with everyone else’s commits. When the same file changed in two
working trees, it merges text line by line and keeps both versions of anything
else for you to choose from. Clones and alternatives
covers this. Two separate copies of a repository that are changed
independently, by contrast, stay separate forever.
This is a real limitation, and it is intentional. Branches and merges are what let developers work in parallel on text, but they have no good meaning for most knowledge-work data. Synck chooses a simple, predictable rule instead: one authority, one ordered history. The trade-offs page describes what this costs and when another tool is the better choice.
One kind of repository, with or without files on disk
Every Synck repository has the same complete format. What differs is whether its files are also laid out in a folder for you to edit, a checkout:
With a checkout Without a checkout (bare)
(from `synck init`) (an export or a copy)
notes/ launch-project/
├── .synck/ history + content └── .synck/ history + every byte
├── .synckignore for files, chats,
├── plan.txt email, tasks, ...
└── meetings/
└── standup.txt Read it with `synck item`, or ask
for a checkout to get files.
Edit files, then `synck commit`.
| With a checkout | Bare | |
|---|---|---|
| Where it comes from | synck init in a folder, or synck repository checkout |
An export from SynckHub, or a copy |
| What it holds | Every kind of item: files, chats, email, tasks, calendars and more | The same |
| Everyday commands | status, commit, log, diff |
item list, item show, repository verify |
| Your files on disk | Yes | No |
Both hold the complete history, and a copy of either is a bare repository you can check out again. The Synck basics chapter covers everyday work in a checkout. Complete repositories covers reading, copying and checking out repositories without files on disk.
What Synck is not
It helps to be clear about what Synck deliberately leaves to other software:
- Not a sync service. Synck does not copy changes between computers. Clones share one repository on one computer. A copy anywhere else is a point-in-time snapshot that you refresh explicitly.
- Not an access-control system. Anyone who can read a repository’s files can read all of its retained history, including deleted items. Permissions belong to the application that serves the data.
- Not the applications. Reading a saved chat does not give you a chat app, and reading saved email does not give you a mail server. Synck preserves the data and its history. The SynckHub applications provide the live services.
- Not a merge tool for copies. Two diverged copies cannot be combined. Merging happens only inside one repository, between its working trees.
With those ideas in place, install Synck.