git worktree

Workspaces & Large Projects

Check out several branches at once in separate folders


The 'git worktree' command gives one repository several working folders. Each folder has a different branch checked out, with its own files and staging area, while the history is shared. It is the alternative to stashing when you must switch tasks: open the urgent branch in another folder and keep your work in progress untouched. A branch can be checked out in only one folder at a time.

Synopsis

git worktree add [-b <new-branch>] <path> [<commit-ish>]
git worktree list
git worktree remove <worktree>
git worktree prune
[ ] optional| or<arg> placeholder... repeatable--flag option

Options

Click any option to expand

Beginner (3)

List all working folders with their commit and branch.

RecommendedKnow which branch is open where

Example

git worktree list

Delete a working folder (it must have no uncommitted changes unless --force).

RecommendedThe clean way to delete a worktree

Example

git worktree remove ../hotfix

Forget worktrees whose folders were deleted by hand.

When neededClean up after deleting a folder manually

Example

git worktree prune

Choosing the Right Option

Switching tasks

Three ways

CommandYour editsFolders
git stash + switchPut aside, then restoredOne
git commit (WIP) + switchIn a temporary commitOne
git worktree addUntouchedTwo

Examples

New branch in a new folder

git worktree add ../hotfix -b hotfix

Folder ../hotfix on a new branch.


Existing branch

git worktree add ../review feature/login

Review a branch without leaving yours.


List

git worktree list

Every folder with its branch.


Remove

git worktree remove ../hotfix

Delete the extra folder.

Workflow Examples

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

Open main in a new folder

2
cd ../hotfix

Fix, commit, push there

3
git worktree remove ../hotfix

Clean up when done

Troubleshooting

fatal: 'hotfix' is already used by worktree

Cause: That branch is checked out in another folder

Work in that folder, or remove the worktree first

Tips & Pitfalls

Best Practices

  • ✓Put worktrees next to the main folder (../name), not inside it.

Common Mistakes

  • ✗Deleting a worktree folder by hand — use git worktree remove (or prune afterwards).
  • ✗Trying to check out the same branch in two folders.

FAQ

A:

Yes: one repository, one history; only the checked-out files differ.