johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document files created by bd init and clarify .gitattributes should be committed

Browse Source 
Fixes #299

Added comprehensive documentation to help new users understand what files
should be committed vs ignored after running bd init:

1. README.md:
   - New "Files Created by bd init" section
   - Clear lists of files to commit vs ignore
   - Explains purpose of .gitattributes for team collaboration

2. docs/GIT_INTEGRATION.md:
   - Enhanced .gitattributes section with IMPORTANT notice
   - Explains why it must be committed (merge driver config)
   - Lists benefits of intelligent JSONL merging

Key clarification: .gitattributes should be COMMITTED (not ignored) as it
configures git merge behavior for the entire team.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-11-20 21:28:59 -05:00
parent a42e84ca9c
commit e7fd1dd3b6
2 changed files with 27 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

@@ -161,6 +161,26 @@ git config merge.beads.name "bd JSONL merge driver"
echo ".beads/beads.jsonl merge=beads" >> .gitattributes
```
### Files Created by `bd init`
**`bd init` creates these files in your repository:**
**Should be committed to git:**
- `.gitattributes` - Configures git merge driver for intelligent JSONL merging (critical for team collaboration)
- `.beads/beads.jsonl` - Issue data in JSONL format (source of truth, synced via git)
- `.beads/config.yaml` - Repository configuration template
- `.beads/README.md` - Documentation about beads for repository visitors
- `.beads/metadata.json` - Database metadata
**Should be in `.gitignore` (local-only):**
- `.beads/beads.db` - SQLite cache (auto-synced with JSONL)
- `.beads/beads.db-*` - SQLite journal files
- `.beads/bd.sock` / `.beads/bd.pipe` - Daemon communication socket
- `.beads/.exclusive-lock` - Daemon lock file
- `.git/beads-worktrees/` - Git worktrees (only created when using protected branch workflows)
The `.gitignore` entries are automatically created inside `.beads/.gitignore` by `bd init`, but your project's root `.gitignore` should also exclude the database and daemon files if you want to keep your git status clean.
**Using devcontainers?** Open the repository in a devcontainer (GitHub Codespaces or VS Code Remote Containers) and bd will be automatically installed with git hooks configured. See [.devcontainer/README.md](.devcontainer/README.md) for details.
Most tasks will be created and managed by agents during conversations. You can check on things with:

7
docs/GIT_INTEGRATION.md
View File

@@ -434,6 +434,8 @@ export BEADS_NO_DAEMON=1 # Direct mode
### Recommended .gitattributes
**IMPORTANT:** The `.gitattributes` file should be **committed to git**, not ignored. It configures merge behavior for the entire team.
```
# Intelligent merge driver for JSONL (auto-configured by bd init)
.beads/beads.jsonl merge=beads
@@ -442,6 +444,11 @@ export BEADS_NO_DAEMON=1 # Direct mode
.beads/*.jsonl text diff
```
This file is automatically created by `bd init` and is essential for:
- Preventing spurious merge conflicts in `.beads/beads.jsonl`
- Enabling field-level 3-way merging instead of line-by-line
- Ensuring all team members get intelligent JSONL merging
### Git LFS Considerations
**Do NOT use Git LFS for `.beads/beads.jsonl`:**