Editing files in a complete repository

Reading a complete repository through synck item is fine for looking things up. When you want to work on its documents, opening them in your usual applications and saving changes, check out the repository. synck repository checkout writes its files and folders to disk, so that you can edit and commit them, just like the repository you created in Your first repository.

Everything else in the repository stays exactly where it was. Chats, email, tasks and the complete history remain in .synck and are still readable with synck item.

Check out a copy, not the original

A checkout starts an independent line of history. From that point on, your commits and the original’s later changes are separate, and they can never be combined. So:

  1. keep the export you received as it is, as your reference copy;
  2. make your own copy with synck repository import;
  3. check out the copy.
$ synck repository import launch-project launch-local
{"imported":"launch-local","schema_version":1}
$ synck repository checkout launch-local --author "Alex"
{"authority":"INDEPENDENT_LOCAL","checkout_paths":[],"repo_id":"01a174b7-8a7d-74e0-b0d7-81b1dcfa6ccd","schema_version":1}

--author is the name recorded on your commits. The authors already in the history are unchanged. Checkout adds no commit of its own.

The repository’s files are now on disk:

$ find launch-local -not -path '*/.synck*'
launch-local
launch-local/Launch
launch-local/Launch/proposal.txt
launch-local/Launch/budget.csv

The chat does not appear. It is a non-tree item, and only tree items (files and folders) have a place on disk. It stays in .synck, readable with synck item show.

Checkout requires a directory that contains nothing but .synck. Synck never adopts or overwrites existing files, and if it finds any, it stops:

synck: checkout requires a directory containing only .synck; existing files are never overwritten

Edit and commit

From here, the everyday commands from Synck basics work as usual. Edit a file, rename another, add a folder:

$ cd launch-local
$ printf 'Status: approved by Sam\n' >> Launch/proposal.txt
$ mv Launch/budget.csv Launch/budget-2026.csv
$ mkdir Launch/Notes && printf 'Client call on Monday.\n' > Launch/Notes/call.txt
$ synck status
A Launch/Notes
A Launch/Notes/call.txt
RN Launch/budget.csv -> Launch/budget-2026.csv
M Launch/proposal.txt
$ synck commit -m "Record approval and file call notes"
committed sha256:fe30fd6db7a90e10877d788562e31c40899ee25e835f7c87aaf1225a4249f6fc

Identity is preserved exactly as in any repository. The renamed budget is still the item Maria created, with its history:

$ synck history Launch/budget-2026.csv
5 sha256:8405bf1627ba858298cf9de8f55efac0cc900e36ccbcde670ea8b127f08a372c 2026-10-25T20:19:09.579105411+00:00 Maria 
A Launch/budget.csv
9 sha256:fe30fd6db7a90e10877d788562e31c40899ee25e835f7c87aaf1225a4249f6fc 2026-10-25T20:21:53.125594639+00:00 Alex Record approval and file call notes
RN Launch/budget.csv -> Launch/budget-2026.csv

And the rest of the repository is still there and still complete:

$ synck repository verify .
{"repo_id":"01a174b7-8a7d-74e0-b0d7-81b1dcfa6ccd","terminal_repo_seq":9,"commits":9,"items":6,"blobs":5,"bodies":3}

What works in a checkout

Every command in Synck basics works in a checkout, along with fsck, storage, gc and archive from Backup and recovery, and every synck item and synck repository command. A checkout of an export behaves exactly like the repository synck init creates.

History commands see the same view as the working tree: log, show, compare, diff and export-tree report the files and folders, and leave out chats and other non-tree items. A commit that only added a chat message shows 0 changes. Read those items with synck item, and list every commit with all of its events with synck repository log.

For the same reason, synck revert only reverses commits that change files and folders, and refuses a commit that also changed a chat, an email or another item. revert and recover also refuse changes outside a partial checkout’s selected paths until you widen it.

Checking out only part of a repository

