Taking over as the writer

Every Synck item has exactly one writer authority. For a SynckHub workspace, that is the SynckHub service. If that service is shut down for good, for example when your organization stops using SynckHub or a self-hosted server is decommissioned, a complete repository lets you carry on. You can declare that a copy is now the writer, and continue its history from where the source stopped.

This is a deliberate, one-way decision. Read this page before you make it.

Activation versus checkout

Synck offers two ways to change a complete repository. They answer different questions:

	Checkout	Activation
Command	`synck repository checkout`	`synck repository activate --source-retired`
The source	May still be running	Has been permanently retired
What your copy becomes	An independent local line of history	The successor that continues the source’s history
Files on disk	Yes	No (combine with a checkout if you want them)
Authority in `config.json`	`INDEPENDENT_LOCAL`	`LOCAL`

If the source is still running, or you are not sure, use a checkout. Activation is for succession.

Before you activate

Retire the source first. “Retired” means the old writer will never accept another change: the SynckHub workspace is closed or the server is switched off for good. If the source kept accepting changes after your copy took over, you would have two writers for the same history. Synck has no way to reconcile them later, because there are no merges.

Use your newest complete copy. Anything the source accepted after your copy’s checkpoint is not in it, and cannot be added later.

Keep the export untouched. Activate a copy made with synck repository import, and keep the original export as a reference.

Activate

$ synck repository import launch-project launch-continued
$ synck repository activate launch-continued --author "Alex" --source-retired
{"authority":"LOCAL","repo_id":"01a174b7-8a7d-74e0-b0d7-81b1dcfa6ccd","schema_version":1}

--source-retired is required. It is your acknowledgment, recorded in the command line you typed, that the previous writer is gone. Synck cannot check this for you. Activation does not contact the source, and cannot stop a machine you no longer control from writing. It records your decision and the author for future changes. It adds no commit, and every existing author, date and ID is preserved.

Continue the history

An activated repository accepts four kinds of change directly, without a checkout. Each one prints the ID of the commit it recorded. The same commands also work in any repository with a checkout.

Create a file, at the top level or, with --parent, inside a folder:

$ synck repository create-file contract.txt ~/Documents/contract.txt --parent 01a174b7-8a7d-74e0-b0d7-81cf3866d6b9 --path launch-continued
{"commit_id":"sha256:551afeb4d5b3cfd3b3dcaf745747b48d6eeba17ffbc7f9ec73950e076006f9dc","item_id":"01a17492-4efb-7e51-a6f8-a97cc19a51e2","schema_version":1}

Save new content to an existing file. Its identity and earlier versions are kept:

$ synck repository save-file 01a174b7-8f4e-76f1-8ac4-440db922fb52 ~/Documents/proposal-v3.txt --path launch-continued
{"commit_id":"sha256:a05d17184476424ffcffaa1bdbca68835832cf69d82376147ae7d2fcbda0aa0f","schema_version":1}

Start a chat. The title is what people see; the chat gets a new item ID:

$ synck repository create-chat "Handover" --path launch-continued
{"commit_id":"sha256:40acf9cc32dd9296364098145f579dd4ce6e33653c3ac833051a05cc41ecd68a","item_id":"01a1795b-cb5c-7736-9772-d43242cc4770","schema_version":1}

Add a message to a chat. The body is read from a UTF-8 text file. Add --attachment FILE, once per file, to attach files to the message:

$ printf 'Sent to the client.' > message.txt
$ synck repository append-chat 01a174b7-8a7d-74e0-b0d7-81d946ca6792 message.txt --path launch-continued
{"commit_id":"sha256:d9a6cddb68e36424147818ffd9d2d8eec5cac3b1743eef7c8a3e57783a3f7759","schema_version":1}

For wider file editing, such as renaming, moving, deleting or reorganizing folders, check out the activated repository and work with ordinary files. Its authority stays LOCAL.

These commands are deliberately narrow. They do not reproduce every SynckHub workflow. You cannot edit a task’s state or send mail, and there is no general command for writing arbitrary events. The data model for all of those is preserved and readable. The applications that edited them are not part of Synck.

Items sequenced elsewhere

Some items are not ordered by their repository at all. In a federated SynckHub setup, a shared item may be sequenced by an external authority that several organizations’ repositories follow. In item list, such items show a sequencing_mode other than LOCAL and a federation_stream_id.

Activation never takes over those items. Your copy keeps everything it received for them, and you can read and export them. But the right to extend their history belongs to their own authority, which is not your repository.

If a write is interrupted

A write happens in two stages: first the change is accepted into the history, then Synck brings its indexes up to date. If the second stage fails, for example because the disk filled up or the process was killed, the command reports that the commit was accepted and needs recovery:

$ synck repository save-file ...
synck: commit sha256:2776…edf1 was accepted; local recovery is pending: ...

With --json, the error’s kind is ACCEPTED_NEEDS_RECOVERY.

The change is in the history. Do not run the command again, because that would record the change a second time, for example as a duplicate message. Note the commit ID, fix the underlying problem, then finish the job:

$ synck repository finalize launch-continued
{"finalized":"launch-continued","schema_version":1}
$ synck repository verify launch-continued

Reading a repository never runs this recovery by itself. Until you run finalize, verify reports that the repository has incomplete sequencing.

Editing files

Backup and recovery