Git Worktree Tutorial

Git worktree lets you check out multiple branches of the same repository into separate directories simultaneously. Instead of stashing changes or cloning the repo again, you create a linked worktree and work on a different branch in parallel. This tutorial covers every git worktree subcommand with real-world examples so you can start using worktrees in your daily workflow.

Prerequisites

Git worktree was introduced in Git 2.5 (released July 2015). Verify your version before getting started:

git --version

If your version is below 2.5, upgrade Git using your system package manager. Some subcommands like git worktree move and git worktree lock require Git 2.17+.

Upgrade Git

# macOS (Homebrew)
brew install git

# Ubuntu / Debian
sudo apt-get install git

# Windows (winget)
winget install Git.Git

Quick Start

Here is how to use git worktree in three commands. From inside any Git repository:

Worktree in 30 seconds

# 1. Create a new worktree for a feature branch
git worktree add ../feature-login feature/login

# 2. Work in the new directory
cd ../feature-login

# 3. When finished, remove it
git worktree remove ../feature-login

Commands

Each subcommand is covered in detail on its own page. Click through for full syntax, flags, and examples.

git worktree add

Create a new worktree linked to your repository. Supports creating new branches, checking out existing branches, and tracking remote branches.

git worktree remove

Safely delete a worktree directory and its administrative files. Use --force to remove worktrees with uncommitted changes.

git worktree list

Display all worktrees associated with the repository, showing their paths, HEAD commits, and checked-out branches.

git worktree prune

Clean up stale worktree metadata when a worktree directory has been manually deleted or moved without using git worktree remove.

Merge across worktrees

Strategies for merging branches that live in separate worktrees, including pull-based and rebase-based workflows.

git worktree move

Relocate a worktree to a different path on disk without losing its link to the main repository. Requires Git 2.17+.

Switch branches in a worktree

Change which branch a worktree has checked out using git switch or git checkout, with notes on the one-branch-per-worktree rule.

git checkout with worktrees

Use git checkout inside a worktree to switch branches or restore files. Understand how worktrees interact with checkout restrictions.

git worktree lock

Prevent a worktree from being pruned, useful for worktrees on removable drives or network mounts that may be temporarily unavailable.

How Git Worktrees Work Under the Hood

Every Git repository has a main worktree (the directory where you ran git init or git clone) and can have zero or more linked worktrees. All worktrees share the same .git/objects store, refs, and configuration. This means:

No extra disk space for duplicated object data.
Commits, tags, and stashes are visible from every worktree.
Each worktree has its own index (staging area) and HEAD, so operations in one worktree do not affect another.
A branch can only be checked out in one worktree at a time to prevent conflicting changes.

Worktree internals

# Linked worktrees store a .git *file* (not a directory)
cat ../feature-login/.git
# gitdir: /path/to/main-repo/.git/worktrees/feature-login

Next Steps

Start with git worktree add to create your first linked worktree. When you are done with a worktree, head to git worktree remove to learn how to clean up properly. For a quick-reference card, see the home page.