beads/docs/GIT_INTEGRATION.md
darcy f9b306f152 docs(claim): standardize start-work semantics to --claim (#2070)
Standardize start-work semantics to `bd update <id> --claim` across docs,
examples, templates, and website static LLM artifacts. Replaces
`--status in_progress` with `--claim` where the meaning is start-work.

Also fixes stale comment in llms.txt ("Update status" → "Start work").

Co-Authored-By: Valeriy Pavlovich <iqdoctor@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-24 22:11:39 -08:00

5.8 KiB

Git Integration Guide

For: AI agents and developers managing bd git workflows

Overview

bd integrates with git for worktree support and protected branch workflows. The Dolt backend handles all data storage and versioning natively.

Git Worktrees

Beads has comprehensive Git worktree compatibility with shared database architecture.

How It Works

Git worktrees share the same .git directory and .beads database:

  • All worktrees use the same .beads/dolt/ database in the main repository
  • Database discovery prioritizes main repository location
  • Worktree-aware git operations prevent conflicts

Worktree-Aware Features

Database Discovery:

  • Searches main repository first for .beads directory
  • Falls back to worktree-local search if needed
  • Prevents database duplication across worktrees

Git Operations:

  • Worktree-aware repository root detection
  • Proper handling of git directory vs git common directory
  • Safe concurrent access to shared database (use server mode for multi-writer)

Protected Branch Workflows

If your repository uses protected branches (GitHub, GitLab, etc.), bd can commit to a separate branch instead of main:

Configuration

# Initialize with separate sync branch
bd init --branch beads-sync

# Or configure existing setup
bd config set sync.branch beads-sync

How It Works

  • Beads commits issue updates to beads-sync instead of main
  • Uses git worktrees (lightweight checkouts) in .git/beads-worktrees/
  • Your main working directory is never affected
  • Periodically merge beads-sync back to main via pull request

Daily Workflow (Unchanged for Agents)

# Agents work normally - no changes needed!
bd create "Fix authentication" -t bug -p 1
bd update bd-a1b2 --claim
bd close bd-a1b2 "Fixed"

Merging to Main (Humans)

# Check what's changed
bd sync --status

# Option 1: Create pull request
git push origin beads-sync
# Then create PR on GitHub/GitLab

# Option 2: Direct merge (if allowed)
bd sync --merge

Benefits

  • Works with protected main branches
  • No disruption to agent workflows
  • Platform-agnostic (works on any git platform)
  • Backward compatible (opt-in via config)

See PROTECTED_BRANCHES.md for complete setup guide, troubleshooting, and examples.

Git Hooks

Installation

# Install hooks
bd hooks install --beads

What Gets Installed

pre-commit hook:

  • Runs pre-commit checks for beads data consistency

post-merge hook:

  • Ensures Dolt database is current after pull/merge operations

Hook Implementation Details

Hook Installation (cmd/bd/hooks.go)

The installHooks() function:

  • Writes embedded hook scripts to the .git/hooks/ directory
  • Creates the hooks directory with os.MkdirAll() if needed
  • Backs up existing hooks with .backup extension (unless --force flag used)
  • Sets execute permissions (0755) on installed hooks
  • Supports shared mode via --shared flag (installs to .beads-hooks/ instead)

Git Directory Resolution

Critical for worktree support: The getGitDir() helper uses git rev-parse --git-dir to resolve the actual git directory:

// Returns ".git" in normal repos
// Returns "/path/to/shared/.git" in git worktrees
gitDir, err := getGitDir()

In normal repositories, .git is a directory containing the git internals. In git worktrees, .git is a file containing gitdir: /path/to/actual/git/dir.

Hook Detection (cmd/bd/init.go)

The detectExistingHooks() function scans for existing hooks and classifies them:

  • bd hooks: Identified by "bd (beads) pre-commit hook" comment in content
  • pre-commit framework hooks: Detected by "pre-commit framework" or "pre-commit.com" in content
  • Custom hooks: Any other existing hook

Multi-Workspace Sync

Fork-Based Pattern

┌──────────────┐      ┌─────────────────┐
│  OSS Contrib │─────▶│ Planning Repo   │
│  (Fork)      │      │ (.beads/dolt/)  │
└──────────────┘      └─────────────────┘
       │
       │ PR
       ▼
┌─────────────────┐
│ Upstream Repo   │
│ (no .beads/)    │
└─────────────────┘

Best for:

  • Open source contributors
  • Solo developers
  • Private task tracking on public repos

Setup:

bd init --contributor  # Interactive wizard

Team Branch Pattern

┌──────────────┐
│  Team Member │────┐
│  (main)      │    │
└──────────────┘    │
                    ▼
┌──────────────┐  ┌─────────────────┐
│  Team Member │─▶│ Shared Repo     │
│  (main)      │  │ (beads-sync)    │
└──────────────┘  └─────────────────┘

Best for:

  • Teams on protected branches
  • Managed git workflows
  • Review-before-merge policies

Setup:

bd init --team  # Interactive wizard

See MULTI_REPO_MIGRATION.md for complete guide.

Git Configuration Best Practices

# Dolt database (not tracked in git)
.beads/dolt/

# Lock files
.beads/dolt-access.lock

Git LFS Considerations

The Dolt database directory (.beads/dolt/) should be gitignored, not tracked via LFS or regular git.

See Also