beads/examples/git-hooks
Steve Yegge 19cd7d1887 Prepare for public launch: comprehensive examples, docs, and tooling
This commit adds everything needed for a successful public launch:

**New Documentation**
- SECURITY.md: Security policy and best practices
- CLAUDE.md: Complete agent instructions for contributing to beads
- Enhanced README with pain points, FAQ, troubleshooting sections
- Added Taskwarrior to comparison table with detailed explanation

**Installation**
- install.sh: One-liner installation script with platform detection
- Auto-detects OS/arch, tries go install, falls back to building from source
- Updated README with prominent installation instructions

**Examples** (2,268+ lines of working code)
- examples/python-agent/: Full Python implementation of agent workflow
- examples/bash-agent/: Shell script agent with colorized output
- examples/git-hooks/: Pre-commit, post-merge, post-checkout hooks with installer
- examples/claude-desktop-mcp/: Documentation for future MCP server integration
- examples/README.md: Overview of all examples

**Dogfooding**
- Initialized bd in beads project itself (.beads/beads.db)
- Created issues for roadmap (MCP server, migrations, demos, 1.0 milestone)
- Exported to .beads/issues.jsonl for git versioning

**Visual Assets**
- Added screenshot showing agent using beads to README intro
- Placed in .github/images/ following GitHub conventions

This addresses all launch readiness items:
✅ Security policy
✅ Working agent examples (Python, Bash)
✅ Git hooks for automation
✅ FAQ addressing skeptics
✅ Troubleshooting common issues
✅ Easy installation
✅ Dogfooding our own tool
✅ Pain points that create urgency

Ready to ship! 🚀

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-12 11:25:29 -07:00
..
install.sh Prepare for public launch: comprehensive examples, docs, and tooling 2025-10-12 11:25:29 -07:00
post-checkout Prepare for public launch: comprehensive examples, docs, and tooling 2025-10-12 11:25:29 -07:00
post-merge Prepare for public launch: comprehensive examples, docs, and tooling 2025-10-12 11:25:29 -07:00
pre-commit Prepare for public launch: comprehensive examples, docs, and tooling 2025-10-12 11:25:29 -07:00
README.md Prepare for public launch: comprehensive examples, docs, and tooling 2025-10-12 11:25:29 -07:00

Git Hooks for Beads

Automatic export/import of beads issues during git operations.

What These Hooks Do

  • pre-commit: Exports SQLite → JSONL before every commit
  • post-merge: Imports JSONL → SQLite after git pull/merge
  • post-checkout: Imports JSONL → SQLite after branch switching

This keeps your .beads/issues.jsonl (committed to git) in sync with your local SQLite database (gitignored).

Installation

Quick Install

cd /path/to/your/project
./examples/git-hooks/install.sh

The installer will prompt before overwriting existing hooks.

Manual Install

# Copy hooks to .git/hooks/
cp examples/git-hooks/pre-commit .git/hooks/
cp examples/git-hooks/post-merge .git/hooks/
cp examples/git-hooks/post-checkout .git/hooks/

# Make them executable
chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/post-merge
chmod +x .git/hooks/post-checkout

Usage

Once installed, the hooks run automatically:

# Creating/updating issues
bd create "New feature" -p 1
bd update bd-1 --status in_progress

# Committing changes - hook exports automatically
git add .
git commit -m "Update feature"
# 🔗 Exporting beads issues to JSONL...
# ✓ Beads issues exported and staged

# Pulling changes - hook imports automatically
git pull
# 🔗 Importing beads issues from JSONL...
# ✓ Beads issues imported successfully

# Switching branches - hook imports automatically
git checkout feature-branch
# 🔗 Importing beads issues from JSONL...
# ✓ Beads issues imported successfully

How It Works

The Workflow

  1. You work with bd commands (create, update, close)
  2. Changes are stored in SQLite (.beads/*.db) - fast local queries
  3. Before commit, hook exports to JSONL (.beads/issues.jsonl) - git-friendly
  4. JSONL is committed to git (source of truth)
  5. After pull/merge/checkout, hook imports JSONL back to SQLite
  6. Your local SQLite cache is now in sync with git

Why This Design?

SQLite for speed:

  • Fast queries (dependency trees, ready work)
  • Rich SQL capabilities
  • Sub-100ms response times

JSONL for git:

  • Clean diffs (one issue per line)
  • Mergeable (independent lines)
  • Human-readable
  • AI-resolvable conflicts

Best of both worlds!

Troubleshooting

Hook not running

# Check if hook is executable
ls -l .git/hooks/pre-commit
# Should show -rwxr-xr-x

# Make it executable if needed
chmod +x .git/hooks/pre-commit

Export/import fails

# Check if bd is in PATH
which bd

# Check if you're in a beads-initialized directory
bd list

Merge conflicts in issues.jsonl

If you get merge conflicts in .beads/issues.jsonl:

  1. Most conflicts are safe to resolve by keeping both sides
  2. Each line is an independent issue
  3. Look for <<<<<<< HEAD markers
  4. Keep all lines that don't conflict
  5. For actual conflicts on the same issue, choose the newest

Example conflict:

<<<<<<< HEAD
{"id":"bd-3","title":"Updated title","status":"closed","updated_at":"2025-10-12T10:00:00Z"}
=======
{"id":"bd-3","title":"Updated title","status":"in_progress","updated_at":"2025-10-12T09:00:00Z"}
>>>>>>> feature-branch

Resolution: Keep the HEAD version (newer timestamp).

After resolving:

git add .beads/issues.jsonl
git commit
bd import -i .beads/issues.jsonl  # Sync to SQLite

Uninstalling

rm .git/hooks/pre-commit
rm .git/hooks/post-merge
rm .git/hooks/post-checkout

Customization

Skip hook for one commit

git commit --no-verify -m "Skip hooks"

Add to existing hooks

If you already have git hooks, you can append to them:

# Append to existing pre-commit
cat examples/git-hooks/pre-commit >> .git/hooks/pre-commit

Filter exports

Export only specific issues:

# Edit pre-commit hook, change:
bd export --format=jsonl -o .beads/issues.jsonl

# To:
bd export --format=jsonl --status=open -o .beads/issues.jsonl

See Also