The .beads/.gitignore now ignores everything by default and explicitly
whitelists tracked files. This fixes confusion about which files to
commit when using protected branches workflow.
Changes:
- Use `*` to ignore all by default, then `!file` to whitelist
- Fix config.json -> config.yaml (wrong filename in negation)
- Update doctor check to validate new patterns
- Update PROTECTED_BRANCHES.md documentation
- Simplify git add instructions to just `git add .beads/`
Fixes#473🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes#312
Users were confused about which files should be committed after running
'bd init --branch beads-metadata'. The PROTECTED_BRANCHES.md doc now
clearly explains:
1. Files to commit to protected branch (main):
- .beads/.gitignore - Tells git what to ignore
- .gitattributes - Merge driver configuration
2. Files automatically gitignored (do NOT commit):
- .beads/beads.db - SQLite database (local only)
- .beads/daemon.* - Runtime files
- .beads/*.left/right.jsonl - Temporary merge artifacts
3. Files in sync branch (beads-metadata):
- .beads/beads.jsonl - Issue data (committed by daemon)
- .beads/metadata.json - Repository metadata
- .beads/config.yaml - Configuration template
Added step-by-step instructions in Quick Start section and a "What lives
in each branch" section to How It Works.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Created complete documentation suite for using beads with protected branches:
1. **docs/PROTECTED_BRANCHES.md** - Comprehensive 600+ line guide covering:
- Quick start and setup
- How git worktrees work
- Daily workflow for agents and humans
- Merging strategies (PR and direct)
- Troubleshooting common issues
- Platform-specific notes (GitHub, GitLab, Bitbucket)
- Advanced topics (CI/CD, multi-clone sync, etc.)
2. **AGENTS.md** - Added "Protected Branch Workflow" section:
- Quick reference for agents
- No changes needed to agent workflows
- Commands for setup and merging
- Link to detailed docs
3. **README.md** - Updated with:
- Protected branch support feature flag
- Quick start instructions with --branch flag
- Link to comprehensive guide
4. **examples/protected-branch/** - Working example with:
- Step-by-step demo
- Multi-clone sync workflow
- GitHub Actions integration example
- Directory structure explanation
- Troubleshooting tips
All commands verified:
- bd init --branch <name>
- bd config get/set sync.branch
- bd sync --status
- bd sync --merge
Documentation is platform-agnostic and works with GitHub, GitLab,
Bitbucket, or any git platform with branch protection.
Closes bd-5ce8
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
