A Practical Git Worktree Workflow for Parallel Development

A Practical Git Worktree Workflow for Parallel Development

Git worktrees let you work on multiple branches from the same repository at the same time, which makes context switching, hotfixes, and code review fixes much cleaner than juggling stashes or constantly checking out branches. This guide shows a simple, repeatable workflow you can use in real projects, with commands, setup advice, and cleanup steps.

Why worktrees help

A worktree is an additional working directory attached to the same repository, and Git explicitly supports one main worktree plus zero or more linked worktrees. Unlike a normal branch switch, a worktree gives each task its own folder, which is especially useful when you need to keep one branch stable while exploring another change.

This is not a replacement for branching. Instead, it is a way to make branches easier to use when you need parallel work, emergency fixes, or isolated testing.

When to use them

Use worktrees when you need to do any of these:

• Fix a production issue while a feature branch is mid-refactor.
• Review a pull request without disturbing your current dev environment.
• Run tests on one branch while continuing feature work on another.
• Compare behavior between two branches side by side.

Git’s own documentation includes a classic example: if you are in the middle of a refactor and an urgent fix appears, you can create a temporary linked worktree, make the fix, and remove the worktree afterward without disturbing the original session.

Core commands

The main commands are straightforward:

git worktree add ../hotfix hotfix-branch
git worktree list
git worktree remove ../hotfix
git worktree prune

git worktree add creates a new working tree, list shows active worktrees, remove deletes a clean one, and prune cleans stale metadata left behind by manually deleted directories. Git also supports move, lock, and repair for more advanced maintenance or recovery situations.

A convenient shortcut is git worktree add ../hotfix, which creates a new branch named after the folder if that branch does not already exist. If you want a worktree for an existing branch, add the branch name explicitly.

A recommended setup

Start from your main repo:

cd ~/projects/app
git status
git branch

Create a second worktree for a specific task:

git worktree add ../app-hotfix hotfix/payment-timeout
cd ../app-hotfix

Now you have two isolated folders:

• ~/projects/app for normal development.
• ~/projects/app-hotfix for the hotfix branch.

This is cleaner than stashing because each directory keeps its own working state, editor session, test server, and shell history.

Daily workflow

A simple daily rhythm looks like this:

1. Keep main or your primary branch in the main worktree.
2. Create one worktree per active task.
3. Open a separate terminal and editor window for each worktree.
4. Commit small changes inside the relevant worktree.
5. Remove the worktree once the branch is merged.

Example:

### main repo
git switch main
git pull

### new feature worktree
git worktree add ../app-search feature/search-v2
cd ../app-search
npm test
git add .
git commit -m "Add search query normalization"

### back in main repo, after merge
git worktree remove ../app-search
git worktree prune

Git’s docs note that removed worktrees should be cleaned up with remove or prune, and remove requires a clean tree unless you use force.

Handling hotfixes safely

Worktrees are especially good for urgent fixes because they let you avoid disturbing unfinished work. If your main worktree is full of local edits, you do not need to stash everything just to patch a bug.

A safe hotfix flow is:

git worktree add ../app-hotfix -b hotfix/login-failure main
cd ../app-hotfix
git commit -am "Fix login redirect loop"
git push -u origin hotfix/login-failure

Once the fix is merged and deployed, delete the worktree:

git worktree remove ../app-hotfix
git worktree prune

This keeps emergency work short-lived and easy to trace.

Good practices

A few habits make worktrees much easier to manage:

• Use clear folder names like ../app-feature-payments or ../app-bug-142.
• Keep one editor instance per worktree so file watchers and build tools do not collide.
• Install dependencies in each worktree if your project needs local tooling or generated files.
• Run git worktree list before deleting anything, especially in larger repos.

Git also allows locking a worktree to prevent accidental pruning or removal, which can help if it lives on a portable drive or network path.

Common mistakes

The biggest mistake is treating worktrees as a way to checkout the same branch in multiple places. Git generally prevents checking out the same branch in more than one worktree at once unless you force it, because that can create confusion and race conditions.

Another common mistake is forgetting cleanup. If you manually delete a worktree folder, run git worktree prune afterward so Git forgets the stale administrative entry. If you move a worktree directory by hand, use git worktree repair to reconnect the metadata.

Branch strategy around worktrees

Worktrees work best with short-lived topic branches and a stable main line. Git’s branching workflow docs describe topic branches as a way to isolate a single piece of work, context-switch cleanly, and merge when ready. That pairs naturally with worktrees because each topic branch can live in its own directory without affecting the others.

A practical pattern is:

• main stays production-ready.
• Each feature or bug fix gets its own short-lived branch.
• Each branch gets its own worktree only while active.
• Finished worktrees are deleted immediately after merge.

Example team policy

Here is a simple policy you can adopt for a small team:

1. One branch per task.
2. One worktree per active branch.
3. No branch stays in a worktree after merge.
4. Use worktrees for hotfixes, reviews, and parallel experiments.
5. Prune stale worktrees weekly.

That policy keeps the repo tidy while still giving people room to work in parallel. It also makes it much easier to reason about what is happening in each directory.

Command cheat sheet

git worktree add ../name branch-name   # Create a new worktree for an existing branch
git worktree add ../name               # Create a new branch and worktree named after the folder
git worktree list                      # Show all worktrees
git worktree remove ../name            # Remove a clean worktree
git worktree prune                     # Remove stale metadata
git worktree move ../old ../new        # Move a worktree cleanly
git worktree repair                    # Fix broken worktree links

If you want a lightweight, low-friction workflow for doing parallel Git work, worktrees are one of the most useful features Git already ships with.

Would you like a second version tailored for solo developers, teams using pull requests, or release/hotfix workflows?

-

Rizwan Saleem | https://rizwansaleem.co