Using Git Worktrees for Parallel Development

Desired outcome

Create an additional working tree (worktree) that shares the same object database as the main repository but has its own HEAD and index, so you can work on a different branch without cloning the whole repo.

Prerequisites

• Git version 2.5 or newer (worktree command introduced in 2.5).
• Access to a local repository that you can read and write.
• The repository should be in a clean state or you must be prepared to stash/discard any uncommitted changes you do not want to keep.
• Enough free disk space for the new worktree directory (roughly the size of the working files, not the full object database).

Procedure

1. Open a terminal and navigate to the root of the existing repository:

   cd /path/to/main-repo
   

2. Decide where the new worktree will live and which branch (or new branch) you want to check out there. For example, to create a worktree for an existing branch named feature/login at a sibling directory ../feature-login:

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

   The command creates the directory ../feature-login, populates it with the working files for feature/login, and links its internal .git file to the main repository’s object store.

3. If you need a brand‑new branch, use the -b flag:

   git worktree add ../feature-login -b feature/login
   

   This creates the branch feature/login from the current HEAD and checks it out in the new worktree.

4. Enter the new directory and work as you would in any clone:

   cd ../feature-login
   # edit, stage, commit, etc.
   

5. When the work is finished, you can remove the worktree safely:

   # From any location, preferably the main repo
   git worktree remove ../feature-login
   

   If you have already deleted the directory manually, run a prune to clean up the internal tracking:

   git worktree prune
   

Expected checks

• List worktrees to confirm the new entry appears:

  git worktree list
  

  Expected output includes a line similar to:

  /path/to/main-repo  abc1234 [main]
  ../feature-login  def5678 [feature/login]
  

• Verify that the worktree’s Git directory points to the main repository’s .git:

  cd ../feature-login
  git rev-parse --git-dir
  

  Should return something like /path/to/main-repo/.git/worktrees/feature-login which internally links to the main object database.

• Ensure uncommitted changes are isolated: make a change in the main worktree, then check that git status in the feature worktree shows a clean tree (or only changes you made there).

Recovery options

Creating a worktree does not alter the repository’s history; it only adds a reference to a working directory. If you need to undo the creation:

• If the worktree directory still exists, run git worktree remove <path> as shown above.
• If you accidentally deleted the directory without using the command, run git worktree prune to remove the stale entry from Git’s internal list.
• Should you have uncommitted changes in the worktree that you wish to keep, either commit or stash them before removal, or move the directory elsewhere and later re‑attach it with git worktree add <path> <branch> --detach (advanced).

Note: Running git worktree prune while another worktree has uncommitted changes can delete that worktree’s entry and risk losing work. Always ensure all worktrees are clean or have their changes committed/stashed before pruning.