Worktrees

Git Worktrees: The Modern Alternative

After this page you can check out a second branch in a second directory that shares the same .git.

One object store, several working trees

cd ~/desk/desk-api
git worktree add ~/desk/desk-api-hotfix hotfix/timeout

Git creates ~/desk/desk-api-hotfix on a new branch hotfix/timeout (or an existing branch if you name one that is not already checked out). Both directories share objects and refs. git commit in the hotfix tree moves hotfix/timeout. main in the original tree is untouched.

 ~/desk/desk-api/                 ~/desk/desk-api-hotfix/
 working tree on main             working tree on hotfix/timeout
         \                           /
          \                         /
           └── shared .git ────────┘
               objects, refs, reflog, remotes

git worktree list

Why not git clone again

A second clone duplicates objects. A worktree is cheap and sees the same remotes, stash, and reflog. You cannot check out the same branch in two worktrees; Git refuses so the two indexes cannot fight.

Linux workflow

git fetch origin
git worktree add ~/desk/desk-api-pr origin/feat/ping-json
cd ~/desk/desk-api-pr
# review, run tests
cd ~/desk/desk-api
git worktree remove ~/desk/desk-api-pr

remove deletes the extra directory after the working tree is clean. git worktree prune cleans metadata if you rm -rf the directory by hand.

Detached review

git worktree add --detach ~/desk/desk-api-tag v0.1.0

Inspect a tag without leaving your feature branch in the main directory.

Hooks and GIT_DIR

Worktrees have .git as a file pointing at the main repo’s worktrees/… metadata. Hooks still run from core.hooksPath or the main .git/hooks. Scripts that assume .git/ is a directory should call git rev-parse --git-dir.