Git Worktree Checkout: Work on Multiple Branches

One of the primary uses of git worktree is checking out multiple branches simultaneously. Instead of switching branches in a single working directory, you create a separate worktree for each branch you need. Each worktree has its own directory, index, and HEAD, so you can work on all of them at the same time without conflicts.

Try It: Checking Out Branches in Worktrees

Existing branch, -b new branch, remote branch, and --detach

The SetupOne Branch Per Worktree

You're on the acme project working on feature/payments. Today you need to check out multiple branches at the same time — a hotfix, a PR review, and a debug tag. With worktrees, each branch gets its own directory. Let's see the different ways to check out branches.

~/code/

1 directory

└── acme/ [feature/payments]← you are here
    ├── .git/  full git database
    ├── src/
    ├── package.json
    └── README.md

Checkout an Existing Branch

To check out a branch that already exists locally into a new worktree, pass the branch name as the second argument to git worktree add:

Checkout an existing local branch

# Check out the existing "main" branch in a new worktree
git worktree add ../acme-hotfix main

# The new worktree is ready to use
cd ../acme-hotfix
git status
# On branch main

The branch must not already be checked out in another worktree. Git enforces this rule to prevent two working directories from simultaneously modifying the same branch, which could cause index corruption.

Checkout a Remote Branch

If the branch exists on a remote but not locally, fetch the refs first and then create a worktree. Git will automatically set up tracking if a unique remote branch matches the name:

Checkout a remote branch

# Fetch the latest refs
git fetch origin feature/auth-refactor

# Create a worktree with a local tracking branch
git worktree add -b feature/auth-refactor ../acme-review origin/feature/auth-refactor

# Git creates a local branch tracking the remote
cd ../acme-review
git branch -vv
# * feature/auth-refactor  b2c3d4e [origin/feature/auth-refactor] Refactor auth middleware

If you want the local branch name to differ from the remote branch name, use the -b flag:

Custom local branch name

git worktree add -b auth-review ../acme-review origin/feature/auth-refactor

Checkout and Create a New Branch

Use the -b flag to create a new branch and check it out in a single command. This is the most common workflow for starting new feature work:

Create and checkout a new branch

# Create a new branch "hotfix/checkout-crash" based on main
git worktree add -b hotfix/checkout-crash ../acme-hotfix main

# The new branch is created and checked out
cd ../acme-hotfix
git log --oneline -1
# e4f5a6b (HEAD -> hotfix/checkout-crash, main) Deploy v2.3.1

If you omit both the -b flag and the branch name, Git uses the last path component as the branch name. If that branch does not exist yet, Git creates it from HEAD:

Infer branch name from the path

# Git uses "acme-hotfix" as the inferred branch name
git worktree add ../acme-hotfix

Detached HEAD Checkout

Sometimes you want to check out a specific commit, tag, or ref without creating or switching to a branch. Use the --detach flag for this:

Detached HEAD worktree

# Check out a specific tag in detached HEAD mode
git worktree add --detach ../acme-debug v2.3.1

# Check out a specific commit
git worktree add --detach ../acme-bisect e4f5a6b

This is useful for debugging a specific release, bisecting a regression, or comparing behavior across versions. Since no branch is checked out, the detached worktree does not block any branch from being used elsewhere.

Verify detached state

# Verify the detached state
cd ../acme-debug
git status
# HEAD detached at v2.3.1

The "Already Checked Out" Error

The most common error when checking out branches in worktrees is:

Already checked out error

$ git worktree add ../acme-second main
fatal: 'main' is already checked out at '/home/you/code/acme'

Git prevents the same branch from being checked out in two worktrees simultaneously. This is a safety feature — if two worktrees modified the same branch, they would overwrite each other's index and staging area.

Solutions to this error:

Create a new branch based on the target branch instead:

git worktree add -b hotfix/checkout-crash ../acme-hotfix main

Use --detach to check out the same commit without a branch:
```
git worktree add --detach ../acme-debug main
```
If the other worktree was deleted but not properly removed, prune the stale entry:
```
git worktree prune
git worktree add ../acme-hotfix main
```

For a detailed guide on resolving this error, see Troubleshooting: already checked out.

Git Worktree Checkout: Work on Multiple Branches

Try It: Checking Out Branches in Worktrees

Checkout an Existing Branch

Checkout a Remote Branch

Checkout and Create a New Branch

Detached HEAD Checkout

The "Already Checked Out" Error

You Might Also Like

Switching Worktrees

Already Checked Out Error

git worktree add