* Add init remote bootstrap path (bd-cil) * fix(init): adopt source _project_id when bootstrapping from remote When `bd init --remote=<url>` cloned an existing Dolt remote, the ProjectID adoption gate at init.go:867 only fired for `--database` (GH#2922), so a fresh ProjectID was minted and then written back to the cloned database, overwriting the source rig's identity and breaking cross-project verification on subsequent pulls. Extend the gate to also adopt when `bootstrappedFromRemote` is true, matching the GH#2922 intent: if another rig already chose an identity, inherit it rather than overwrite. Fixes the failing TestEmbeddedInit/remote_bootstraps_existing_dolt_data subtest added in this PR. The other --remote subtests (empty source, plain git origin) and the GH#2922 --database path are unaffected. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
351 lines
11 KiB
Markdown
351 lines
11 KiB
Markdown
# Git Integration Guide
|
|
|
|
**For:** AI agents and developers managing bd git workflows
|
|
|
|
## Overview
|
|
|
|
bd integrates with git for worktree support and protected branch workflows. The Dolt backend handles all data storage and versioning natively.
|
|
|
|
## Git Worktrees
|
|
|
|
Beads has comprehensive Git worktree compatibility with shared database architecture.
|
|
|
|
### How It Works
|
|
|
|
Git worktrees share the same `.git` directory and `.beads` database:
|
|
- All worktrees use the same `.beads/dolt/` database in the main repository
|
|
- Database discovery prioritizes main repository location
|
|
- Worktree-aware git operations prevent conflicts
|
|
|
|
### Worktree-Aware Features
|
|
|
|
**Database Discovery:**
|
|
- Resolves the active workspace using `BEADS_DIR`, worktree fallback, and shared main-repo `.beads`
|
|
- Falls back to worktree-local search if needed
|
|
- Prevents database duplication across worktrees
|
|
- Use `bd where` as the authoritative check; local `./.beads` may be absent in pure worktree or redirected setups
|
|
|
|
**Git Operations:**
|
|
- Worktree-aware repository root detection
|
|
- Proper handling of git directory vs git common directory
|
|
- Safe concurrent access to shared database (use server mode for multi-writer)
|
|
|
|
## Protected Branch Workflows
|
|
|
|
**Note:** Beads data is stored in Dolt under `refs/dolt/data`, separate from standard Git refs. This means beads does not commit to any Git branch, so protected branch workflows are not affected.
|
|
|
|
Sync with remotes using Dolt's native push/pull:
|
|
|
|
```bash
|
|
bd init --remote http://myserver:7007/mydb # First setup or clone from a Dolt remote
|
|
bd dolt push # Push changes to Dolt remote
|
|
bd dolt pull # Pull changes from Dolt remote
|
|
```
|
|
|
|
### Daily Workflow (Unchanged for Agents)
|
|
|
|
```bash
|
|
# Agents work normally - no changes needed!
|
|
bd create "Fix authentication" -t bug -p 1
|
|
bd update bd-a1b2 --claim
|
|
bd close bd-a1b2 "Fixed"
|
|
```
|
|
|
|
### Merging to Main (Humans)
|
|
|
|
```bash
|
|
# Check what's changed
|
|
bd dolt show
|
|
|
|
# Option 1: Create pull request
|
|
git push origin beads-sync
|
|
# Then create PR on GitHub/GitLab
|
|
|
|
# Option 2: Direct merge (if allowed)
|
|
git merge beads-sync
|
|
```
|
|
|
|
### Benefits
|
|
|
|
- Works with protected `main` branches
|
|
- No disruption to agent workflows
|
|
- Platform-agnostic (works on any git platform)
|
|
- Backward compatible (opt-in via config)
|
|
|
|
See [PROTECTED_BRANCHES.md](PROTECTED_BRANCHES.md) for complete setup guide, troubleshooting, and examples.
|
|
|
|
## Branchless Workflows (Jujutsu / jj)
|
|
|
|
Beads works with branchless VCS tools like [Jujutsu (jj)](https://martinvonz.github.io/jj/). Since beads data is stored in Dolt (not git branches), there is no dependency on the "current branch" concept.
|
|
|
|
### What Works Without Hooks
|
|
|
|
All core beads functionality works without git hooks:
|
|
|
|
| Feature | Hooks Required? | Notes |
|
|
|---------|----------------|-------|
|
|
| `bd create`, `bd update`, `bd close` | No | Core CRUD uses Dolt directly |
|
|
| `bd ready`, `bd list`, `bd show` | No | Read-only queries |
|
|
| `bd dolt push` / `bd dolt pull` | No | Dolt-native sync, independent of git |
|
|
| `bd onboard`, `bd doctor` | No | Diagnostics and onboarding |
|
|
| Agent identity trailers | Yes | `prepare-commit-msg` hook adds `Executed-By:` to commits |
|
|
| Hook chaining | Yes | Preserves existing pre-commit, post-merge hooks |
|
|
|
|
**To skip hooks entirely during init:**
|
|
|
|
```bash
|
|
bd init --skip-hooks
|
|
```
|
|
|
|
### What Works Without AGENTS.md
|
|
|
|
The AGENTS.md file generated by `bd init` provides AI agent instructions (including "Landing the Plane" push/pull workflow). If you manage your own agent instructions or don't want beads to modify tracked files:
|
|
|
|
```bash
|
|
bd init --skip-agents # Skip AGENTS.md and Claude settings generation
|
|
bd init --stealth # Full invisible mode (also skips hooks + agents)
|
|
```
|
|
|
|
### Jujutsu Setup
|
|
|
|
**Colocated repos** (`jj git init --colocate`): Git hooks work normally. Beads installs simplified hooks (no staging logic).
|
|
|
|
**Pure jj repos** (no git): Since jj doesn't have native hooks yet, set up push aliases:
|
|
|
|
```toml
|
|
# ~/.config/jj/config.toml
|
|
[aliases]
|
|
push = ["util", "exec", "--", "sh", "-c", "bd dolt commit && bd dolt push && jj git push \"$@\"", ""]
|
|
```
|
|
|
|
### Merge Conflicts
|
|
|
|
Configure jj to use beads' merge driver for `.beads/issues.jsonl`:
|
|
|
|
```toml
|
|
# ~/.config/jj/config.toml
|
|
[merge-tools.beads-merge]
|
|
program = "bd"
|
|
merge-args = ["merge", "$output", "$base", "$left", "$right"]
|
|
merge-conflict-exit-codes = [1]
|
|
```
|
|
|
|
Then resolve with: `jj resolve --tool=beads-merge .beads/issues.jsonl`
|
|
|
|
## Git Hooks
|
|
|
|
### External Hook Manager Support
|
|
|
|
bd detects and integrates with these external git hook managers:
|
|
|
|
- **[lefthook](https://lefthook.dev/)** — YAML/TOML/JSON config
|
|
- **[husky](https://typicode.github.io/husky/)** — `.husky/` directory scripts
|
|
- **[pre-commit](https://pre-commit.com/)** — `.pre-commit-config.yaml`
|
|
- **[prek](https://prek.j178.dev/)** — Rust-based pre-commit alternative (same config)
|
|
- **[hk](https://hk.jdx.dev/)** — Fast hook manager using Pkl config
|
|
- **[overcommit](https://github.com/sds/overcommit)** — Ruby-based (detection only)
|
|
- **[simple-git-hooks](https://github.com/toplenboren/simple-git-hooks)** — Lightweight JS (detection only)
|
|
|
|
When an external hook manager is detected, `bd hooks install` uses `--chain` to preserve existing hooks.
|
|
|
|
#### hk Integration Example
|
|
|
|
Add bd hooks to your `hk.pkl`:
|
|
|
|
```pkl
|
|
hooks {
|
|
["pre-commit"] {
|
|
steps {
|
|
["bd-pre-commit"] {
|
|
check = "bd hooks run pre-commit"
|
|
}
|
|
}
|
|
}
|
|
["post-merge"] {
|
|
steps {
|
|
["bd-post-merge"] {
|
|
check = "bd hooks run post-merge"
|
|
}
|
|
}
|
|
}
|
|
["pre-push"] {
|
|
steps {
|
|
["bd-pre-push"] {
|
|
check = "bd hooks run pre-push \"$@\""
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Install hooks
|
|
bd hooks install --beads
|
|
```
|
|
|
|
### What Gets Installed
|
|
|
|
**pre-commit hook:**
|
|
- Runs pre-commit checks for beads data consistency
|
|
|
|
**post-merge hook:**
|
|
- Ensures Dolt database is current after pull/merge operations
|
|
|
|
### Hook Timeout
|
|
|
|
The beads hook shim wraps `bd hooks run` with an OS-level `timeout` to prevent hooks from hanging git operations indefinitely. The default timeout is **300 seconds** (5 minutes), which accommodates repos with chained pre-commit pipelines (e.g., eslint, prettier, TypeScript compilation).
|
|
|
|
If your chained hooks need more time, override the timeout with the `BEADS_HOOK_TIMEOUT` environment variable:
|
|
|
|
```bash
|
|
# Set a longer timeout (in seconds)
|
|
export BEADS_HOOK_TIMEOUT=600 # 10 minutes
|
|
|
|
# Or set it per-invocation
|
|
BEADS_HOOK_TIMEOUT=600 git commit -m "..."
|
|
```
|
|
|
|
When the timeout is reached, beads prints a warning and allows the git operation to proceed (the commit/push is not blocked).
|
|
|
|
### Hook Implementation Details
|
|
|
|
#### Hook Installation (`cmd/bd/hooks.go`)
|
|
|
|
The `installHooks()` function:
|
|
- Writes embedded hook scripts to the `.git/hooks/` directory
|
|
- Creates the hooks directory with `os.MkdirAll()` if needed
|
|
- Backs up existing hooks with `.backup` extension (unless `--force` flag used)
|
|
- Sets execute permissions (0755) on installed hooks
|
|
- Supports shared mode via `--shared` flag (installs to `.beads-hooks/` instead)
|
|
|
|
#### Git Directory Resolution
|
|
|
|
**Critical for worktree support:** The `getGitDir()` helper uses `git rev-parse --git-dir` to resolve the actual git directory:
|
|
|
|
```go
|
|
// Returns ".git" in normal repos
|
|
// Returns "/path/to/shared/.git" in git worktrees
|
|
gitDir, err := getGitDir()
|
|
```
|
|
|
|
In **normal repositories**, `.git` is a directory containing the git internals.
|
|
In **git worktrees**, `.git` is a file containing `gitdir: /path/to/actual/git/dir`.
|
|
|
|
#### Hook Detection (`cmd/bd/init.go`)
|
|
|
|
The `detectExistingHooks()` function scans for existing hooks and classifies them:
|
|
|
|
- **bd hooks**: Identified by "bd (beads) pre-commit hook" comment in content
|
|
- **pre-commit framework hooks**: Detected by "pre-commit framework" or "pre-commit.com" in content
|
|
- **Custom hooks**: Any other existing hook
|
|
|
|
## Multi-Workspace Sync
|
|
|
|
### Fork-Based Pattern
|
|
|
|
```
|
|
┌──────────────┐ ┌─────────────────┐
|
|
│ OSS Contrib │─────▶│ Planning Repo │
|
|
│ (Fork) │ │ (.beads/dolt/) │
|
|
└──────────────┘ └─────────────────┘
|
|
│
|
|
│ PR
|
|
▼
|
|
┌─────────────────┐
|
|
│ Upstream Repo │
|
|
│ (no .beads/) │
|
|
└─────────────────┘
|
|
```
|
|
|
|
**Best for:**
|
|
- Open source contributors
|
|
- Solo developers
|
|
- Private task tracking on public repos
|
|
|
|
**Setup:**
|
|
```bash
|
|
bd init --contributor # Interactive wizard
|
|
```
|
|
|
|
### Team Branch Pattern
|
|
|
|
```
|
|
┌──────────────┐
|
|
│ Team Member │────┐
|
|
│ (main) │ │
|
|
└──────────────┘ │
|
|
▼
|
|
┌──────────────┐ ┌─────────────────┐
|
|
│ Team Member │─▶│ Shared Repo │
|
|
│ (main) │ │ (beads-sync) │
|
|
└──────────────┘ └─────────────────┘
|
|
```
|
|
|
|
**Best for:**
|
|
- Teams on protected branches
|
|
- Managed git workflows
|
|
- Review-before-merge policies
|
|
|
|
**Setup:**
|
|
```bash
|
|
bd init --team # Interactive wizard
|
|
```
|
|
|
|
See [MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md) for complete guide.
|
|
|
|
## Git Configuration Best Practices
|
|
|
|
### Recommended .gitignore
|
|
|
|
```
|
|
# Dolt database (not tracked in git)
|
|
.beads/dolt/
|
|
|
|
```
|
|
|
|
### Git LFS Considerations
|
|
|
|
The Dolt database directory (`.beads/dolt/`) should be gitignored, not tracked via LFS or regular git.
|
|
|
|
## Custom Merge Driver
|
|
|
|
bd includes a built-in merge driver for resolving conflicts in `.beads/issues.jsonl` files. This replaces the standalone `beads-merge` binary that was previously maintained in a separate repository.
|
|
|
|
### Alternative: Standalone beads-merge Binary (Deprecated)
|
|
|
|
> **⚠️ Deprecated:** The standalone `beads-merge` binary (previously hosted at `github.com/neongreen/mono`) is no longer maintained and may be incompatible with current versions of bd. Use `bd merge` instead.
|
|
|
|
The built-in `bd merge` command provides the same functionality:
|
|
|
|
```bash
|
|
bd merge <output> <base> <left> <right>
|
|
```
|
|
|
|
### Jujutsu Integration
|
|
|
|
> See also: [Branchless Workflows](#branchless-workflows-jujutsu--jj) for a complete guide.
|
|
|
|
**For [Jujutsu](https://martinvonz.github.io/jj/) users**, add to `~/.config/jj/config.toml`:
|
|
|
|
```toml
|
|
[merge-tools.beads-merge]
|
|
program = "bd"
|
|
merge-args = ["merge", "$output", "$base", "$left", "$right"]
|
|
merge-conflict-exit-codes = [1]
|
|
```
|
|
|
|
Then resolve conflicts with:
|
|
|
|
```bash
|
|
jj resolve --tool=beads-merge .beads/issues.jsonl
|
|
```
|
|
|
|
This configures Jujutsu to invoke `bd merge` as its merge tool, restricted to `.beads/issues.jsonl` (since it only handles beads data conflicts, not general file conflicts).
|
|
|
|
## See Also
|
|
|
|
- [AGENTS.md](../AGENTS.md) - Main agent workflow guide
|
|
- [PROTECTED_BRANCHES.md](PROTECTED_BRANCHES.md) - Protected branch workflows
|
|
- [MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md) - Multi-repo patterns
|