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:
- keep the export you received as it is, as your reference copy;
- make your own copy with
synck repository import; - 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":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","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/budget.csv
launch-local/Launch/proposal.txt
The chat does not appear. It is a
record, 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, and so does synck clone
if you want several working trees of it. 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:f3e8be218181c0fbef44579123c653c7c02ca055b2d4f40e9abdf28ed46fd7e5
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:825e54fc831ab6f191da99bbe2547d8a60cb6ca153df8ab0e37354d57e401127 2026-11-04T00:18:08.331535+00:00 Maria
A Launch/budget.csv
9 sha256:f3e8be218181c0fbef44579123c653c7c02ca055b2d4f40e9abdf28ed46fd7e5 2026-11-04T00:31:55.867681+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":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","terminal_repo_seq":9,"commits":9,"items":6,"objects":8,"metadata":11,"missing_objects":[],"missing_metadata":[],"state_digest":"sha256:521fe541291f688962b4c0404189ce91eac27d11a7306a2520605b2340e5a95a"}
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 records. 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":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","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":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","schema_version":1}
$ find . -not -path './.synck*'
.
./Launch
./Launch/budget.csv
./Launch/proposal.txt
$ synck repository checkout-selection . --all
{"checkout_paths":[],"repo_id":"01a1a3eb-9711-76ea-85fc-d8beeefc6585","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 file or folder whose history is sequenced by an external authority, such as
one shared through a federation (see items sequenced
elsewhere), cannot be edited here. A
checkout whose selection includes one stops with externally sequenced item cannot be checked out for editing and the item’s path. Check out the other
paths with --include instead. Such files remain fully readable with synck item show and synck item export.
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
Nothing connects them later, either. synck pull and synck push work between
the working trees of one repository,
not between a copy and its source. 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.