beads/docs/reference/git-integration.md
Tomasz Feliksik 33bed587e0
Accept uutils coreutils timeout in generated hooks, and check the shims against real implementations (#6561)
* Accept uutils coreutils timeout in generated hooks

The generated hook selects a timeout helper only when its --version
banner starts with "timeout (GNU coreutils) ". uutils coreutils reports
"timeout (uutils coreutils) " with the same command line and the same
exit 124 on expiry, so hosts that ship it (Ubuntu 25.10+, NixOS with
uutils-coreutils-noprefix) silently fell through to the Perl alarm, or
to the unbounded direct run when Perl is absent. Follow-up from #5522,
tracked in #5541.

- Widen the identity allowlist to uutils; the match stays by banner so
  Windows timeout.exe is still never probed (#5503).
- Add a backend-selection case using the GNU stub with the uutils
  banner: fails on the old shim (selects gtimeout), passes with the
  widening.
- Regenerate the managed sections in the tracked .githooks/* so
  TestTrackedManagedHookSectionsMatchGenerator stays green.
- Update the hook-timeout passages in docs/reference/git-integration.md
  and troubleshooting.md, which described the probe as GNU-only.

Verified on NixOS with uutils 0.10.0 as /run/current-system/sw/bin/timeout:
with Perl removed from PATH and a bd that hangs, the old shim runs
"without timeout" for the full duration; the new shim expires at
BEADS_HOOK_TIMEOUT and continues.

Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik

* Regenerate tracked .githooks managed sections with make githooks-regen

TestTrackedManagedHookSectionsMatchGenerator holds the managed section in
each tracked .githooks/* byte-equal to the cmd/bd/hooks.go generator, but
nothing regenerated them: after a generator change a contributor had to
splice the new section in by hand, and the failure only dumped both
texts. The v1.2.0 bump reddened main this way (ce20a64bb), and #6561 shipped
its first revision with the five hooks stale.

- BD_UPDATE_GOLDEN=1 makes the test rewrite the section in place, keeping
  everything around the markers (the project's own hook logic) untouched.
  Same switch the package's events golden already uses.
- `make githooks-regen` wraps it, next to `corpus-regen`.
- The drift failure now names that command.
- The exactly-one-section check runs before any rewrite.

Verified: drifting one byte inside .githooks/pre-push fails the test with
the hint; `make githooks-regen` restores the file to the same blob SHA;
the test is green again.

Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik

* Check the tracked hook shims against real timeout implementations

The Go tests pin the shim's helper selection with scripted stand-ins, so
they can only encode what the author believes each real `timeout` does.
That is where the last two defects lived: uutils prints a banner the
allowlist did not know (#5541), and busybox — which #5541 suggests
adding — exits 143 on expiry rather than 124, so allowlisting it would
turn every deadline into a failed hook and a blocked push.

checks.nix adds a flake check that runs the tracked .githooks/* managed
sections (held equal to the generator by
TestTrackedManagedHookSectionsMatchGenerator) against the binaries
themselves: GNU coreutils, uutils, busybox and toybox `timeout`, each
with and without perl, under dash, bash and busybox ash, for all five
hooks — 150 cases. Expectations come from a model of the contract (the
allowlist as data), so widening it is one line here and the binaries
either agree or they do not.

A fake bd on the shim's restricted PATH blocks on a held-open fifo until
a helper kills it, records the signal and re-raises it, so each case
asserts the backend that ran (TERM from timeout, ALRM from perl's alarm)
and not merely that the shim finished. No clock: a helper that fails to
kill the fake trips the harness's own `timeout 10`. Every case asserts
exit 0, since anything else blocks the user's push. Reading .githooks/*
instead of building bd keeps it at ~1 s and off the Go build's critical
path; CI's test-nix job runs it after its existing help-text smoke test.

Mutation-checked: restoring main's GNU-only sections fails all 30 uutils
cases (15 unbounded, 15 on the perl backend); allowlisting busybox with
a loosened probe fails all 30 busybox cases with hook exit 143.

Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik

* Run the hook-timeout check under the gtimeout candidate name too

The shim probes `timeout` and then `gtimeout`, but the matrix only ever
put a binary named `timeout` on PATH, so the second candidate was never
run against a real implementation. Whether a helper is accepted under
that name depends on what its banner does with argv[0].

Measured: the uutils multicall dispatches on the argv[0] SUFFIX
(src/bin/coreutils.rs, `binary_as_util.ends_with(util)`) and then prints
the canonical utility name — invoked as gtimeout it reports
"timeout (uutils coreutils) 0.8.0" (this flake's nixos-25.11 pin; 0.11.0
identical), which the allowlist accepts. busybox and toybox know no
gtimeout applet and fail the probe outright, rejected as before. GNU is
immune by construction: Homebrew's gtimeout is a separate binary whose
banner is the fixed "timeout (GNU coreutils) 9.11"; nixpkgs' coreutils
is a single-binary multicall that refuses a foreign name ("unknown
program 'gtimeout'"), so it gets no variant here.

Each multicall is now also installed on a case PATH as `gtimeout` ALONE
(`installs`, derived from `implementations`; `backendFor` stays keyed on
the implementation, so the model's claim is "uutils is allowlisted
whatever it is called"). 240 cases on Linux, 80 on darwin (no busybox or
toybox there, and no busybox-ash shell). The shadowed
`out=` inside run_case is `case_out` now: it only survived because every
case is a backgrounded subshell, and a de-backgrounded case would have
died on the final `touch "$out"`.

Mutation-checked: installing the variant as `xtimeout` (a name the shim
never probes) fails exactly the 30 uutils-as-gtimeout cases — 15 with
nothing killing the fake bd, 15 on the perl backend (ALRM) instead of
coreutils; restored, 240 of 240 pass. The busybox/toybox variants cannot
distinguish (their expectation is rejection either way); their weight is
that the probe does not blow up on a foreign name.

* Run the flake checks on main too, by nix flake check; docs wording

pr-risk.yml's test-nix job ran the hook-timeout check on PRs only; the
byte-identical job in main.yml never got the step, so post-merge main
never ran it. Both jobs now run `nix flake check -L`: no hardcoded
`x86_64-linux` (the step beside it, `nix run .#default`, was already
system-agnostic), and a check added to checks.nix runs without a
workflow edit. checks.aarch64-darwin and .x86_64-darwin evaluate.

Measured on ubuntu-latest with a cold Nix store (fork run 35700791032,
this tree, 240 cases): `nix flake check -L` 3.6 s including substitution
of uutils, busybox, toybox, dash and perl; 0.08 s warm — beside the
4 min 9 s the existing `nix run .#default` step spends building bd in
the same job. The 10-minute timeout is not in question.

git-integration.md: on Git for Windows the preferred deadline backend is
"a coreutils timeout (GNU or uutils)", not GNU alone, since both now
qualify. troubleshooting.md: reflow a ragged paragraph.

* review: close the duplicated contracts around the uutils timeout accept

Maintainer review fixes for #6561. No change to the shim's behavior or to the
generated/tracked hook sections.

- cmd/bd/hooks_timeout_process_test.go: the uutils fixture was built with
  strings.Replace, which returns its input unchanged when the pattern is
  absent, so a later edit to the GNU stub's banner would silently degenerate
  the uutils case into a second copy of the GNU one — still green, no longer
  testing the new accept. Hoist the derivation and fail loudly when the banner
  no longer matches.
- cmd/bd/hooks_timeout_process_test.go: findHookProcessGNUTimeout held a second,
  un-widened copy of the identity allowlist, so on exactly the hosts this PR
  exists for (uutils timeout, no gtimeout) the only Go test that drives a real
  timeout binary skipped with a reason the fix had just made false. Widen the
  probe's case, rename it findHookProcessCoreutilsTimeout, and reword the skip
  and the subtest. Measured against stub PATHs: uutils goes rc=1 -> rc=0, GNU
  stays rc=0, a busybox banner stays rc=1.
- cmd/bd/init_hooks_test.go: TestGenerateHookSection_Timeout asserted only the
  GNU alternative, so deleting the new uutils one from the generator left the
  structural contract green (verified: it passes under that mutation before
  this change, and reports "section missing uutils coreutils identity check"
  after). Add the companion assertion.
- cmd/bd/init_hooks_test.go, Makefile: the regen arm rewrites tracked source
  files, so give it its own BD_UPDATE_HOOKS_GOLDEN rather than the package's
  shared BD_UPDATE_GOLDEN — an unscoped `BD_UPDATE_GOLDEN=1 go test ./cmd/bd/`
  used to turn genuine hook drift into a silent working-tree rewrite that
  reported PASS.
- cmd/bd/init_hooks_test.go: locate the managed section by marker prefix
  instead of the versioned marker line. Tracked hooks drift both from generator
  content and from the release version stamp; the exact-line lookup made the
  second class fatal ("tracked hook missing ...") before the regen arm was
  reachable, so `make githooks-regen` failed at exactly the moment a release
  engineer reaches for it. The versioned markers are still verified — they are
  part of the byte compare.
- checks.nix: the `rc -eq 124` safety-net verdict discarded both $case_out and
  the already-captured $signal, so the one failure mode that is intermittent
  and not locally reproducible was also the only one with no diagnostics.
  Report them like the `rc -ne 0` branch below it.
- docs/reference/troubleshooting.md, docs/reference/git-integration.md: mirror
  the coreutils wording across both docs this PR touches, and generalize the
  re-install guidance in both. Managed sections are never reported Outdated
  (getHookVersion returns IsShim for them and computeHookStatuses gates on
  !IsShim), so nothing tells an existing install it is stale; the sentence was
  still scoped to the older name-only check (#5503).
- CHANGELOG.md: add the [Unreleased] entry for #5541, worded to the actual
  scope — with Perl installed the shim still reached the Perl alarm arm, so the
  lost deadline bit uutils hosts without Perl — say that existing installs must
  run `bd hooks install` once, and drop the claim that stock NixOS ships uutils
  (this PR's own checks.nix takes GNU from pkgs.coreutils).

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-27 03:38:45 -07:00

11 KiB

title description
Git Integration How bd uses git for hosting and hooks, including hook installation, external hook managers, worktrees, and branch workflows.

How beads integrates with git.

Overview

Beads uses git for:

  • Project hosting - Your code repository also hosts beads configuration
  • Hooks - Auto-sync on git operations

Data storage and sync are handled by Dolt (a version-controlled SQL database) — see Sync Concepts for how issue data moves between machines.

File Structure

.beads/
├── config.yaml        # Project config (git-tracked)
├── metadata.json      # Backend metadata (git-tracked)
├── .gitignore         # Written by bd init (git-tracked)
├── embeddeddolt/      # Dolt database — embedded mode, the default (gitignored)
└── dolt/              # Dolt database — server mode (gitignored)

bd init writes .beads/.gitignore to keep the database directory and runtime files out of git — no manual gitignore rules are needed. Never track the database directory (.beads/embeddeddolt/ or .beads/dolt/) in git or via Git LFS.

Git Hooks

Installation

bd init installs hooks by default (skip with bd init --skip-hooks). To install or refresh them manually:

bd hooks install

Installed hooks are thin shims that call bd hooks run <hook-name>. Upgrading bd automatically updates the delegated behavior inside that command; the shim's generated shell policy remains installed content and changes only when the hook is installed or refreshed:

Hook What it does
pre-commit Runs chained hooks; when export.auto is enabled, exports .beads/issues.jsonl so it lands in the same commit
post-merge Runs chained hooks; imports JSONL only as a legacy fallback when no Dolt remote is configured — with sync.remote set, bd dolt pull is the canonical sync
pre-push Runs chained hooks before push
post-checkout Runs chained hooks after branch checkout
prepare-commit-msg Adds an Executed-By: agent identity trailer when an agent (BD_ACTOR) makes the commit

The shims use section markers to coexist with existing hooks — content outside the markers is preserved across installs and upgrades. Install variants:

bd hooks install --beads    # Install to .beads/hooks/ (recommended for the Dolt backend)
bd hooks install --shared   # Install to .beads-hooks/ (versioned, shareable with the team)
bd hooks install --chain    # Run existing hooks before bd hooks

Hook installation is worktree-aware: bd resolves the shared git directory, so installing from a linked worktree works.

Status

bd hooks list

Uninstall

bd hooks uninstall

External Hook Managers

bd detects these external git hook managers and checks whether their config calls bd hooks run:

  • lefthook — YAML/TOML/JSON config
  • husky — .husky/ directory scripts
  • pre-commit — .pre-commit-config.yaml
  • prek — Rust-based pre-commit alternative (same config)
  • hk — fast hook manager using Pkl config
  • overcommit — Ruby-based (detection only)
  • yorkie — detection only
  • simple-git-hooks — lightweight JS (detection only)

bd doctor reports whether a detected manager is integrated with bd, and bd doctor --fix reinstalls the hooks with --chain so the manager's existing hooks keep running.

For config-driven managers, add bd steps directly. Example hk.pkl:

hooks {
    ["pre-commit"] {
        steps {
            ["bd-pre-commit"] {
                check = "bd hooks run pre-commit"
            }
        }
    }
    ["post-merge"] {
        steps {
            ["bd-post-merge"] {
                check = "bd hooks run post-merge"
            }
        }
    }
    ["pre-push"] {
        steps {
            ["bd-pre-push"] {
                check = "bd hooks run pre-push \"$@\""
            }
        }
    }
}

Hook Timeout

The hook shim applies a soft deadline to bd hooks run when a compatible helper is available. It uses timeout or gtimeout only after a successful identity probe for GNU coreutils or uutils coreutils (same command line, same exit status), avoiding the incompatible timeout.exe that native Windows can place on PATH. The coreutils helper sends TERM at the configured deadline. On POSIX hosts, the Perl fallback uses SIGALRM on the direct bd process at the deadline. Git for Windows Perl does not guarantee that alarm across exec, so a coreutils timeout (GNU or uutils) is the preferred deadline backend there.

The default deadline is 300 seconds (5 minutes), which accommodates chained pre-commit pipelines (eslint, prettier, TypeScript compilation). Override it with the BEADS_HOOK_TIMEOUT environment variable:

# Set a longer timeout (in seconds)
export BEADS_HOOK_TIMEOUT=600  # 10 minutes

# Or set it per-invocation
BEADS_HOOK_TIMEOUT=600 git commit -m "..."

The value must be a positive whole number of seconds. Invalid values and zero produce a warning and use the 300-second default. These are soft process deadlines, not process-tree containment: TERM-resistant work or descendants can outlive them. If neither a coreutils timeout nor Perl is available, the hook warns and runs directly without a deadline; that last-resort path can hang until the hook itself returns.

Already-installed hook sections are not refreshed automatically. After upgrading to a release that changed the generated timeout probe — the name-only check, or the uutils coreutils banner — run bd hooks install once to refresh already-installed canonical hook sections. Automatic generated-policy adoption is tracked separately.

When the timeout is reached, beads prints a warning and lets the git operation proceed — the commit or push is not blocked.

Conflict Resolution

Dolt handles merge conflicts at the database level using its built-in merge capabilities. When conflicts arise during sync, Dolt identifies conflicting rows and allows resolution through SQL.

# Check for and fix conflicts
bd doctor --fix

Protected Branches

Dolt stores data under refs/dolt/data, separate from Git refs. This means beads data does not conflict with protected Git branches, and no separate beads-sync branch or protected-branch exception is needed. On new projects with a Git origin, bd init configures that origin as the Dolt remote automatically.

See Protected Branches for the full workflow, including legacy beads-sync cleanup.

Git Worktrees

Beads works in Git worktrees without extra setup. Linked worktrees discover the repository's .beads workspace and sync issue data through Dolt:

# In a linked worktree
bd create "Task"
bd list
bd dolt pull
bd dolt push

All worktrees share the repository's .beads workspace: discovery follows BEADS_DIR if set, then the main repository's .beads, preventing database duplication across worktrees. Use bd where as the authoritative check for which workspace is active — a local ./.beads may legitimately be absent in a worktree. Embedded mode (the default) serves one writer at a time; for concurrent writers across worktrees, use server mode. See Git Worktrees for the full guide.

Older beads versions documented a sync.branch workflow that created hidden Git worktrees. That workflow has been removed; current sync uses Dolt remotes.

Branch Workflows

Feature Branch

git checkout -b feature-x
bd create "Feature X" -t feature
# Work...
bd dolt push
git push

Fork Workflow

# In fork
bd init --contributor   # Interactive wizard
# Work in separate planning repo...
bd dolt push

The contributor wizard keeps issue data in a separate planning repository, leaving the upstream repo without any .beads/. Best for open source contributors, solo developers, and private task tracking on public repos.

bd init auto-detects forks and offers to configure .git/info/exclude (--setup-exclude) so beads files stay local. Set the role without prompting via --role contributor or --role maintainer (the default in non-interactive mode).

Team Workflow

bd init --team
# All team members share the Dolt database
bd dolt pull   # Pull latest changes from Dolt remote
bd dolt push   # Push your changes to Dolt remote

Best for teams on protected branches and review-before-merge policies. See Multi-Repo Migration for multi-repo patterns.

Duplicate Detection

After merging branches:

bd duplicates --auto-merge

Branchless Workflows (Jujutsu / jj)

Beads works with branchless VCS tools like Jujutsu (jj). Since beads data is stored in Dolt (not git branches), there is no dependency on the "current branch" concept.

What Works Without Hooks

All core beads functionality works without git hooks:

Feature Hooks Required? Notes
bd create, bd update, bd close No Core CRUD uses Dolt directly
bd ready, bd list, bd show No Read-only queries
bd dolt push / bd dolt pull No Dolt-native sync, independent of git
bd onboard, bd doctor No Diagnostics and onboarding
Agent identity trailers Yes prepare-commit-msg hook adds Executed-By: to commits
Hook chaining Yes Preserves existing pre-commit, post-merge hooks

To skip hooks entirely during init:

bd init --skip-hooks

What Works Without AGENTS.md

The AGENTS.md file generated by bd init provides AI agent instructions. If you manage your own agent instructions or don't want beads to modify tracked files:

bd init --skip-agents    # Skip AGENTS.md and Claude/Codex setup generation
bd init --stealth        # Full invisible mode (also skips hooks + agents)

Jujutsu Setup

Colocated repos (jj git init --colocate): Git hooks work normally. Beads installs simplified hooks (pre-commit and post-merge only, no staging logic).

Pure jj repos (no git): Since jj doesn't have native hooks yet, set up push aliases:

# ~/.config/jj/config.toml
[aliases]
push = ["util", "exec", "--", "sh", "-c", "bd dolt commit && bd dolt push && jj git push \"$@\"", ""]

Then use jj push instead of jj git push.

Best Practices

  1. Install hooks - bd hooks install
  2. Push regularly - bd dolt push at session end
  3. Pull before work - bd dolt pull to get latest issues
  4. Use normal Git worktrees - no sync branch is required