Git Worktree Cheat Sheet

Need parallel branches without cloning the same repository twice? Git worktree lets you attach multiple working directories to one repo, so you can work on features, hotfixes, and release branches side-by-side.

Why Use Git Worktree?

• Keep a clean main working tree while developing elsewhere.
• Switch contexts instantly for urgent fixes.
• Save disk space versus multiple full clones.
• Run different branch builds/tests in parallel.

Quick Start

# From your existing repository

git worktree add ../feature-login -b feature/login
cd ../feature-login
git status

This creates a new directory (../feature-login) checked out to a new branch (feature/login), all tied to the same .git metadata.

Git Worktree Cheat Sheet

Task	Command
List worktrees	git worktree list
Add a worktree on existing branch	git worktree add ../hotfix-123 hotfix/123
Add and create new branch	git worktree add ../feat-api -b feat/api
Lock worktree (prevent prune)	git worktree lock ../feat-api
Unlock worktree	git worktree unlock ../feat-api
Remove worktree	git worktree remove ../feat-api
Prune stale metadata	git worktree prune
Repair moved worktree paths	git worktree repair

Docker Stack Integration

Git worktree is branch management. Docker handles runtime. They work together well when each worktree gets a unique Docker Compose project name and non-conflicting host ports.

# main branch worktree
cd ../localparts-main
docker compose -p localparts-main up -d

# feature branch worktree
cd ../localparts-feature-login
docker compose -p localparts-feature-login up -d

If both stacks map the same host ports, one stack fails to start. Use per-worktree .env values such as APP_PORT=8080 in one and APP_PORT=8081 in another.

Angular Integration

Run Angular from each worktree directory so it serves that branch’s files. Use different dev-server ports when running more than one branch at once.

# worktree A
cd ../localparts-main
npm ci
ng serve --port 4200

# worktree B
cd ../localparts-feature-login
npm ci
ng serve --port 4201

Typical Team Workflow

1. Keep your primary worktree on main.
2. Create a feature worktree per task.
3. Start that branch’s Docker/Angular process from its own worktree folder.
4. Use unique Compose project names and ports.
5. Merge and delete branch.
6. Remove worktree and prune.

# create worktree for feature
git worktree add ../localparts-feature-login -b feature/login

# run stack for that branch
cd ../localparts-feature-login
docker compose -p localparts-feature-login up -d
ng serve --port 4201

# after merge (from original repo)
git checkout main
git pull
git branch -d feature/login
git worktree remove ../localparts-feature-login
git worktree prune

Gotchas to Remember

• You cannot check out the same branch in two worktrees at once.
• Delete worktrees with git worktree remove (not just filesystem delete).
• If a worktree path is moved manually, run git worktree repair.
• Use unique ports/project names when running multiple Docker or Angular sessions.
• Use git worktree list --porcelain for scripting.

Use one repo, many workspaces. Then run each workspace as its own runtime context.