a69e94a958
* feat: auto-disable daemon in git worktrees for safety Implement worktree daemon compatibility as proposed in the analysis. The daemon is now automatically disabled when running in a git worktree unless sync-branch is configured. Git worktrees share the same .beads directory, and the daemon commits to whatever branch its working directory has checked out. This causes commits to go to the wrong branch when using daemon in worktrees. - Add shouldDisableDaemonForWorktree() helper that checks: 1. If current directory is a git worktree (via git rev-parse) 2. If sync-branch is configured (env var or config.yaml) - Modify shouldAutoStartDaemon() to call the helper - Modify daemon connection logic in main.go to skip connection - Add FallbackWorktreeSafety constant for daemon status reporting - Update warnWorktreeDaemon() to skip warning when sync-branch configured - In worktree WITHOUT sync-branch: daemon auto-disabled, direct mode used - In worktree WITH sync-branch: daemon enabled (commits go to dedicated branch) - In regular repo: no change (daemon works as before) - Added comprehensive unit tests for shouldDisableDaemonForWorktree() - Added integration tests for shouldAutoStartDaemon() in worktree contexts - Manual E2E testing verified correct behavior - Updated WORKTREES.md with new automatic safety behavior - Updated DAEMON.md with Git Worktrees section * feat: check database config for sync-branch in worktree safety logic Previously, the worktree daemon safety check only looked at: - BEADS_SYNC_BRANCH environment variable - sync-branch in config.yaml This meant users who configured sync-branch via `bd config set sync-branch` (which stores in the database) would still have daemon disabled in worktrees. Now the check also reads sync.branch from the database config table, making daemon work in worktrees when sync-branch is configured via any method. Changes: - Add IsConfiguredWithDB() function that checks env, config.yaml, AND database - Add findBeadsDB() to locate database (worktree-aware via git-common-dir) - Add getMainRepoRoot() helper using git rev-parse - Add getConfigFromDB() for lightweight database reads - Update shouldDisableDaemonForWorktree() to use IsConfiguredWithDB() - Update warnWorktreeDaemon() to use IsConfiguredWithDB() - Add test case for database config path * refactor: use existing beads.FindDatabasePath() instead of duplicating code Remove duplicate getMainRepoRoot() and findBeadsDB() functions from syncbranch.go and use the existing beads.FindDatabasePath() which is already worktree-aware. Changes: - Replace custom findBeadsDB() with beads.FindDatabasePath() - Remove duplicate getMainRepoRoot() (git.GetMainRepoRoot() exists) - Remove unused imports (exec, strings, filepath) - Clean up debug logging in tests --------- Co-authored-by: Charles P. Cross <cpdata@users.noreply.github.com>
310 lines
8.6 KiB
Markdown
310 lines
8.6 KiB
Markdown
# Git Worktrees Guide
|
|
|
|
**Enhanced Git worktree compatibility for Beads issue tracking**
|
|
|
|
## Overview
|
|
|
|
Beads now provides **enhanced Git worktree support** with a shared database architecture. All worktrees in a repository share the same `.beads` database located in the main repository, enabling seamless issue tracking across multiple working directories.
|
|
|
|
**Note:** While comprehensively implemented and tested internally, this feature may benefit from real-world usage feedback to identify any remaining edge cases.
|
|
|
|
## How It Works
|
|
|
|
### Shared Database Architecture
|
|
|
|
```
|
|
Main Repository
|
|
├── .git/ # Shared git directory
|
|
├── .beads/ # Shared database (main repo)
|
|
│ ├── beads.db # SQLite database
|
|
│ ├── issues.jsonl # Issue data (git-tracked)
|
|
│ └── config.yaml # Configuration
|
|
├── feature-branch/ # Worktree 1
|
|
│ └── (code files only)
|
|
└── bugfix-branch/ # Worktree 2
|
|
└── (code files only)
|
|
```
|
|
|
|
**Key points:**
|
|
- ✅ **One database** - All worktrees share the same `.beads` directory in main repo
|
|
- ✅ **Automatic discovery** - Database found regardless of which worktree you're in
|
|
- ✅ **Concurrent access** - SQLite locking prevents corruption
|
|
- ✅ **Git integration** - Issues sync via JSONL in main repo
|
|
|
|
### Worktree Detection & Daemon Safety
|
|
|
|
bd automatically detects when you're in a git worktree and handles daemon mode safely:
|
|
|
|
**Default behavior (no sync-branch configured):**
|
|
- Daemon is **automatically disabled** in worktrees
|
|
- Uses direct mode for safety (no warning needed)
|
|
- All commands work correctly without configuration
|
|
|
|
**With sync-branch configured:**
|
|
- Daemon is **enabled** in worktrees
|
|
- Commits go to dedicated sync branch (e.g., `beads-metadata`)
|
|
- Full daemon functionality available across all worktrees
|
|
|
|
## Usage Patterns
|
|
|
|
### Recommended: Configure Sync-Branch for Full Daemon Support
|
|
|
|
```bash
|
|
# Configure sync-branch once (in main repo or any worktree)
|
|
bd config set sync-branch beads-metadata
|
|
|
|
# Now daemon works safely in all worktrees
|
|
cd feature-worktree
|
|
bd create "Implement feature X" -t feature -p 1
|
|
bd update bd-a1b2 --status in_progress
|
|
bd ready # Daemon auto-syncs to beads-metadata branch
|
|
```
|
|
|
|
### Alternative: Direct Mode (No Configuration Needed)
|
|
|
|
```bash
|
|
# Without sync-branch, daemon is auto-disabled in worktrees
|
|
cd feature-worktree
|
|
bd create "Implement feature X" -t feature -p 1
|
|
bd ready # Uses direct mode automatically
|
|
bd sync # Manual sync when needed
|
|
```
|
|
|
|
### Legacy: Explicit Daemon Disable
|
|
|
|
```bash
|
|
# Still works if you prefer explicit control
|
|
export BEADS_NO_DAEMON=1
|
|
# or
|
|
bd --no-daemon ready
|
|
```
|
|
|
|
## Worktree-Aware Features
|
|
|
|
### Database Discovery
|
|
|
|
bd intelligently finds the correct database:
|
|
|
|
1. **Priority search**: Main repository `.beads` directory first
|
|
2. **Fallback logic**: Searches worktree if main repo doesn't have database
|
|
3. **Path resolution**: Handles symlinks and relative paths correctly
|
|
4. **Validation**: Ensures `.beads` contains actual project files
|
|
|
|
### Git Hooks Integration
|
|
|
|
Pre-commit hooks adapt to worktree context:
|
|
|
|
```bash
|
|
# In main repo: Stages JSONL normally
|
|
git add .beads/issues.jsonl
|
|
|
|
# In worktree: Safely skips staging (files outside working tree)
|
|
# Hook detects context and handles appropriately
|
|
```
|
|
|
|
### Sync Operations
|
|
|
|
Worktree-aware sync operations:
|
|
|
|
- **Repository root detection**: Uses `git rev-parse --show-toplevel` for main repo
|
|
- **Git directory handling**: Distinguishes between `.git` (file) and `.git/` (directory)
|
|
- **Path resolution**: Converts between worktree and main repo paths
|
|
- **Concurrent safety**: SQLite locking prevents corruption
|
|
|
|
## Setup Examples
|
|
|
|
### Basic Worktree Setup
|
|
|
|
```bash
|
|
# Create main worktree
|
|
git worktree add main-repo
|
|
|
|
# Create feature worktree
|
|
git worktree add feature-worktree
|
|
|
|
# Initialize beads in main repo
|
|
cd main-repo
|
|
bd init
|
|
|
|
# Worktrees automatically share the database
|
|
cd ../feature-worktree
|
|
bd ready # Works immediately - sees same issues
|
|
```
|
|
|
|
### Multi-Feature Development
|
|
|
|
```bash
|
|
# Main development
|
|
cd main-repo
|
|
bd create "Epic: User authentication" -t epic -p 1
|
|
# Returns: bd-a3f8e9
|
|
|
|
# Feature branch worktree
|
|
git worktree add auth-feature
|
|
cd auth-feature
|
|
bd create "Design login UI" -p 1
|
|
# Auto-assigned: bd-a3f8e9.1 (child of epic)
|
|
|
|
# Bugfix worktree
|
|
git worktree add auth-bugfix
|
|
cd auth-bugfix
|
|
bd create "Fix password validation" -t bug -p 0
|
|
# Auto-assigned: bd-f14c3
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Issue: Daemon commits to wrong branch
|
|
|
|
**Symptoms:** Changes appear on unexpected branch in git history
|
|
|
|
**Note:** This issue should no longer occur with the new worktree safety feature. Daemon is automatically disabled in worktrees unless sync-branch is configured.
|
|
|
|
**Solution (if still occurring):**
|
|
```bash
|
|
# Option 1: Configure sync-branch (recommended)
|
|
bd config set sync-branch beads-metadata
|
|
|
|
# Option 2: Explicitly disable daemon
|
|
export BEADS_NO_DAEMON=1
|
|
# Or use --no-daemon flag for individual commands
|
|
bd --no-daemon sync
|
|
```
|
|
|
|
### Issue: Database not found in worktree
|
|
|
|
**Symptoms:** `bd: database not found` error
|
|
|
|
**Solutions:**
|
|
```bash
|
|
# Ensure main repo has .beads directory
|
|
cd main-repo
|
|
ls -la .beads/
|
|
|
|
# Re-run bd init if needed
|
|
bd init
|
|
|
|
# Check worktree can access main repo
|
|
cd ../worktree-name
|
|
bd info # Should show database path in main repo
|
|
```
|
|
|
|
### Issue: Multiple databases detected
|
|
|
|
**Symptoms:** Warning about multiple `.beads` directories
|
|
|
|
**Solution:**
|
|
```bash
|
|
# bd shows warning with database locations
|
|
# Typically, the closest database (in main repo) is correct
|
|
# Remove extra .beads directories if they're not needed
|
|
```
|
|
|
|
### Issue: Git hooks fail in worktrees
|
|
|
|
**Symptoms:** Pre-commit hook errors about staging files outside working tree
|
|
|
|
**Solution:** This is now automatically handled. The hook detects worktree context and adapts its behavior. No manual intervention needed.
|
|
|
|
## Advanced Configuration
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
# Disable daemon globally for worktree usage
|
|
export BEADS_NO_DAEMON=1
|
|
|
|
# Disable auto-start (still warns if manually started)
|
|
export BEADS_AUTO_START_DAEMON=false
|
|
|
|
# Force specific database location
|
|
export BEADS_DB=/path/to/specific/.beads/beads.db
|
|
```
|
|
|
|
### Configuration Options
|
|
|
|
```bash
|
|
# Configure sync behavior
|
|
bd config set sync.branch beads-metadata # Use separate sync branch
|
|
bd config set sync.auto_commit true # Auto-commit changes
|
|
bd config set sync.auto_push true # Auto-push changes
|
|
```
|
|
|
|
## Performance Considerations
|
|
|
|
### Database Sharing Benefits
|
|
|
|
- **Reduced overhead**: One database instead of per-worktree copies
|
|
- **Instant sync**: Changes visible across all worktrees immediately
|
|
- **Memory efficient**: Single SQLite instance vs multiple
|
|
- **Git efficient**: One JSONL file to track vs multiple
|
|
|
|
### Concurrent Access
|
|
|
|
- **SQLite locking**: Prevents corruption during simultaneous access
|
|
- **Git operations**: Safe concurrent commits from different worktrees
|
|
- **Sync coordination**: JSONL-based sync prevents conflicts
|
|
|
|
## Migration from Limited Support
|
|
|
|
### Before (Limited Worktree Support)
|
|
|
|
- ❌ Daemon mode broken in worktrees
|
|
- ❌ Manual workarounds required
|
|
- ❌ Complex setup procedures
|
|
- ❌ Limited documentation
|
|
|
|
### After (Enhanced Worktree Support)
|
|
|
|
- ✅ Shared database architecture
|
|
- ✅ Automatic worktree detection
|
|
- ✅ Clear user guidance and warnings
|
|
- ✅ Comprehensive documentation
|
|
- ✅ Git hooks work correctly
|
|
- ✅ All bd commands function properly
|
|
|
|
**Note:** Based on comprehensive internal testing. Real-world usage may reveal additional refinements needed.
|
|
|
|
## Examples in the Wild
|
|
|
|
### Monorepo Development
|
|
|
|
```bash
|
|
# Monorepo with multiple service worktrees
|
|
git worktree add services/auth
|
|
git worktree add services/api
|
|
git worktree add services/web
|
|
|
|
# Each service team works in their worktree
|
|
cd services/auth
|
|
export BEADS_NO_DAEMON=1
|
|
bd create "Add OAuth support" -t feature -p 1
|
|
|
|
cd ../api
|
|
bd create "Implement auth endpoints" -p 1
|
|
# Issues automatically linked and visible across worktrees
|
|
```
|
|
|
|
### Feature Branch Workflow
|
|
|
|
```bash
|
|
# Create feature worktree
|
|
git worktree add feature/user-profiles
|
|
cd feature/user-profiles
|
|
|
|
# Work on feature with full issue tracking
|
|
bd create "Design user profile schema" -t task -p 1
|
|
bd create "Implement profile API" -t task -p 1
|
|
bd create "Add profile UI components" -t task -p 2
|
|
|
|
# Issues tracked in shared database
|
|
# Code changes isolated to worktree
|
|
# Clean merge back to main when ready
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - General git integration guide
|
|
- [AGENTS.md](../AGENTS.md) - Agent usage instructions
|
|
- [README.md](../README.md) - Main project documentation
|
|
- [MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md) - Multi-workspace patterns |