Clones and alternatives

A repository’s folder is one working tree, and one person editing it at a time works well. When several people, or several AI agents, work on the same project on one computer, each of them needs a working tree of their own. A clone is exactly that: another folder of the same repository, whose commits all go into the same history. And when you want to try something without disturbing the original, an alternative is a copy inside that history that you can later take back.

Neither is a branch. History stays one line, in the order commits were accepted.

Make a clone

synck clone makes another working tree of a repository on the same computer:

$ synck clone matter matter-sam --author Sam
cloned matter into .../matter-sam

(The full path is shortened here.) The clone reads the original repository’s history and stored content in place, so it costs only its working files. --author names the commits made from it; without it, the clone uses the original’s author. --include PATH, which you can repeat, checks out only those files and folders.

The original must be on a local disk. Synck refuses network drives, where its database cannot be locked safely, and moving or deleting the original breaks its clones.

Commit from any working tree

A commit made in a clone goes straight into the shared history. Here Sam edits the proposal in their clone:

$ cd matter-sam
$ printf 'Launch proposal\n\nGoal: open the Lisbon office on 1 March.\nBudget: 52,500 EUR.\n' > proposal.txt
$ synck commit -m "Add the fit-out to the budget"
committed sha256:b91681f2086527e169852880300708cf82fdbc9dd8b6038aa41a275112db86d7

Back in the original folder, the commit is already in the log, but the files on disk have not changed, and status does not report Sam’s edit as a change of yours:

$ cd ../matter
$ synck log --oneline
3 | 2026-11-04 01:29 +01:00 | Sam | Add the fit-out to the budget
2 | 2026-11-04 01:29 +01:00 | Alex | Add the proposal and the plan
1 | 2026-11-04 01:29 +01:00 | Alex | Initialize Synck repository
$ synck status
nothing to commit, working tree clean

Every working tree, the original’s included, remembers the commit its files are based on. synck pull brings the files up to date with everything committed since, and keeps your own uncommitted changes:

$ synck pull
updated 1 paths to sequence 3
$ cat proposal.txt
Launch proposal

Goal: open the Lisbon office on 1 March.
Budget: 52,500 EUR.

You rarely need to run pull yourself before you commit. commit, revert, mv, recover and version restore pull first, so commits that touch different files land from every working tree with no extra step.

When a file changed on both sides

Suppose Alex and Sam both edit proposal.txt and the Word document plan.docx, and Sam commits first. Alex’s commit stops before it records anything:

$ synck status
M plan.docx
M proposal.txt
$ synck commit -m "Raise the budget"
synck: changed here and in the repository since this working tree was last updated: plan.docx, proposal.txt; run synck pull to merge them

synck pull merges such files:

$ synck pull
updated 2 paths to sequence 4
conflicts in plan.docx, proposal.txt; edit them, then run synck resolve with their paths
  • A text file is merged line by line. Changes to different lines are combined. Where both sides changed the same lines, the file gets markers around the two versions, yours first:

    $ cat proposal.txt
    Launch proposal
    
    <<<<<<< ours
    Goal: open the Lisbon office on 1 March.
    Budget: 55,000 EUR.
    =======
    Goal: open the Lisbon office on 1 April.
    Budget: 53,000 EUR.
    >>>>>>> theirs
    
  • Any other file, such as a Word document, cannot be merged. Pull keeps your version and writes the repository’s beside it as <name>.~theirs.<ext>, here plan.~theirs.docx.

A text file whose changes combined cleanly is an ordinary change; review it and commit it. The others are conflicts. status lists them, and commit refuses until each one is resolved:

