Skip to main content

​
Per user

With no --agent, install looks for each agent by its configuration directory, its application path and its command, configures every one it finds, and prints the list. Forgetting the flag used to configure Claude Code alone and leave the rest ungated, which is indistinguishable from not installing at all.
  • Default policy → ~/.gitvow/policy.json (created only if absent, so your edits survive reinstalls)
  • Four git hooks → ~/.gitvow/git-hooks/ (prepare-commit-msg, pre-commit, post-commit, pre-push), registered as the global core.hooksPath
  • Hook entries merged into each agent’s settings file, using the absolute path of the gitvow executable, so hooks work even when the agent’s shell has no virtualenv or pipx directory on its PATH. This matters most for desktop agents such as Cursor, which do not inherit the PATH of your terminal at all.
  • Whatever the agent still needs by hand, printed at the end. Codex CLI has two such steps; see Use gitvow with other agents.
  • A pre-push hook in the same directory that pushes refs/notes/gitvow/* to the remote you push to
  • Global git config notes.displayRef and notes.rewriteRef set to refs/notes/gitvow/*, so git log --show-notes shows session notes and they follow amend and rebase (not squash; see the FAQ)
Covers every repository you open. Nothing is committed anywhere. If you already had a global hooks path, gitvow reports it; its hook chains to each repository’s own .git/hooks/prepare-commit-msg, not to a previous global path.

​
Per repo

  • Policy and git hook → <repo>/.gitvow/
  • Hook entries merged into <repo>/.claude/settings.json (or that agent’s file), using the bare command gitvow because the file is shared by people with different install paths; every teammate needs gitvow on the PATH their agent’s shell gives it. A desktop agent started from Finder or Spotlight often has a minimal PATH, so a per-user install alongside is safer there. gitvow status reports this as a note rather than leaving you to find out.
  • core.hooksPath set to .gitvow/git-hooks for that repository
  • Repository git config notes.displayRef and notes.rewriteRef set to refs/notes/gitvow/*
  • A pre-push hook that pushes session notes with every push
Commit .gitvow/ and .claude/settings.json to share. Each teammate runs once: git config core.hooksPath .gitvow/git-hooks. Use this once a team has agreed a policy: it is reviewed in pull requests, and gate paths are specific to the repository.

​
Precedence

Policy lookup: <repo>/.gitvow/policy.json, then ~/.gitvow/policy.json, then the package default. Hooks in both user and repository settings run; gitvow’s entries are idempotent, so installing twice never duplicates them and never disturbs hooks you added yourself.

​
Upgrading

Rerunning gitvow install after an upgrade refreshes the hook bodies and, since 0.28.3, the policy file if it is an untouched copy of an older default: the copy carries _from_default, the digest of its own body, and a body that still matches the marker is replaced by the current default. A policy you edited is left alone and named in the output; a copy made before 0.28.3 has no marker and is also left alone, with gitvow policy to compare it against the current default. To take the new default in that case, delete the file and rerun gitvow install once.

​
Upgrading (older notes)

pip install --upgrade gitvow replaces the package but not the git hook files written by install, nor the hook commands in settings. After upgrading, re-run the same install command you used (gitvow install --user or gitvow install <repo>). It is idempotent and refreshes both. With uv, upgrade with uv tool upgrade gitvow. In the minutes after a release the package index can lag behind the release page, and uv tool install --reinstall --refresh gitvow then quietly reinstalls the previous version; pin when it matters: uv tool install --reinstall "gitvow==0.32.0". Check with gitvow --version before re-running install. gitvow status detects an install left behind by an older release: git hooks whose contents differ from what this version writes, and agent settings missing events this version installs. Both matter. An install from before 0.12 has no pre-commit or post-commit hook, so the decision card never fires on a commit made by a person, and nothing else would tell you. Repositories that committed .gitvow/ refresh it in a pull request like any other change.

​
Uninstall

Removes exactly what install added, including the git config keys when they still hold gitvow’s values. Leaves commit trailers already in history, notes already pushed, and the ledger unless asked. --purge-notes deletes every local refs/notes/gitvow/* ref.

​
Restart any session that was already open

Every agent except Cursor reads its hook configuration once, when the session starts. Install gitvow while a session is open and that session keeps working, ungated, and says nothing about it. Cursor watches its hook file and reloads on its own. install says this per agent, and gitvow status tests for the real thing rather than repeating the advice: if a commit made after the install carries an agent’s signature but no session, it fails and tells you to restart. Commits from before the install are ignored, because they are uncovered by construction.

​
See the record work, in the status bar

gitvow status --line prints one line from the current repository’s session state: decisions answered, findings recorded without asking anyone, findings still open, questions a person actually got, calls refused. Claude Code renders it live:
in ~/.claude/settings.json. The counts are what the record holds, not an estimate of anything; a repository with no session says so instead of showing a clean-looking row of zeros.

​
Install is safe to rerun, and refuses a redirected target

Rerunning gitvow install rewrites nothing whose bytes are already current, so mtimes stay put (the install stamp status reads is a hook’s mtime). Every write into a repository is preflighted: a target that resolves outside the repository, into its git directory, onto something that is not a regular file, or onto a hard link is refused by name and nothing is written. A checked-in symlink at .claude/settings.json cannot redirect the install. See What gitvow reads, writes, executes and sends.

​
If hooks silently do nothing

Most agents treat a hook command they cannot run as a non-blocking error and carry on, which switches the gate off with no visible failure. That is the worst outcome, so there is a command for exactly this:
status resolves the command each agent will actually run and fails when it cannot be executed. If the recorded command is a bare gitvow and your install lives in a virtualenv, either install with pipx install gitvow or pip install --user gitvow so it is on the PATH everywhere, or re-run the per-user install so the absolute path is recorded. Claude Code’s /hooks view also shows hook errors, and Codex needs its hooks trusted before they run at all.

​
Pause without uninstalling

git config --global --unset core.hooksPath stops trailers. The gate keeps running until the hooks are removed. To relax the gate temporarily, edit the policy lists rather than removing the file: a missing policy fails closed.