0b0d9a43d1
Oracle identified a critical race condition in the initial fix: - Pre-push hook checked for changes but didn't flush first - Pending 5s-debounced flushes could land after the check - Result: stale JSONL could still be pushed Improvements: 1. Pre-push now flushes pending changes FIRST (bd sync --flush-only) 2. Uses git status --porcelain to catch ALL change types: - Staged, unstaged, untracked, deleted, renamed, conflicts 3. Handles both beads.jsonl and issues.jsonl (backward compat) 4. Works even without bd installed (git-only check) 5. Pre-commit stages both JSONL files (simpler loop) This completely eliminates the race condition.
bd Git Hooks
This directory contains git hooks that integrate bd (beads) with your git workflow, preventing stale JSONL from being pushed to remote.
The Problem
Two race conditions can occur:
-
Between operations and commits: Daemon auto-flush (5s debounce) may fire after commit
- User closes issue via MCP → daemon schedules flush (5 sec delay)
- User commits code changes → JSONL appears clean
- Daemon flush fires → JSONL modified after commit
- Result: dirty working tree showing JSONL changes
-
Between commits and pushes: Changes made after commit but before push (bd-my64)
- User commits → pre-commit hook flushes JSONL
- User adds comments or updates issues
- User pushes → outdated JSONL is pushed
- Result: remote has stale JSONL
The Solution
These git hooks ensure bd changes are always synchronized with your commits and pushes:
- pre-commit - Flushes pending bd changes to JSONL before commit and stages it
- pre-push - Blocks push if JSONL has uncommitted changes (bd-my64)
- post-merge - Imports updated JSONL after git pull/merge
Installation
Quick Install
From your repository root:
./examples/git-hooks/install.sh
This will:
- Copy hooks to
.git/hooks/ - Make them executable
- Back up any existing hooks
Manual Install
cp examples/git-hooks/pre-commit .git/hooks/pre-commit
cp examples/git-hooks/pre-push .git/hooks/pre-push
cp examples/git-hooks/post-merge .git/hooks/post-merge
chmod +x .git/hooks/pre-commit .git/hooks/pre-push .git/hooks/post-merge
How It Works
pre-commit
Before each commit, the hook runs:
bd sync --flush-only
This:
- Exports any pending database changes to
.beads/issues.jsonl - Stages the JSONL file if modified
- Allows the commit to proceed with clean state
The hook is silent on success, fast (no git operations), and safe (fails commit if flush fails).
pre-push
Before each push, the hook:
bd sync --flush-only # Flush pending changes (if bd available)
git status --porcelain .beads/*.jsonl # Check for uncommitted changes
This prevents pushing stale JSONL by:
- Flushing pending in-memory changes from daemon's 5s debounce
- Checking for uncommitted changes (staged, unstaged, untracked, deleted)
- Failing the push with clear error message if changes exist
- Instructing user to commit JSONL before pushing again
This solves bd-my64: changes made between commit and push (or pending debounced flushes) are caught before reaching remote.
post-merge
After a git pull or merge, the hook runs:
bd import -i .beads/beads.jsonl
This ensures your local database reflects the merged state. The hook:
- Only runs if
.beads/beads.jsonlexists (also checksissues.jsonlfor backward compat) - Imports any new issues or updates from the merge
- Warns on failure but doesn't block the merge
Note: With hash-based IDs (v0.20.1+), ID collisions don't occur - different issues get different hash IDs.
Compatibility
- Auto-sync: Works alongside bd's automatic 5-second debounce
- Direct mode: Hooks work in both daemon and
--no-daemonmode - Worktrees: Safe to use with git worktrees
Benefits
✅ No more dirty working tree after commits
✅ Database always in sync with git
✅ Automatic collision resolution on merge
✅ Fast and silent operation
✅ Optional - manual bd sync still works
Uninstall
Remove the hooks:
rm .git/hooks/pre-commit .git/hooks/pre-push .git/hooks/post-merge
Your backed-up hooks (if any) are in .git/hooks/*.backup-*.