Opening a complete repository
A complete repository is what you get when a project is exported from
SynckHub: one directory that holds the project’s entire retained history and
every byte that history refers to. That includes files, folders, conversations
and more. In this tutorial you will open one with nothing but the synck
command. No account, no server and no network.
You need Synck installed. The tutorial also uses
jq, a small JSON tool, to make output easier to read.
It is optional, and every step says what to do without it.
Get the sample
Download the sample repository: launch-project.zip (14 KB). It is a small, made-up SynckHub project in which Maria and Sam prepare a proposal to open a new office. Unzip it in a working folder, either by double-clicking it or from the terminal:
$ unzip -q launch-project.zip
$ ls -A launch-project
.synck
That is all there is: a directory containing .synck. Unlike the repository
in the previous tutorial, this one has no checkout, so
there are no files on disk. Everything is stored inside .synck, and you read it through
Synck. (When you want ordinary files to edit, you can
check them out later.)
Inside the sample, the project looks like this:
launch-project
├── FOLDER Launch a workspace
│ ├── FILE proposal.txt created by Maria, revised once
│ └── FILE budget.csv
└╌╌ CHAT "Launch review" a team chat: three messages between Sam and Maria
Launch is a workspace: in SynckHub, the folder that holds a project’s
files. The chat is a record. It is not inside any folder and has no name,
only a title. (What is Synck? explains the
difference.)
Its history has eight commits:
| # | Author | What happened |
|---|---|---|
| 1 | Maria | Created the Launch workspace |
| 2 | Maria | Created the Launch review chat |
| 3 | Maria | Added the first draft of proposal.txt |
| 4 | Sam | “Please check the budget before Friday.” |
| 5 | Maria | Added budget.csv |
| 6 | Maria | Saved a revised proposal.txt |
| 7 | Maria | “The revised figures are ready. Fit-out was missing.” |
| 8 | Sam | “Approved. Send it to the client.” |
Verify it first
Before you rely on a repository someone gave you, check it:
$ synck repository verify launch-project
{"repo_id":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","terminal_repo_seq":8,"commits":8,"items":4,"objects":6,"metadata":8,"missing_objects":[],"missing_metadata":[],"state_digest":"sha256:08281769a273c9d75eb5b7d5873f11c1db42308a8a7fdb5df635a03157a0d51e"}
Verification replays the entire history, checks its structure and recomputes the hash of every stored file version and message text. The report counts what it checked:
terminal_repo_seqis the last position in the history. Eight commits mean the history runs up to position 8.itemscounts the workspace folder, the two files and the chat.objectscounts stored contents: two versions of the proposal, one of the budget, and the texts of the three messages.metadatacounts the small records that describe events, such as a file’s size or the chat’s title.missing_objectsandmissing_metadatalist anything the history refers to that is not here. In a complete repository both are empty.state_digestis a hash of the repository’s current state, so two copies can be compared at a glance.
If anything had been altered, the command would fail with an error instead, and anything missing would be listed. Either would be your cue to get a fresh copy rather than use this one.
Verification proves that the copy is internally consistent. It does not prove where the copy came from; for that you still rely on how you received it. See copies you can trust.
Browse the items
List what is at the top level of the folder tree:
$ synck item list --path launch-project
{"items":[{"repo_id":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","item_id":"01a1a3eb-9726-7013-bfd0-bb59a731f352","item_type":"FOLDER","parent_folder_id":null,"name":"Launch",...}],"next_cursor":null}
(Output abbreviated with ....) The synck item commands always answer in
JSON, because they are designed to be easy for scripts and other programs to
read. Each item carries its type, its name and, most importantly, its
item_id, which never changes. --path names the repository; leave it out
when you run the command from inside the repository’s directory.
With jq, you can print just the interesting fields:
$ synck item list --path launch-project | jq -r '.items[] | "\(.item_type)\t\(.name)\t\(.item_id)"'
FOLDER Launch 01a1a3eb-9726-7013-bfd0-bb59a731f352
The chat is missing. It is a record, and records are not part of the folder tree, so a tree listing never shows them. Ask for records instead:
$ synck item list --records --path launch-project | jq -r '.items[] | "\(.item_type)\t\(.item_id)"'
CHAT 01a1a3eb-972f-7227-8c51-fe4369603984
A record has no name, so there is none to print. The title people see, “Launch
review”, is data stored with the chat, and item show reveals it:
$ synck item show 01a1a3eb-972f-7227-8c51-fe4369603984 --path launch-project | jq -r '.item.chat | "\(.title) (\(.profile.chat_kind))"'
Launch review (ROOM)
ROOM is SynckHub’s kind for a team chat, as opposed to a direct message or an
assistant conversation. A record has no path either, so you always name it by
its ID. Files and folders can also be named by their path in the repository.
The folder, for example, is not an ordinary folder:
$ synck item show Launch --path launch-project | jq -c .item.projection.metadata_json.workspace
{"kind":"STANDARD_CASE","workflow":{"lifecycle_mode":"status_only","lifecycle_version_id":null,"pipeline_key":null,"stage_key":null,"status":"open"}}
The workspace object marks a SynckHub workspace: its kind, STANDARD_CASE,
and its workflow state, here simply open. To look inside it, pass it as the
parent:
$ synck item list --parent Launch --path launch-project | jq -r '.items[] | "\(.item_type)\t\(.name)\t\(.item_id)"'
FILE budget.csv 01a1a3eb-974a-770b-91d3-a518ea5dbef8
FILE proposal.txt 01a1a3eb-9737-7051-8189-c2dc29a0d474
Read a conversation
synck item show reconstructs one item from its history. For a chat, that
includes every message:
$ synck item show 01a1a3eb-972f-7227-8c51-fe4369603984 --path launch-project | jq -r '.item.subitems[] | "\(.sender_id): \(.body)"'
Sam: Please check the budget before Friday.
Maria: The revised figures are ready. Fit-out was missing.
Sam: Approved. Send it to the client.
Without jq, look for the subitems list in the JSON. Each message has a
sender_id, a created_at time and a body.
This is the point of a complete repository. The conversation that explains why the budget changed is preserved alongside the file, and you can read it without the chat application that originally hosted it.
Extract a file
To get a file’s content out as an ordinary file, use synck item export with
the file’s path or ID and a destination that does not exist yet:
$ synck item export Launch/proposal.txt proposal.txt --path launch-project
{"bytes":110,"destination":"proposal.txt","item_id":"01a1a3eb-9737-7051-8189-c2dc29a0d474","schema_version":1}
$ cat proposal.txt
Launch proposal
Goal: open the Lisbon office on 1 March.
Budget: 52,500 EUR (includes fit-out).
Owner: Maria
Synck checks the bytes against their stored hash before it writes the file, and it never overwrites an existing file.
Go back in time
The proposal was revised in commit 6. To see it as it was before that, read
the repository through an earlier position in its history. --through 5
means “as of the end of commit 5”:
$ synck item export Launch/proposal.txt proposal-first-draft.txt --through 5 --path launch-project
{"bytes":91,"destination":"proposal-first-draft.txt","item_id":"01a1a3eb-9737-7051-8189-c2dc29a0d474","schema_version":1}
$ diff proposal-first-draft.txt proposal.txt
4c4
< Budget: 48,000 EUR.
---
> Budget: 52,500 EUR (includes fit-out).
--through works with every item command, so you can also see the
conversation as it stood at that moment:
$ synck item show 01a1a3eb-972f-7227-8c51-fe4369603984 --through 5 --path launch-project | jq -r '.item.subitems[] | "\(.sender_id): \(.body)"'
Sam: Please check the budget before Friday.
At position 5, Sam had asked about the budget and nobody had answered yet. Every item can be viewed at any point in the repository’s history like this.
Make your own copy
The sample you unzipped is someone else’s copy. To keep a copy of your own, let Synck make it, rather than copying the directory with your file manager:
$ synck repository import launch-project my-copy
{"imported":"my-copy","schema_version":1}
$ synck repository verify my-copy
{"repo_id":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","terminal_repo_seq":8,"commits":8,"items":4,"objects":6,"metadata":8,"missing_objects":[],"missing_metadata":[],"state_digest":"sha256:08281769a273c9d75eb5b7d5873f11c1db42308a8a7fdb5df635a03157a0d51e"}
repository import locks the source, takes a consistent snapshot of it,
verifies everything in a private staging area, and only then creates my-copy. The
copy keeps the same repository ID, item IDs, authors and history. It adds no
commit of its own. If anything fails, my-copy is never created.
Look at the copy’s configuration:
$ cat my-copy/.synck/config.json
{"storage_mode":"WHOLE_FILE","format_version":7,"repo_id":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","authority":"FOLLOWER"}
"storage_mode":"WHOLE_FILE" says how the copy stores content on disk. A copy
keeps the layout of its source, and this sample stores each file whole.
Storage space explains the two
layouts.
"authority":"FOLLOWER" means that this copy can be read, verified and copied
again, but it does not accept changes yet. Copying a repository does not
give you the right to write to it. Becoming a writer is a separate, explicit
step, which Complete repositories explains.
What you learned
- A complete repository is a directory with a
.synckinside. It needs no service to read. synck repository verifychecks every commit and every stored byte.synck item listandsynck item showbrowse items by path or ID, and answer in JSON.--recordslists chats, email and other records, which have no place in the folder tree.synck item exportextracts a file, and--throughreads any earlier point in the history.synck repository importmakes a verified copy of your own. Copies start as read-only followers.
Next, learn to work with complete repositories in depth, including how to edit their files, or go back to Synck basics for everyday work in a tracked folder.