Git Worktree Command•Step #1

git worktree add: Create Git Worktrees — Complete Guide

The git worktree add command creates a new working directory linked to your current Git repository. It allows you to check out any existing branch, commit, or create a brand-new branch in a separate folder simultaneously.

Basic Syntax

Terminal

# Basic git worktree add format

$git worktree add <path> [<commit-ish>]

<path> is the target directory where the new worktree will live (relative or absolute). If <commit-ish> is omitted, Git creates a new branch based on current HEAD matching the basename of the path.

1. Add a worktree from an existing branch

If a branch named feature/login already exists in your repository:

Terminal

# Create sibling directory and checkout feature/login

$git worktree add ../project-feature-login feature/login

Output Example

Preparing worktree (checking out 'feature/login')
HEAD is now at a1b2c3d Add login form validation

Resulting Directory Structure:

projects/
├── project/                <-- primary worktree [main]
└── project-feature-login/  <-- linked worktree [feature/login]

2. Create a new branch and worktree simultaneously

Use the -b <new-branch> flag to create a new branch from a starting point (e.g. main):

Terminal

# Creates branch 'feature/auth' branching off 'main'

$git worktree add -b feature/auth ../project-auth main

Output Example

Preparing worktree (new branch 'feature/auth')
HEAD is now at f4e5d6c Merge pull request #142 from main

3. Checkout a detached worktree or specific commit

For inspecting an older release tag or commit hash without creating a permanent branch, use --detach:

Terminal

# Checkout release tag v2.1.0 in detached HEAD state

$git worktree add --detach ../inspect-v2.1.0 v2.1.0

Complete practical workflow

Here is a realistic day-to-day workflow for starting a new task without interrupting ongoing work:

Terminal

# End-to-end setup for isolated feature development

$# 1. Update your primary repository main branch git switch main git pull origin main # 2. Create the worktree and new branch git worktree add -b feature/payments ../app-payments main # 3. Navigate into your new isolated directory cd ../app-payments # 4. Install dependencies or start isolated server npm install npm run dev

Common Command Flags

Flag	Purpose
-b <new-branch>	Create and checkout a new branch in the new worktree
-B <new-branch>	Force create or reset the branch to the start point
--detach	Checkout HEAD in a detached state (no branch attached)
--lock	Lock the worktree immediately upon creation
--reason <text>	Explanation string recorded with the lock
--no-checkout	Suppress checkout of the working tree files

Common Mistakes & Restrictions

Branch Already Checked Out Error

If the branch is already checked out in another worktree, Git will refuse to create another worktree for it. Check your existing worktrees with git worktree list. If the old worktree folder was deleted manually, run git worktree prune to clear stale records.

Choosing directory paths

Always use sibling paths like ../project-feature rather than nesting worktrees inside each other. Nesting can confuse IDE file watchers and cause duplicate git tracking errors.

WorktreeWise

Create Worktree

Try Free

With WorktreeWise, you can create worktrees from HEAD, any existing branch, tag, or commit in 1 click. WorktreeWise automatically creates the folder according to your custom naming pattern and triggers your configured setup hooks.

Create a new Git worktree from a branch in WorktreeWise

Next steps & related commands

After creating your worktree, learn how to inspect it with git worktree list or safely remove it after merging with git worktree remove.