Git Worktree Cheat Sheet

Quick Reference Table

git worktree add

Creates a new working tree linked to the same repository. Each worktree checks out a different branch, letting you work on multiple branches simultaneously without stashing or cloning.

Create a worktree for an existing branch

# Syntax: git worktree add <path> <branch>
git worktree add ../feature-auth feature/auth

Create a worktree with a new branch

# The -b flag creates the branch if it doesn't exist
git worktree add -b feature/payments ../payments main

Create a worktree with a detached HEAD

# Useful for inspecting a specific commit or tag
git worktree add --detach ../review-v2 v2.0.0

Shorthand — infer branch name from path

# If the branch "staging" exists, Git checks it out automatically
git worktree add ../staging

See also: git worktree add (detailed tutorial)

git worktree list

Shows every worktree associated with the repository, along with the currently checked-out branch and the HEAD commit.

git worktree list
# Example output:
# /home/dev/project        abc1234 [main]
# /home/dev/project-hotfix def5678 [hotfix/login]
# /home/dev/project-feat   789abcd [feature/auth]

Porcelain format

Use --porcelainfor machine-readable output that is stable across Git versions — ideal for scripts.

git worktree list --porcelain
# worktree /home/dev/project
# HEAD abc1234abc1234abc1234abc1234abc1234abc1234
# branch refs/heads/main
#
# worktree /home/dev/project-hotfix
# HEAD def5678def5678def5678def5678def5678def5678
# branch refs/heads/hotfix/login

git worktree remove

Removes a linked worktree and deletes its working directory. Git refuses to remove a worktree with uncommitted changes unless you pass --force.

# Remove a clean worktree
git worktree remove ../hotfix

# Force-remove a worktree with uncommitted changes
git worktree remove --force ../hotfix

See also: git worktree remove (detailed tutorial)

git worktree prune

Cleans up worktree administrative data for worktrees whose working directories have been deleted manually (e.g., with rm -rf). This does not remove worktrees that still exist on disk.

# Prune stale worktree references
git worktree prune

# Dry-run: see what would be pruned without doing it
git worktree prune --dry-run

# Prune entries older than a certain time
git worktree prune --expire 30.days.ago

git worktree move

Moves an existing linked worktree to a new filesystem path. The main worktree (the original clone) cannot be moved with this command.

# Move a worktree to a different directory
git worktree move ../hotfix ../fixes/login-hotfix

Tip: If the target path already exists, the command fails. Make sure the destination does not exist beforehand.

git worktree lock / unlock

Locking prevents git worktree prune from removing a worktree whose path is temporarily unavailable (for example, on an unmounted external drive or network share).

# Lock a worktree (with an optional reason)
git worktree lock --reason "on external SSD" ../portable-wt

# Unlock it when the drive is available again
git worktree unlock ../portable-wt

git worktree repair

Repairs the internal links between the main repository and its linked worktrees. This is useful after you manually move the main repository or a worktree directory without using git worktree move.

# Repair from inside the main repository
git worktree repair

# Repair and specify worktree paths explicitly
git worktree repair /new/path/to/worktree

Available since Git 2.30. If you are on an older version, you will need to manually fix the .git file in the worktree and the corresponding file in .git/worktrees/<name>/gitdir.