Move a vault to its own branch
A new in-repo vault lives on its own branch (vaultfold by default). It is
written with git plumbing, so nothing is checked out, nothing is committed on
your code branch, and the repository's commit hooks never run. That works in
repositories whose code branches are protected, and in ones with hooks that
classify or reject paths.
Older vaults live in .vaultfold/ on the code branch, or in a worktree someone
set up by hand. vaultfold vault migrate moves them without losing an event.
Prerequisites
Section titled “Prerequisites”- An admin applied the branch rules from protect the vault branch first. If the remote already has the vault branch, migrate adopts it as long as its
vault.jsonnames the same vault. It does not check who created it, so a branch created by someone else before the rules existed could hold planted files. - You are a member of the vault, and a human at a terminal:
migrateandremoveare refused in agent sessions. - For a vault committed on the code branch: the repository's default branch is checked out, tracks its remote branch, and is fetched. If
migratesaysrefs/remotes/origin/HEADis missing, rungit remote set-head origin --auto.
Find out which case you have
Section titled “Find out which case you have”vaultfold doctorsame-branch-vault means the vault predates branch mode and works unchanged.
vault-worktree-layout means a hand-made worktree. vault-moved-to-branch
means a teammate migrated and your machine still uses the old layout.
Move a vault committed on the code branch
Section titled “Move a vault committed on the code branch”vaultfold vault migrateIt copies the vault into a local mirror, creates the vaultfold branch on the
remote (--branch picks another name), and adds branch to vault.toml. It
then prints the team steps: land the vault.toml change and the removal of the
old .vaultfold/ directory through your normal pull request flow. History
keeps the old ciphertext, which vaultfold assumes is public anyway.
It either keeps every record or refuses before changing anything. A vault
directory that is incomplete, that differs from the remote's default branch,
that holds records failing verification, or that holds records beyond the
remote's tip that your device did not write is refused with the files named.
Files that are not records of the vault are skipped, and migrate prints one
warning with their count.
Move a vault set up by hand
Section titled “Move a vault set up by hand”If the vault is on an orphan branch checked out in a separate worktree,
migrate adopts that branch, copies the worktree's vault files (committed or
not), switches your registration to the mirror, syncs once, and offers to
remove the worktree and, once its tip is on the remote, the local branch.
vaultfold vault migrate --remove-worktree--remove-worktree answers yes to both offers. Git refuses to remove a
worktree with uncommitted changes, and the files are already in the mirror
either way. If the branch holds other root files, for example a committed
.githooks/, migrate refuses and names them. Commit and push their removal
on that branch, then run it again.
Teammates who have not moved yet
Section titled “Teammates who have not moved yet”Until the old directory disappears from your work tree (after you pull the
change that removes it), teammates may keep writing to it. Each migrated member's sync imports, read-only, what the vault
branch lacks from that directory. It imports only what verifies: the old
vault.json must name the same vault, events and policy records must match the
hash in their file name and be accepted by a trial fold, and key and wrap files
only when an accepted policy record requires that exact file. Anything else is
skipped, and sync prints one warning with the count:
warning: vault "acme": 3 file(s) in <dir> were not imported (not verified, not needed by the vault, or different from the vault branch's); the vault branch was not changed by themThe warning is informational. Once the directory is gone, the import stops.
Keep a vault on the code branch
Section titled “Keep a vault on the code branch”Add same_branch = true to the vault's table in vault.toml. New vaults can
ask for this layout with vaultfold init --same-branch. It runs the
repository's hooks, which can refuse the init commit; init then names the
directory to commit yourself. It is refused on a branch the forge protects,
unless you pass --force.
Remove a vault from this machine
Section titled “Remove a vault from this machine”vaultfold vault remove acmeThis unregisters the vault and deletes only what vaultfold made for it: the
local mirror or clone, its private ref, a copied token file and the cache. It
never touches a directory you registered, an in-repo .vaultfold/, the remote
branch, the remote repository or a hosted service. It refuses when that would
lose events you have not pushed (run vaultfold sync, or pass --force) and
asks to confirm; --yes skips the question but not the refusal.
Current limitations
Section titled “Current limitations”- A Windows run of the migration has not happened yet on real hardware.
- A teammate on an older vaultfold cannot read a
vault.tomlwithbranchin it: it fails naming the unknown key, which keeps them from syncing a stale copy.