Git Hooks

A post-commit hook writes trace IDs into git notes on each commit. The notes travel with commits when pushed, so collaborators can look up the traces that produced any change.

Setup

traces setup git

This installs .git/hooks/traces-post-commit and injects a guarded call into .git/hooks/post-commit. It chains with existing hooks (husky, lefthook, project hooks) without overwriting them. It also configures a per-repo fetch refspec so notes sync on pull.

Running traces setup (the interactive flow) also offers to install git hooks after agent skill selection.

What the hook does

On each commit, the hook:

1. Runs traces list --dir . --since <previous commit timestamp> to find recent traces
2. Writes their external IDs into refs/notes/traces on the commit
3. Runs traces share in the background to upload unshared traces
4. Pushes notes to the remote

Multiple traces can attach to a single commit, and multiple commits can reference the same trace.

Note format

One trace per line, shared URL appended when available:

traces:<externalId> <sharedUrl>
traces:<externalId>

The traces: prefix prevents collisions with other tools using git notes. Notes are appended, not replaced, so multiple collaborators can add trace IDs to the same commit.

Verifying

# Check note on latest commit
git notes --ref=traces show HEAD

# View notes inline with commit log
git log --notes=traces -3

# Run health check
traces doctor

Removing

traces remove git

Removes the hook file and the injected call from .git/hooks/post-commit, leaving other hooks intact.