584608a14e
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml from joyshmitz's PR. Fixed workflow to trigger on main branch instead of docs/docusaurus-site. Features: - Docusaurus documentation site with llms.txt support - Environment-variable driven config (defaults to steveyegge org) - Automated llms-full.txt generation from docs - GitHub Pages deployment workflow Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Executed-By: beads/crew/dave Rig: beads Role: crew
171 lines
2.8 KiB
Markdown
171 lines
2.8 KiB
Markdown
---
|
|
id: git-integration
|
|
title: Git Integration
|
|
sidebar_position: 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)
|
|
└── bd.sock # Daemon socket (gitignored)
|
|
```
|
|
|
|
## Git Hooks
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
bd hooks install
|
|
```
|
|
|
|
Installs:
|
|
- **pre-commit** - Exports database to JSONL
|
|
- **post-merge** - Imports from JSONL after pull
|
|
- **pre-push** - Ensures sync before push
|
|
|
|
### Status
|
|
|
|
```bash
|
|
bd hooks status
|
|
```
|
|
|
|
### Uninstall
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
bd init # Prompts for merge driver setup
|
|
```
|
|
|
|
Or manually add to `.gitattributes`:
|
|
|
|
```gitattributes
|
|
.beads/issues.jsonl merge=beads
|
|
.beads/deletions.jsonl merge=beads
|
|
```
|
|
|
|
And `.git/config`:
|
|
|
|
```ini
|
|
[merge "beads"]
|
|
name = Beads JSONL merge driver
|
|
driver = bd merge-driver %O %A %B
|
|
```
|
|
|
|
## Protected Branches
|
|
|
|
For protected main branches:
|
|
|
|
```bash
|
|
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 requires `--no-daemon` in git worktrees:
|
|
|
|
```bash
|
|
# In worktree
|
|
bd --no-daemon create "Task"
|
|
bd --no-daemon list
|
|
```
|
|
|
|
Why: Daemon uses `.beads/bd.sock` which conflicts across worktrees.
|
|
|
|
## Branch Workflows
|
|
|
|
### Feature Branch
|
|
|
|
```bash
|
|
git checkout -b feature-x
|
|
bd create "Feature X" -t feature
|
|
# Work...
|
|
bd sync
|
|
git push
|
|
```
|
|
|
|
### Fork Workflow
|
|
|
|
```bash
|
|
# In fork
|
|
bd init --contributor
|
|
# Work in separate planning repo...
|
|
bd sync
|
|
```
|
|
|
|
### Team Workflow
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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. **Use `--no-daemon` in worktrees**
|