Large repositories may contain far more than you want on disk. --include checks out only the paths you name, and the folders that contain them. Try it on a second copy of the sample, next to launch-local:

$ cd ..
$ synck repository import launch-project launch-sparse
{"imported":"launch-sparse","schema_version":1}
$ synck repository checkout launch-sparse --author "Alex" --include Launch/proposal.txt
{"authority":"INDEPENDENT_LOCAL","checkout_paths":["Launch/proposal.txt"],"repo_id":"01a174b7-8a7d-74e0-b0d7-81b1dcfa6ccd","schema_version":1}
$ find launch-sparse -not -path '*/.synck*'
launch-sparse
launch-sparse/Launch
launch-sparse/Launch/proposal.txt

Repeat --include for several paths. Paths are literal, use / as the separator, are relative to the repository root and are case-sensitive. There are no wildcards. An included folder brings everything beneath it.

Files you did not include, here budget.csv, are simply not on disk. They are never treated as deleted, and Synck refuses changes that would affect them without your seeing them:

$ cd launch-sparse
$ mkdir Other
$ mv Launch/proposal.txt Other/
$ synck commit -m "Move the proposal out"
synck: Launch/proposal.txt was moved to Other/proposal.txt, outside checkout selection; move it back, or widen the selection with synck repository checkout-selection before moving it
$ mv Other/proposal.txt Launch/
$ rmdir Other
$ rm -rf Launch
$ synck commit -m "Delete Launch"
synck: folder deletion would affect omitted or non-filesystem items
$ synck restore-tree
restored working tree

Moving a file outside the selected paths is refused, because Synck could no longer see it afterwards. The message names both paths. Until the file is back where it was, commands that scan the folder, including restore-tree, give the same answer, so move it back as shown. Deleting Launch is refused because it still contains budget.csv, which is not on disk. Widen the selection first, then make the change.

Changing the selection

synck repository checkout-selection changes which paths are on disk. Commit or restore your changes first. Synck refuses to change the selection over uncommitted work:

$ synck repository checkout-selection . --include Launch
{"checkout_paths":["Launch"],"repo_id":"01a174b7-8a7d-74e0-b0d7-81b1dcfa6ccd","schema_version":1}
$ find . -not -path './.synck*'
.
./Launch
./Launch/proposal.txt
./Launch/budget.csv
$ synck repository checkout-selection . --all
{"checkout_paths":[],"repo_id":"01a174b7-8a7d-74e0-b0d7-81b1dcfa6ccd","schema_version":1}

--include replaces the selection, and --all selects everything. Files that leave the selection are removed from disk, and files that join it are written. History does not change. If a file that would be removed has been modified in the meantime, Synck stops rather than lose your bytes.

Files that cannot be checked out

A few files exist in a repository without a place on disk:

  • files that belong to another item rather than to a folder, such as a file stored inside an application record;
  • files whose history is sequenced by an external authority, such as a federated workspace (see items sequenced elsewhere).

They remain fully readable with synck item show and synck item export. They just do not appear in the checkout, and you cannot edit them there.

What a checkout is, and is not

A checkout is independent local continuation. Your directory carries on the history from the export onward, under your authorship. The source, such as the SynckHub workspace, can carry on in parallel, and nothing connects the two:

 SynckHub   … ── 6 ── 7 ── 8 ── 9 ── 10 …              the source continues
                      │
                      └── export ──▶ launch-local: 7 ── 8′ ── 9′ …   your commits

There is no push, pull, sync or merge. Your changes do not flow back to the source, and the source’s later changes do not flow into your checkout. To see newer source data, get a fresh export.

When you copy a checked-out repository with repository archive or repository import, the copy contains everything you committed, but no checkout. It is a plain follower again.

If the source has been shut down for good and this copy should become its continuation, that is a different, explicit step. See Taking over as the writer.

Previous
Copies, refreshes and trust
Next
Taking over as the writer