git worktree

Check out two branches at once without cloning twice.

🎯 What & why

Check out multiple branches of one repo into separate working directories simultaneously. Same .git/, multiple workspaces.

🧠 Mental model

A worktree is a separate working directory plus a tiny .git file pointing back at the main .git/ dir. Each worktree has its own HEAD and its own index. The object DB is shared.

🛠️ Synopsis

git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]
                 [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]
git worktree list [-v | --porcelain [-z]] [--expire <when>]
git worktree lock [--reason <string>] <worktree>
git worktree move <worktree> <new-path>
git worktree prune [-n] [-v] [--expire <expire>]
git worktree remove [-f] <worktree>
git worktree repair [<path>...]
git worktree unlock <worktree>

🎚️ Switches & options

Flag	What it does
`add <path> [<branch>]`	Create a new worktree at `<path>`.
`list`	List worktrees.
`remove <path>`	Remove an unused worktree.
`prune`	Clean up stale worktree records.
`--detach`	Create a worktree with detached HEAD.

📦 Subcommands

add <path> [<commit-ish>] — Create a new worktree at <path>.

$ git worktree add ../proj-hotfix release/1.2

list — List worktrees with their HEAD and branch.

$ git worktree list

lock <path> [--reason <text>] — Prevent automatic pruning.

$ git worktree lock ../proj-hotfix --reason 'paused mid-bisect'

unlock <path> — Allow pruning again.

$ git worktree unlock ../proj-hotfix

move <path> <new-path> — Relocate a worktree on disk.

$ git worktree move ../old-name ../new-name

remove <path> — Remove a worktree (must be clean).

$ git worktree remove ../proj-hotfix

prune — Drop stale records for worktrees deleted out-of-band.

$ git worktree prune

repair [<path>...] — Fix back-pointers after a parent repo move.

$ git worktree repair

💡 Use cases

Hotfix on a release branch while you're mid-feature on main.
Reviewing a PR locally without disturbing your work.
Running long-running CI/build in one worktree while developing in another.

🧪 Examples

Side worktree to test a fix while keeping main work intact.

$ git worktree add ../proj-hotfix release/1.2

List worktrees.

$ git worktree list

Remove when done.

$ git worktree remove ../proj-hotfix

🎓 Recommendations

Much faster than cloning twice — one object DB.
Don't share a worktree path with another tool that may delete files (CI, etc.).

🪤 Common pitfalls

Each worktree pins a branch. You can't check out the same branch in two worktrees.
Forgetting to worktree remove leaves stale records — git worktree prune cleans them.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.