Skip to content

Sync and resolve conflicts

A vault is a set of write-once files, so two people never overwrite each other. When two people change the same field at once, both values are kept until one of you chooses.

  • A vault in a git repository with a reachable remote.
  • Permission to write to the remote.

sync fetches, verifies, merges and pushes. Run it after changes, and before you start work.

Terminal window
vaultfold sync

It prints how many events it sent and received and how many it rejected. Rejected events are ones the vault's rules do not allow, for example a write by a key that was revoked.

If two writers changed the same field before syncing, get lists both values and exits 2 instead of guessing.

Terminal window
vaultfold sync
vaultfold get app/db#password

resolve shows the candidates (masked), then records your choice. Pass --pick n to choose without the prompt; add --reveal on a terminal to see the values first.

Terminal window
vaultfold resolve app/db#password
vaultfold resolve app/db#password --pick 1
vaultfold sync

A vault on its own branch (the default for init) pushes only that branch, from whatever branch you have checked out. It never rebases or force-pushes, and it works while your code branch is protected. If the forge refuses the push, sync exits 4 with sync-protected, quotes the forge's message and keeps your events queued; see protect the vault branch for the rules a vault branch needs.

A vault kept on a code branch (init --same-branch) only pushes its own files. If local commits also change other files, sync pushes nothing and tells you to push with git, or run vaultfold sync --push-all to push them as well. If that branch is protected, move the vault to its own branch with vault migrate.

If sync detects that the remote history or the heads you last saw went backwards, it stops with exit 2. After you have investigated, accept it with vaultfold sync --accept-rollback, which records the decision in the audit log.

Membership changes form a policy chain, and sync also refuses (exit 2) when a link you had already seen is missing (policy-rollback) or replaced (policy-fork), naming the records and their authors. vaultfold never picks a side for you. Check the tip with those people, for example by comparing the chain fingerprint vaultfold key verify prints, then accept that tip with vaultfold sync --accept-rollback <fingerprint>; it is refused, and nothing changes, if the remote now shows a different tip.

Membership commands (member add, revoke, grant, ungrant and rename, device revoke, epoch new, collection new, key rotate) do not wait for sync: they pull and publish as they run. In a shared folder two admins can still write the same policy slot offline; the one whose record lost is told by the command that finds it, by sync and by vaultfold doctor (policy-write-lost). On a terminal sync offers to apply a lost grant, role removal or device revocation graded lost again; for any other record it tells you which command to run again.

A lost revocation did not happen: the report says the device or member is still active and names the revocation command to run again (for example vaultfold device revoke <device>), and sync and doctor keep reporting it until the device or member is revoked. A new epoch does not settle it. If the device rotated its key in the meantime, the report names the newer key, since revoking the old one is not enough.

A lost epoch new, revocation or grant also leaves its key wrap files in the folder. They block nothing: every wrap file sits in a directory named after the policy record that calls for it (epochs/<collection>/<epoch>/<link>/<keyid>.wrap), so the command you run again, or anyone else's, writes beside them and succeeds. sync uses the leftover files only to recover what this device wrote under its own lost record, and vaultfold doctor lists each as stray-wrap, a warning that needs no action.

  • Vault commands start the agent daemon and unlock once. Set VAULTFOLD_NO_AGENT=1 to skip the daemon and unlock in-process for that command only.
  • Only git repositories and plain folders are supported as backends; hosted, s3:// and dav:// locations are refused.
  • vaultfold never prompts to merge: it keeps concurrent values until resolve.
  • The local cache is safe to delete, at the cost of restarting rollback detection from now.