Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as opaque submodule gitlinks on GitHub) into fully-tracked first-party content. AITM now merges its 7 vendored repos as first-party engines: - memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts - git: vendored C git (bundled binary) + gitnexus (in-process code intelligence) - agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess) Includes the full session's product build: Gitgram web/mobile/backend features, AITM website/CLI/MCP, the unified memory layer, engine build tooling (scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md), and extensive test suites. Build artifacts, node_modules, external/, and gemini-cli are gitignored. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
122 lines
2.3 KiB
Markdown
122 lines
2.3 KiB
Markdown
---
|
|
id: git-integration
|
|
title: Git Integration
|
|
sidebar_position: 2
|
|
---
|
|
|
|
# Git Integration
|
|
|
|
How beads integrates with git.
|
|
|
|
## Overview
|
|
|
|
Beads uses git for:
|
|
- **Project hosting** - Your code repository also hosts beads configuration
|
|
- **Hooks** - Auto-sync on git operations
|
|
|
|
Data storage and sync are handled by Dolt (a version-controlled SQL database).
|
|
|
|
## File Structure
|
|
|
|
```
|
|
.beads/
|
|
├── config.yaml # Project config (git-tracked)
|
|
├── metadata.json # Backend metadata (git-tracked)
|
|
└── dolt/ # Dolt database and server data (gitignored)
|
|
```
|
|
|
|
## Git Hooks
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
bd hooks install
|
|
```
|
|
|
|
Installs:
|
|
- **pre-commit** - Triggers Dolt commit
|
|
- **post-merge** - Triggers Dolt sync after pull
|
|
- **pre-push** - Ensures Dolt sync before push
|
|
|
|
### Status
|
|
|
|
```bash
|
|
bd hooks status
|
|
```
|
|
|
|
### Uninstall
|
|
|
|
```bash
|
|
bd hooks uninstall
|
|
```
|
|
|
|
## Conflict Resolution
|
|
|
|
Dolt handles merge conflicts at the database level using its built-in
|
|
merge capabilities. When conflicts arise during sync, Dolt identifies
|
|
conflicting rows and allows resolution through SQL.
|
|
|
|
```bash
|
|
# Check for and fix conflicts
|
|
bd doctor --fix
|
|
```
|
|
|
|
## Protected Branches
|
|
|
|
Dolt stores data under `refs/dolt/data`, separate from Git refs. This means beads data doesn't conflict with protected Git branches — no special branch flag is needed. On new projects with a git `origin`, `bd init` configures that origin as the Dolt remote automatically.
|
|
|
|
## Git Worktrees
|
|
|
|
Beads works in git worktrees using embedded mode:
|
|
|
|
```bash
|
|
# In worktree — just run commands directly
|
|
bd create "Task"
|
|
bd list
|
|
```
|
|
|
|
## Branch Workflows
|
|
|
|
### Feature Branch
|
|
|
|
```bash
|
|
git checkout -b feature-x
|
|
bd create "Feature X" -t feature
|
|
# Work...
|
|
bd dolt push
|
|
git push
|
|
```
|
|
|
|
### Fork Workflow
|
|
|
|
```bash
|
|
# In fork
|
|
bd init --contributor
|
|
# Work in separate planning repo...
|
|
bd dolt push
|
|
```
|
|
|
|
### Team Workflow
|
|
|
|
```bash
|
|
bd init --team
|
|
# All team members share the Dolt database
|
|
bd dolt pull # Pull latest changes from Dolt remote
|
|
bd dolt push # Push your changes to Dolt remote
|
|
```
|
|
|
|
### Duplicate Detection
|
|
|
|
After merging branches:
|
|
|
|
```bash
|
|
bd duplicates --auto-merge
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Install hooks** - `bd hooks install`
|
|
2. **Push regularly** - `bd dolt push` at session end
|
|
3. **Pull before work** - `bd dolt pull` to get latest issues
|
|
4. **Worktrees use embedded mode automatically**
|