Terminal Guidegit worktree Command Guide
Manage multiple working trees
Dai Aoki
CEO at init, Inc. / CTO at US & JP startups / Creator of WebTerm
Quick Reference
Create
git worktree add <path> <branch>Add worktreegit worktree add -b <new> <path>New branchgit worktree add --detach <path>Detached HEADManage
git worktree listList worktreesgit worktree remove <path>Remove worktreegit worktree pruneClean stale entriesInfo
git worktree list --porcelainMachine formatgit worktree lock <path>Prevent pruninggit worktree unlock <path>Allow pruningDownloadable Image Preview
Basic Usage
The git worktree command manages multiple working directories attached to the same repository. Work on multiple branches simultaneously without stashing or cloning.
# Add a worktree for an existing branch
git worktree add ../feature-work feature-branch
# Add a worktree with a new branch
git worktree add -b hotfix ../hotfix-work main
# List all worktrees
git worktree listWhy Use Worktrees?
Common Use Cases
- Parallel development: Work on feature and hotfix simultaneously
- Code review: Check out PR branches without disrupting your work
- Long builds: Continue coding while another branch builds
- Comparing versions: Have multiple versions side by side
Worktree
- • Shared .git directory
- • Shared object database
- • Instant branch access
- • Less disk space
Clone
- • Separate .git directory
- • Separate object database
- • Need to fetch/push
- • More disk space
Creating Worktrees
# Basic: checkout existing branch in new directory
git worktree add ../my-feature feature-branch
# Create new branch from current HEAD
git worktree add -b new-feature ../new-feature-work
# Create new branch from specific commit/branch
git worktree add -b hotfix ../hotfix-work main
# Detached HEAD (same commit, no branch)
git worktree add --detach ../review abc1234
# Worktree for a tag
git worktree add --detach ../v1-release v1.0.0../repo-feature alongside your main repo.Managing Worktrees
# List all worktrees
git worktree list
# /path/to/main abc1234 [main]
# /path/to/feature def5678 [feature-branch]
# Detailed listing
git worktree list --porcelain
# Remove a worktree (preferred method)
git worktree remove ../feature-work
# Force remove (even with changes)
git worktree remove --force ../feature-work
# Clean up stale entries (if directory was deleted manually)
git worktree prune
# Lock worktree to prevent pruning
git worktree lock ../important-work
git worktree lock --reason "Long-running experiment" ../experiment
# Unlock worktree
git worktree unlock ../important-work| Command | Description |
|---|---|
| add <path> <branch> | Create worktree for branch |
| add -b <new> <path> | Create worktree with new branch |
| list | List all worktrees |
| remove <path> | Remove a worktree |
| prune | Clean stale worktree info |
Practical Examples
# Scenario: Urgent hotfix while working on feature
# You're on feature-branch with uncommitted changes
# Option 1: Without worktree (traditional)
git stash
git checkout main
git checkout -b hotfix
# ... make fix ...
git checkout feature-branch
git stash pop
# Option 2: With worktree (better)
git worktree add -b hotfix ../hotfix main
cd ../hotfix
# ... make fix, commit, push ...
cd ../main-repo
git worktree remove ../hotfix
# Your feature work is untouched!
# Review a pull request
git fetch origin pull/123/head:pr-123
git worktree add ../pr-123-review pr-123
cd ../pr-123-review
# Review, test, etc.
cd ../main-repo
git worktree remove ../pr-123-review
# Compare two versions side by side
git worktree add --detach ../v1 v1.0.0
git worktree add --detach ../v2 v2.0.0
# Now compare ../v1 and ../v2 in your editor
# Continuous integration helper
git worktree add ../build-dir main
cd ../build-dir
npm run build # Build runs here
# Continue coding in main worktree--detach for detached HEAD.Frequently Asked Questions
What is a Git worktree?
A worktree is an additional working directory linked to the same repository. Each worktree can have a different branch checked out, allowing parallel work without stashing or cloning.
How is worktree different from cloning?
Worktrees share the same .git directory and object database, saving disk space. Clones are completely separate repositories. Changes in one worktree are immediately visible to others.
Can I checkout the same branch in multiple worktrees?
No, each branch can only be checked out in one worktree at a time. This prevents conflicts. Use "git worktree add --detach" for the same commit in detached HEAD state.
What happens to worktrees when I delete them?
Use "git worktree remove <path>" to properly remove a worktree. Just deleting the folder leaves stale entries - run "git worktree prune" to clean them up.
Summary
git worktree enables parallel development by creating multiple working directories from one repository. Perfect for context switching without stashing.
Quick Reference
git worktree add <path> <branch>- Add worktreegit worktree add -b <new> <path>- New branchgit worktree list- List all worktreesgit worktree remove <path>- Remove worktree
Official Documentation
For authoritative information, refer to the official documentation: