From e7fd1dd3b6609345cb4e717b92f9dee71cf3ff5c Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Thu, 20 Nov 2025 21:28:59 -0500 Subject: [PATCH] Document files created by bd init and clarify .gitattributes should be committed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 20 ++++++++++++++++++++ docs/GIT_INTEGRATION.md | 7 +++++++ 2 files changed, 27 insertions(+) diff --git a/README.md b/README.md index 9a33c3b6..309f59e3 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/docs/GIT_INTEGRATION.md b/docs/GIT_INTEGRATION.md index 508106b8..3720644a 100644 --- a/docs/GIT_INTEGRATION.md +++ b/docs/GIT_INTEGRATION.md @@ -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`:**