You’re halfway through a feature when an urgent hotfix lands. git stash is already a graveyard of entries you’re afraid to pop, and git clone means waiting forever to reinstall dependencies — sound familiar?

Why Worktree Matters Even More in the Age of AI

Worktree used to mean “I can jump to a hotfix while my feature branch stays untouched.” In the AI era, it gets way more interesting —

You can have multiple Code Agents working on different features at the same time, each in its own worktree.

1
2
3
4

~/projects/myapp-worktree/
    OA-001/   ← Agent 1 building user permissions
    OA-002/   ← Agent 2 building report exports
    OA-003/   ← Agent 3 fixing a production bug

Each worktree is an isolated workspace. Agents don’t step on each other. Just open a few terminal windows, point each Agent at its own worktree, and let them work. When they’re done, you review, PR, and merge.

What used to be three tasks done sequentially by one person is now three Agents working in parallel — and you just review. Worktree goes from “a handy branch-switching trick” to core infrastructure for AI-powered parallel development.

But first, you need to get worktree itself working smoothly. In a large monorepo, switching branches is painful:

• node_modules + vendor/bundle can be several GB — reinstalling takes minutes
• config/database.yml, master.key, .env are gitignored — gone after checkout
• Different branches have different migrations — switching may require db:migrate + db:rollback
• git stash with a dozen entries? Good luck figuring out which is which

What you really want: multiple branches open at the same time, each doing its own thing.

Git Worktree does exactly that — one .git, multiple working directories, each locked to a branch. No extra clones, no stashing, true parallel development.

1
2
3
4
5
6

~/projects/myapp/                    ← main worktree (develop)
    .git/                            ← the one and only git database

~/projects/myapp-worktree/
    OA-12345-new-feature/            ← feature branch
    OA-67890-hotfix/                 ← hotfix branch

All worktrees share the same git history — fetch and push work from any directory. But each has its own independent working tree and index.

Get Started in 30 Seconds

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Create a worktree
git worktree add ../myapp-worktree/OA-12345 feature/OA-12345

# List all worktrees
git worktree list

# Remove
git worktree remove ../myapp-worktree/OA-12345

# Clean up stale references
git worktree prune

The Real Problem: Worktrees in Large Projects Aren’t Ready Out of the Box

This is what tutorials don’t tell you. A freshly created worktree is missing a ton of gitignored stuff: database.yml, master.key, .env, vendor/bundle, node_modules…

You don’t want to run bundle install + npm install in every worktree, do you?

The fix: symlink config and dependencies from the main repo. But hand-writing scripts means hardcoded paths, poor maintainability, and rewriting for every project.

So I built gw — a lightweight Git Worktree manager that handles this for you.

gw: Worktree Management in One Step

Install

1

curl -fsSL https://raw.githubusercontent.com/graysonchen/gw/main/install.sh | bash

Initialize Your Project

1
2
3

cd ~/projects/myapp
gw init                    # creates .gw/config and .gw/links
gw config edit-links       # edit the list of files/dirs to symlink

.gw/links is plain text, one path per line:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Config files
.bundle/config
config/database.yml
config/master.key
.env

# Dependencies (shared to save disk)
vendor/bundle
node_modules

# Cache
tmp/cache

Daily Usage

1
2
3
4
5

gw add feature/OA-12345   # create worktree + auto-symlink, one step
gw cd OA-12345             # jump to it (supports fzf fuzzy search)
gw list                    # list all worktrees
gw link OA-12345           # re-link after changing the links file
gw rm OA-12345             # clean up

One gw add and you’re ready to rails server.

What About the Database?

Code can run in parallel, but there’s only one database. Three strategies:

1. DB Dump / Load (recommended): make dbdump in the main repo, make dbload + db:migrate in the worktree
2. Separate databases: use a different database.yml in the worktree, pointing to myapp_dev_OA_12345
3. Code-only: don’t start the server — just review code, cherry-pick, diff. No database needed.

When Should You Use It?

Tool: gw — Git Worktree Manager