Keep several devices in sync

Pull before you edit

Dotweave never runs git pull itself, so a machine you have not touched in a while still holds a stale sync directory. Fetching the repository and applying it to your home directory are two separate commands, and they run in that order.

Open the sync directory, fetch, leave the child shell, then apply:

dotweave cd
git pull
exit
dotweave pull

dotweave cd spawns a child shell rooted at the sync directory, and exit returns you to the shell you started from. Only after git pull has updated the work tree does dotweave pull have the new artifacts to write.

Editing before you pull is what produces divergence. You commit on top of a stale history, and the two machines now disagree about the same file.

Resolve divergence with git, not Dotweave

Dotweave performs no merge. There is no three-way merge, no conflict markers written by Dotweave, and no resolution UI. When two machines have each pushed and committed, what you have is a git divergence in the sync repository, and you settle it with git inside dotweave cd.

Artifacts are plain files, and dotweave init writes a .gitattributes containing * -text so git does not rewrite line endings. A git diff of the sync repository is therefore readable for normal artifacts, and you can merge them line by line like any other text.

Secret artifacts are age ciphertext. A diff of one is not human-readable and cannot be merged line by line, so reconcile a secret by choosing one side, then push the plaintext again from the machine that holds the version you want.

Give each machine a profile

Configuration that differs per machine belongs in a profile rather than in a shared entry. Register the name, restrict the machine-specific entries to it, and select it on the machine it describes:

dotweave profile add work
dotweave track ~/.config/work-vpn --profile work
dotweave profile use work

The selection is stored in settings.jsonc in the dotweave home directory. That directory sits outside the sync directory and is never committed, so each machine chooses independently.

An entry assigned to a profile is invisible while a different profile is active. It does not appear in dotweave status, and neither push nor pull considers it. Check the active profile before you conclude that an entry was lost.

push never prunes another profile's artifacts, so one repository holds every machine's configuration side by side.

Secrets add one requirement per machine. The machine's public key must be listed in manifest.jsonc under age.recipients, and the matching private key must sit in that machine's own keys.txt. A machine missing either one cannot decrypt what the others wrote; read Secrets and encryption for how the keys are managed.

Implementation and reference

The visibility rule and the machine-local selection are described in Profiles.

Read dotweave pull for the flags that let you inspect a plan before applying it, or dotweave cd for the shell where you run git against the sync repository.