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.
Prerequisites
Section titled “Prerequisites”- A vault in a git repository with a reachable remote.
- Permission to write to the remote.
Share changes
Section titled “Share changes”sync fetches, verifies, merges and pushes. Run it after changes, and before
you start work.
vaultfold syncIt 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.
See a conflict
Section titled “See a conflict”If two writers changed the same field before syncing, get lists both values
and exits 2 instead of guessing.
vaultfold syncvaultfold get app/db#passwordChoose a value
Section titled “Choose a value”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.
vaultfold resolve app/db#passwordvaultfold resolve app/db#password --pick 1vaultfold syncOther sync problems
Section titled “Other sync problems”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.
Current limitations
Section titled “Current limitations”- Vault commands start the agent daemon and unlock once. Set
VAULTFOLD_NO_AGENT=1to skip the daemon and unlock in-process for that command only. - Only git repositories and plain folders are supported as backends; hosted,
s3://anddav://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.