feat(workflows): add database branch isolation with git worktrees

Add comprehensive documentation for combining git worktrees with database branches
for true feature isolation across Neon, PlanetScale, Supabase, and local Postgres.

Changes:
- examples/commands/git-worktree.md: Add database branch detection and quick reference (~90 lines)
- examples/workflows/database-branch-setup.md: New complete guide with TL;DR and provider workflows (349 lines)
- english-ultimate-claude-code-guide.md: Add section 9.12 "Database Branch Isolation with Worktrees" (~95 lines)
- CHANGELOG.md: Add v2.4.0 release notes
- README.md: Update version to 2.4, line count to 9500+, add source attributions

Architecture: Progressive disclosure pattern (concise command → complete workflow guide)
Sources: Neon branching docs, PlanetScale branching docs

Stats: ~540 lines added | Guide now 9,592 lines, 35,576 words

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX 2026-01-11 13:25:58 +01:00
parent 162b8562cf
commit 07b8810fe3
5 changed files with 572 additions and 9 deletions

View file

@ -9,9 +9,11 @@ Create isolated git worktrees for feature development without switching branches
1. **Check Existing Directories**: `.worktrees/` or `worktrees/`
2. **Verify .gitignore**: Ensure worktree dir is ignored
3. **Create Worktree**: `git worktree add`
4. **Install Dependencies**: Auto-detect package manager
5. **Run Baseline Tests**: Verify clean state
6. **Report Location**: Confirm ready
4. **Detect Database Provider**: Check for DB branching capability
5. **Suggest Database Branch**: Remind user with exact commands
6. **Install Dependencies**: Auto-detect package manager
7. **Run Baseline Tests**: Verify clean state
8. **Report Location**: Confirm ready
## Directory Selection
@ -97,6 +99,54 @@ Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
```
## Database Branch Suggestion
**After worktree creation, command detects database provider and suggests isolation.**
### Quick Command Reference
| Provider | Suggested Command |
|----------|-------------------|
| **Neon** | `neonctl branches create --name <branch> --parent main` |
| **PlanetScale** | `pscale branch create <db> <branch>` |
| **Local Postgres** | `psql -c "CREATE SCHEMA <schema>;"` |
| **Other** | Manual setup or shared DB |
**Example output:**
```
✅ Worktree created at .worktrees/feature-auth
💡 DB Isolation: neonctl branches create --name feature-auth --parent main
Then update .env with new DATABASE_URL
Full guide: ../workflows/database-branch-setup.md
```
### .worktreeinclude Setup
**Critical for environment variables:**
```bash
# .worktreeinclude (at project root)
.env
.env.local
.env.development
**/.claude/settings.local.json
```
**Why:** Without this, `.env` files won't be copied to worktrees → Claude sessions fail.
### When to Create Database Branch
| Scenario | Create Branch? |
|----------|---------------|
| Schema migrations | ✅ Yes |
| Data model refactoring | ✅ Yes |
| Bug fix (no schema change) | ❌ No |
| Performance experiments | ✅ Yes |
**See:** [Database Branch Setup Guide](../workflows/database-branch-setup.md) for complete workflows.
## Quick Reference
| Situation | Action |
@ -106,6 +156,9 @@ Ready to implement <feature-name>
| Both exist | Use `.worktrees/` |
| Neither exists | Check CLAUDE.md → Ask user |
| Not in .gitignore | Add + commit immediately |
| Neon detected | Suggest `neonctl branches create` |
| PlanetScale detected | Suggest `pscale branch create` |
| No .worktreeinclude | Create with `.env` pattern |
| Tests fail | Report + ask to proceed |
## Common Mistakes
@ -119,16 +172,34 @@ Ready to implement <feature-name>
**Proceeding with failing tests**
- Can't distinguish new bugs from pre-existing
**Not copying .env to worktree**
- Symptom: Claude fails with "DATABASE_URL not found"
- Fix: Add `.env` to `.worktreeinclude`
**Using shared database for schema changes**
- Symptom: Migration conflicts, broken dev environment
- Fix: Create database branch before modifying schema
## Cleanup (After Work Complete)
```bash
# Remove worktree
# 1. Remove git worktree
git worktree remove .worktrees/$BRANCH_NAME
# Or force if uncommitted changes
git worktree remove --force .worktrees/$BRANCH_NAME
# Prune stale worktrees
# 2. If you created a database branch, delete it
# Neon:
neonctl branches delete $BRANCH_NAME
# PlanetScale:
pscale branch delete <database-name> $BRANCH_NAME
# Local schema:
psql $DATABASE_URL -c "DROP SCHEMA ${BRANCH_NAME/\//_} CASCADE;"
# 3. Prune stale references
git worktree prune
```