Work on Multiple Branches Simultaneously with Worktrees

Advanced8 min

Use Git worktrees to check out multiple branches in separate directories, enabling parallel work without stashing or context switching.

Prerequisites

-Git 2.5 or later
-A repository with at least two branches

Steps

Create a worktree for an existing branch

Creates a new directory at ../project-hotfix with the hotfix/urgent-fix branch checked out. Your main working tree is unaffected.

$ git worktree add ../project-hotfix hotfix/urgent-fix

The directory must not already exist. Git will create it for you.

Create a worktree with a new branch

Creates a new branch feature/new-api based on main and checks it out in ../project-api. Combines branch creation and worktree setup.

$ git worktree add -b feature/new-api ../project-api main

List all active worktrees

Shows all worktrees, their paths, the checked-out branch, and the HEAD commit for each.

$ git worktree list

Work in the new worktree

Navigate to the worktree directory and work as you normally would. Each worktree is a fully independent checkout sharing the same .git objects.

$ cd ../project-hotfix git status # Make changes, commit, push as normal

You can open each worktree in a separate editor window or terminal tab for true parallel development.

Remove a worktree when finished

Cleans up the worktree directory and unregisters it. The branch itself is not deleted.

$ git worktree remove ../project-hotfix

If the worktree has uncommitted changes, Git will refuse to remove it. Use --force to override, but you will lose uncommitted work.

Prune stale worktree references

Removes worktree metadata for directories that were manually deleted instead of using 'git worktree remove'.

$ git worktree prune

Full Script

full-script.sh

#!/usr/bin/env bash
# git-worktree-setup.sh — Create and manage worktrees
set -euo pipefail

ACTION="${1:-list}"
BRANCH="${2:-}"
DIR="${3:-}"

case "$ACTION" in
  create)
    if [ -z "$BRANCH" ]; then
      echo "Usage: $0 create <branch> [directory]"
      exit 1
    fi
    DIR="${DIR:-../$BRANCH}"
    echo "Creating worktree for branch '$BRANCH' at '$DIR'..."
    git worktree add "$DIR" "$BRANCH"
    echo "Done. cd into $DIR to start working."
    ;;
  new)
    if [ -z "$BRANCH" ]; then
      echo "Usage: $0 new <new-branch> [directory] (creates from current HEAD)"
      exit 1
    fi
    DIR="${DIR:-../$BRANCH}"
    echo "Creating new branch '$BRANCH' in worktree '$DIR'..."
    git worktree add -b "$BRANCH" "$DIR"
    echo "Done. cd into $DIR to start working."
    ;;
  remove)
    if [ -z "$BRANCH" ]; then
      echo "Usage: $0 remove <directory>"
      exit 1
    fi
    echo "Removing worktree at '$BRANCH'..."
    git worktree remove "$BRANCH"
    echo "Done."
    ;;
  list|*)
    echo "=== Active worktrees ==="
    git worktree list
    ;;
esac

FAQ

Discussion

Loading comments...

#!/usr/bin/env bash # git-worktree-setup.sh — Create and manage worktrees set -euo pipefail ACTION="${1:-list}" BRANCH="${2:-}" DIR="${3:-}" case "$ACTION" in create) if [ -z "$BRANCH" ]; then echo "Usage: $0 create <branch> [directory]" exit 1 fi DIR="${DIR:-../$BRANCH}" echo "Creating worktree for branch '$BRANCH' at '$DIR'..." git worktree add "$DIR" "$BRANCH" echo "Done. cd into $DIR to start working." ;; new) if [ -z "$BRANCH" ]; then echo "Usage: $0 new <new-branch> [directory] (creates from current HEAD)" exit 1 fi DIR="${DIR:-../$BRANCH}" echo "Creating new branch '$BRANCH' in worktree '$DIR'..." git worktree add -b "$BRANCH" "$DIR" echo "Done. cd into $DIR to start working." ;; remove) if [ -z "$BRANCH" ]; then echo "Usage: $0 remove <directory>" exit 1 fi echo "Removing worktree at '$BRANCH'..." git worktree remove "$BRANCH" echo "Done." ;; list|*) echo "=== Active worktrees ===" git worktree list ;; esac