git worktree

What are worktrees

A worktree is a separate working directory attached to the same Git repository. Instead of having one working directory per repository, you can create multiple working directories, each checked out to a different branch. This allows you to work on multiple branches simultaneously without switching branches, stashing changes, or cloning the repository multiple times.

Worktrees share the same .git directory, meaning they share the same commit history, branches, stashes, and configuration. Changes made in one worktree are visible to other worktrees through the shared repository state. This makes worktrees ideal for parallel development workflows.

Creating worktrees

Use git worktree add to create a new working directory. You specify the path for the new worktree and the branch to check out. The branch can be an existing branch or a new branch created with the -b flag. The new worktree is immediately ready for development.

git worktree add ../feature-login feature/login

git worktree add -b hotfix-auth ../hotfix-auth main

It is conventional to place worktrees in a sibling directory rather than a subdirectory. For example, if your main repository is at /projects/myapp, create worktrees at /projects/myapp-feature or /projects/feature-myapp. This keeps the workspace organized and avoids nested .git directories.

Managing worktrees

Use git worktree list to see all active worktrees and their current branch. Use git worktree remove to delete a worktree when you are done with it. Git will refuse to remove a worktree with uncommitted changes, so commit or stash first.

# List all worktrees
git worktree list
# /projects/myapp              a1b2c3d [main]
# /projects/feature-login      e4f5g6h [feature/login]
# /projects/hotfix-auth        i7j8k9l [hotfix-auth]

# Remove a worktree
git worktree remove ../hotfix-auth

# Force remove with uncommitted changes (dangerous)
git worktree remove --force ../hotfix-auth

Common use cases

Worktrees shine in several common development scenarios. The most frequent use case is working on a hotfix while mid-feature. Instead of stashing half-finished work and context-switching, create a worktree for the hotfix branch and switch back when done. The feature worktree remains exactly as you left it.

• Hotfix while mid-feature: create a worktree for the hotfix branch without stashing
• Code review: check out a PR branch in a worktree to review and test locally
• Parallel features: work on two features simultaneously in separate directories
• Long-running builds: run tests in one worktree while coding in another
• Compare branches: have two branches checked out side by side for comparison

Worktree vs alternatives

Before worktrees existed, developers relied on stashing or cloning multiple copies of the repository. Each approach has tradeoffs in terms of speed, disk usage, and workflow friction. Worktrees offer the best balance for most parallel development scenarios.

Cleanup and best practices

Worktrees are lightweight but require discipline. Always remove worktrees when you are done with them. Never manually delete a worktree directory without using git worktree remove first. Use descriptive names for worktree paths so you can identify the branch at a glance.

• Use sibling directories for worktrees, not subdirectories
• Name worktree paths to match the branch name
• Remove worktrees promptly when work is complete
• Run git worktree prune periodically to clean up stale references
• Never manually delete the .git file inside a worktree
• Commit or stash changes before removing a worktree