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_seq is the last position in the history. Eight commits mean the history runs up to position 8.
  • items counts the workspace folder, the two files and the chat.
  • objects counts stored contents: two versions of the proposal, one of the budget, and the texts of the three messages.
  • metadata counts the small records that describe events, such as a file’s size or the chat’s title.
  • missing_objects and missing_metadata list anything the history refers to that is not here. In a complete repository both are empty.
  • state_digest is 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 .synck inside. It needs no service to read.
  • synck repository verify checks every commit and every stored byte.
  • synck item list and synck item show browse items by path or ID, and answer in JSON. --records lists chats, email and other records, which have no place in the folder tree.
  • synck item export extracts a file, and --through reads any earlier point in the history.
  • synck repository import makes 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.