Git Worktree

GIT Tutorials

GIT

Git worktree lets one repository have multiple working directories. Each worktree can check out a different branch, so you can fix a production issue, review another branch, or run tests without stashing the changes in your main directory.

The original checkout is the main worktree. Additional directories are linked worktrees. They share repository objects and most references, but each worktree keeps its own checked-out files, HEAD, and index.

Check Your Repository

Run the status and worktree list commands from the repository before adding another directory. The list always includes the main worktree.

Example:

# Confirm the current branch and existing worktrees.
git status --short --branch
git worktree list

Example output:

## main...origin/main
C:/projects/shop  6a42d11 [main]

Add a Worktree with a New Branch

Use git worktree add with -b to create a branch and check it out in a sibling directory. The final argument selects the commit or branch from which the new branch starts.

Example:

# Create fix/payment-timeout from main in a separate directory.
git worktree add -b fix/payment-timeout ../shop-payment-fix main

# Enter the new worktree and confirm its branch.
cd ../shop-payment-fix
git status --short --branch

Example output:

Preparing worktree (new branch 'fix/payment-timeout')
HEAD is now at 6a42d11 Improve checkout validation
## fix/payment-timeout

Choose a directory outside the main worktree. Keeping linked worktrees as siblings makes it easier to see which directories belong to the same repository.

Add an Existing Branch

If the branch already exists and is not checked out elsewhere, give Git the directory and branch name.

Example:

# Check out the existing feature/search branch separately.
git worktree add ../shop-search feature/search

Git normally prevents the same branch from being checked out in two worktrees. This protection avoids separate directories updating the same branch reference unexpectedly. Use a different branch or a detached worktree instead of forcing the same branch.

Create a Detached Worktree

A detached worktree is useful for inspecting a tag or commit without moving a branch. Commits created there are not attached to a branch until you create one.

Example:

# Inspect release v2.4.0 without checking out a branch.
git worktree add --detach ../shop-v2.4 v2.4.0

# Create a branch later if you decide to keep new commits.
cd ../shop-v2.4
git switch -c investigate/v2.4

List Worktree Details

The normal list is compact. Add --verbose for human-readable details or --porcelain for stable machine-readable output used by scripts.

Example:

# Show details for a person.
git worktree list --verbose

# Use stable output in automation.
git worktree list --porcelain

Example porcelain output:

worktree C:/projects/shop
HEAD 6a42d11af91d5f7c2f084f83cb58b703f9ea41c0
branch refs/heads/main

worktree C:/projects/shop-payment-fix
HEAD 6a42d11af91d5f7c2f084f83cb58b703f9ea41c0
branch refs/heads/fix/payment-timeout

Common Git Worktree Commands

Command Purpose
git worktree add Creates a linked worktree.
git worktree list Shows registered worktrees.
git worktree move Moves a linked worktree to another path.
git worktree remove Removes a clean linked worktree and its metadata.
git worktree lock Prevents automatic cleanup of a worktree.
git worktree prune Removes stale administrative records.
git worktree repair Repairs links after paths change outside Git.

Remove a Worktree Safely

Commit, stash, or discard any intended changes first. Then use Git to remove the linked directory and unregister it in one operation.

Example:

# Check the linked worktree before removal.
git -C ../shop-payment-fix status --short

# Remove it after the working tree is clean.
git worktree remove ../shop-payment-fix

# Delete the branch separately if it is no longer needed.
git branch -d fix/payment-timeout

Example output:

Deleted branch fix/payment-timeout (was b7c915e).

Important: Do not delete an active worktree directory manually. git worktree remove lets Git verify the directory and clean its administrative data.

Lock Portable or Temporary Worktrees

If a linked worktree sits on a removable or temporarily unavailable drive, lock it so prune does not treat it as abandoned. Add a reason that explains why it may disappear.

Example:

# Protect a worktree stored on a drive that may be disconnected.
git worktree lock --reason "External review drive" E:/review-copy

# Unlock it when the path is permanently available again.
git worktree unlock E:/review-copy

Repair and Prune Metadata

If you move the main repository or a linked directory without git worktree move, use repair to restore the connection. Use prune --dry-run before cleanup to see which stale entries Git would remove.

Example:

# Preview stale worktree records before deleting metadata.
git worktree prune --dry-run --verbose

# Repair links after an external directory move.
git worktree repair ../shop-search

If the dry run finds a removable entry, it prints the worktree path and the reason. No output means Git found nothing to prune. The repair command may also finish without output when no correction is needed.

Choose Worktrees or Clones

  • Use worktrees for several branches of the same local repository.
  • Use a separate clone when you need independent object storage, remotes, or repository configuration.
  • Remember that pruning objects, refs, and repository-level maintenance can affect all linked worktrees.
  • Run build tools with separate output directories if they create branch-specific caches.

Conclusion

Git worktree gives each task its own checked-out directory while sharing one repository. Add a new or existing branch, inspect registered paths, and remove linked worktrees through Git. Branch protection, locking, and dry-run cleanup help you use parallel workspaces without losing changes or leaving stale metadata.

Found This Page Useful? Share It!
Get the Latest Tutorials and Updates
Join us on Telegram