beads/website/docs/reference/git-integration.md
topaz 062aedbed7 docs: remove stale daemon references from all documentation (GH#1982)
Sweep 65 markdown files across docs/, website/, claude-plugin/, examples/,
integrations/, and root to replace removed `bd daemon` references with
current Dolt server mode equivalents. CHANGELOG.md preserved per policy.

Key replacements:
- `bd daemon start/stop/status` → `bd dolt start/stop` / `bd doctor`
- `bd daemons killall/health/logs` → `bd dolt stop` / `bd doctor`
- `--no-daemon` flag → removed (embedded mode is default)
- `BEADS_NO_DAEMON` / `BEADS_DAEMON_MODE` env vars → removed
- `.beads/bd.sock` → removed
- "daemon mode" / "direct mode" → "server mode" / "embedded mode"
- daemon.pid/daemon.log → .beads/dolt/sql-server.pid/.log

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Executed-By: beads/polecats/topaz
Rig: beads
Role: polecats
2026-02-22 17:57:53 -08:00

2.8 KiB

id title sidebar_position
git-integration Git Integration 2

Git Integration

How beads integrates with git.

Overview

Beads uses git for:

  • JSONL sync - Issues stored in .beads/issues.jsonl
  • Deletion tracking - .beads/deletions.jsonl
  • Conflict resolution - Custom merge driver
  • Hooks - Auto-sync on git operations

File Structure

.beads/
├── beads.db           # SQLite database (gitignored)
├── issues.jsonl       # Issue data (git-tracked)
├── deletions.jsonl    # Deletion manifest (git-tracked)
├── config.toml        # Project config (git-tracked)
└── dolt/              # Dolt server data (gitignored)

Git Hooks

Installation

bd hooks install

Installs:

  • pre-commit - Exports database to JSONL
  • post-merge - Imports from JSONL after pull
  • pre-push - Ensures sync before push

Status

bd hooks status

Uninstall

bd hooks uninstall

Merge Driver

Purpose

The beads merge driver handles JSONL conflicts automatically:

  • Merges non-conflicting changes
  • Uses latest timestamp for same-issue edits
  • Preserves both sides for real conflicts

Installation

bd init  # Prompts for merge driver setup

Or manually add to .gitattributes:

.beads/issues.jsonl merge=beads
.beads/deletions.jsonl merge=beads

And .git/config:

[merge "beads"]
    name = Beads JSONL merge driver
    driver = bd merge-driver %O %A %B

Protected Branches

For protected main branches:

bd init --branch beads-sync

This:

  • Creates a separate beads-sync branch
  • Syncs issues to that branch
  • Avoids direct commits to main

Git Worktrees

Beads works in git worktrees using embedded mode:

# In worktree — just run commands directly
bd create "Task"
bd list

Branch Workflows

Feature Branch

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

Fork Workflow

# In fork
bd init --contributor
# Work in separate planning repo...
bd sync

Team Workflow

bd init --team
# All team members share issues.jsonl
git pull  # Auto-imports via hook

Conflict Resolution

With Merge Driver

Automatic - driver handles most conflicts.

Manual Resolution

# After conflict
git checkout --ours .beads/issues.jsonl
bd import -i .beads/issues.jsonl
bd sync
git add .beads/
git commit

Duplicate Detection

After merge:

bd duplicates --auto-merge

Best Practices

  1. Install hooks - bd hooks install
  2. Use merge driver - Avoid manual conflict resolution
  3. Sync regularly - bd sync at session end
  4. Pull before work - Get latest issues
  5. Worktrees use embedded mode automatically