$ synck status
M plan.docx
A plan.~theirs.docx
M proposal.txt
conflict: plan.docx (the repository's version is plan.~theirs.docx); synck resolve when done
conflict: proposal.txt; synck resolve when done
$ synck commit -m "Raise the budget"
synck: unresolved conflicts: plan.docx, proposal.txt; edit them, then run synck resolve with their paths

To resolve one, make the file what it should be. Remove every marker from a text file, keeping the lines you want. For any other file, keep the version you want under the original name, then delete the ~theirs copy, or keep it as a new file. Then tell Synck with synck resolve and commit:

$ printf 'Launch proposal\n\nGoal: open the Lisbon office on 1 April.\nBudget: 55,000 EUR.\n' > proposal.txt
$ rm plan.~theirs.docx
$ synck resolve proposal.txt plan.docx
resolved proposal.txt, plan.docx
$ synck commit -m "Raise the budget"
committed sha256:519ba07130e163cc674c17221d71c606836a6b876f9b5bca144e18bc86eb643d

synck restore and synck restore-tree also clear a conflict, along with your version of the file.

Pull merges content only. A move, rename or deletion on one side against an edit on the other is not merged: pull fails with CONFLICT and the paths, and writes nothing. Make the same change here, or undo yours with restore. For files that cannot be merged, it is better to avoid the conflict in the first place: synck lock reserves paths for one working tree, and a commit that touches a reserved path from any other working tree is refused. synck instructions describes reservations.

Keep work private until it is ready

The commits of an ordinary clone are visible to everyone at once. A held clone keeps its commits to itself until you send them:

$ synck clone matter matter-draft --hold --author Alex
cloned matter into .../matter-draft
$ cd matter-draft
$ printf 'Notes for the board.\n' > board-notes.txt
$ synck commit -m "Draft the board notes"
committed sha256:cd1c3e34bba4157a974a9a69f2e5b3ca241f87afe871f1b58afceeccea738d39
$ synck status
nothing to commit, working tree clean
1 commits held; push sends them
$ synck push
pushed 1 commits
$ cd ../matter
$ synck log --oneline -n 1
6 | 2026-11-04 01:29 +01:00 | Alex | Draft the board notes

push pulls first, then adds the held commits to the shared history in order. Each keeps the commit ID it was given when you committed it, because a commit’s ID does not depend on where it lands. If an item was changed both in a held commit and in the shared history, push fails with CONFLICT and changes nothing on either side.

Held commits exist only in the held clone until you push them. Nobody else sees them and no backup of the original includes them, so delete a held clone only after pushing it.

Alternatives instead of branches

An alternative is a copy of a file or folder inside the same history: a second version of a proposal, another cut of a presentation, a different structure for a folder. synck duplicate copies a committed file or folder and commits the copy:

$ synck duplicate proposal.txt "proposal option B.txt" -m "Try a second version of the proposal"
committed sha256:0451481d4b27abe41772ec4b95219620ad7350996bb11fcb696808809216cb5b

Both are ordinary files from then on. Edit the alternative and commit it, and compare the two with diff and compare like any other files:

$ printf 'Launch proposal\n\nGoal: open the Lisbon office on 1 April.\nBudget: 50,000 EUR, without the fit-out.\n' > 'proposal option B.txt'
$ synck commit -m "Cut the fit-out in option B"
committed sha256:0495c87e22a988a2c3e229a8c9541deef9431778031a67f887ea68d91a45eb76

When you decide to go with the alternative, synck adopt makes the original match it, in one commit:

$ synck adopt "proposal option B.txt" proposal.txt -m "Go with option B"
committed sha256:61c9660959610acc94e1eff3734fe65f5755248e1afcb28b115a13b2ab7d16ad
$ cat proposal.txt
Launch proposal

Goal: open the Lisbon office on 1 April.
Budget: 50,000 EUR, without the fit-out.

The original keeps its identity and its whole history; it simply gets a new version. For a folder, adopt works path by path: a file at the same place in both gets the alternative’s content, a file only in the alternative is created, and a file only in the original is deleted. Delete the alternative afterwards if you no longer need it. Its history stays.

The history records where each copy came from. The alternative remembers the revision it began as, and the original remembers the revision it took in:

$ synck item show "proposal option B.txt" | jq -c "{derived_from: .item.projection.derived_from}"
{"derived_from":{"item_id":"01a1a3f5-e18e-722b-97b9-6f294005ea32","item_seq":4}}
$ synck item show proposal.txt | jq -c "{derived_from: .item.projection.derived_from, merged_from: .item.projection.merged_from}"
{"derived_from":null,"merged_from":[{"item_id":"01a1a3f6-3361-7291-9f78-54f05a942e07","item_seq":2}]}

duplicate and adopt need the paths they touch to have no uncommitted changes. Both write the files before they commit, so if one is interrupted, the files it wrote are left as ordinary changes for you to commit or discard.