Skip to content

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.

  • 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.json names 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: migrate and remove are 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 migrate says refs/remotes/origin/HEAD is missing, run git remote set-head origin --auto.
Terminal window
vaultfold doctor

same-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.

Terminal window
vaultfold vault migrate

It 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.

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.

Terminal window
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.

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 them

The warning is informational. Once the directory is gone, the import stops.

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.

Terminal window
vaultfold vault remove acme

This 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.

  • A Windows run of the migration has not happened yet on real hardware.
  • A teammate on an older vaultfold cannot read a vault.toml with branch in it: it fails naming the unknown key, which keeps them from syncing a stale copy.