beads/docs/reference/git-integration.md
Chris Sells a86a2c5dfc docs: port user docs into the Mintlify site tree under docs/
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.

git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).

Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.

Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
2026-07-12 10:37:07 -07:00

2.6 KiB

title
Git Integration

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).

File Structure

.beads/
├── config.yaml        # Project config (git-tracked)
├── metadata.json      # Backend metadata (git-tracked)
└── dolt/              # Dolt database and server data (gitignored)

Git Hooks

Installation

bd hooks install

Installs:

  • pre-commit - Triggers Dolt commit
  • post-merge - Triggers Dolt sync after pull
  • pre-push - Ensures Dolt sync before push

Status

bd hooks status

Uninstall

bd hooks uninstall

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.

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

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
# Work in separate planning repo...
bd dolt push

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

Duplicate Detection

After merging branches:

bd duplicates --auto-merge

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