git-worktree-conventions.md

gistfile1.txt

# Git Worktree Conventions

## Directory layout

All worktrees live under `.trees/` in the repository root. Add `.trees/` to `.gitignore`.

```
my-project/
├── .git/
├── .gitignore        # includes .trees/
├── .trees/
│   ├── feat-auth/
│   ├── fix-billing/
│   └── spike-new-api/
├── src/
└── ...
```

## Creating a worktree

Always pull main before branching to avoid stale-base merge conflicts:

```bash
git checkout main && git pull origin main
git worktree add -b <branch-name> .trees/<branch-name> main
cd .trees/<branch-name>
```

Use the same name for the branch and the directory.

## Branch naming

Use short prefixed names: `feat-`, `fix-`, `spike-`, `chore-`. Example: `feat-order-qualification`, `fix-stripe-webhook`.

## Working in a worktree

- Install dependencies in the worktree if needed (`bundle install`, `npm install`, etc.)
- Each worktree gets its own Claude Code session with its own context
- Do not modify files outside the worktree directory
- Commit and push to origin freely

## Finishing work

All merges happen via pull request on GitHub, never locally. When a PR is merged:

```bash
# From the repo root (not inside .trees/)
git worktree remove .trees/<branch-name>
git branch -d <branch-name>
git fetch --prune
```

## Rules

- One branch per worktree, one worktree per branch
- Never work directly on `main` — always use a worktree
- Clean up worktrees promptly after the PR merges
- Do not use bare repo cloning; use a standard clone with `.trees/`