Git Worktrees for Parallel Branch Work in the Terminal

Switching between branches in a single working directory usually means stashing changes or creating temporary commits before moving on. Git worktrees offer a different approach: a developer can check out more than one branch at a time, each in its own directory, all backed by the same repository.

What Git Worktrees Provide

According to the official Git documentation at https://git-scm.com/docs/git-worktree, git worktree manages multiple working trees attached to the same repository. A repository starts with one main worktree, created by git init or git clone, and can have zero or more linked worktrees added later. Each linked worktree shares the repository’s underlying data but keeps its own per-worktree files, including HEAD and the index.

The basic command adds a new directory tied to a branch:

git worktree add ../hotfix

This creates a branch named after the path’s final component and checks it out at that location. To work on an existing branch instead, the branch name is passed explicitly:

git worktree add ../feature-auth feature/authentication

By default, the same branch cannot be checked out in two worktrees at once, which prevents two directories from drifting out of sync on the same ref. The --force flag overrides this. Most references under refs/ are shared across worktrees, while HEAD, refs/bisect, refs/worktree, and refs/rewritten remain per-worktree.

Listing and Cleaning Up

The documentation describes git worktree list for showing every active tree. The main worktree appears first, followed by linked ones, each annotated with its revision and branch:

/path/to/main-source        abcd1234 [main]
/path/to/feature-auth       1234abc  [feature/authentication]

The --porcelain option produces stable, script-friendly output for tooling that needs to parse the list. When a feature is finished, git worktree remove deletes the directory, which must be clean unless --force is used. The git worktree prune command clears administrative files left behind by directories that were deleted manually, and git worktree lock protects a worktree from pruning, which the docs note is useful for trees stored on portable devices or network shares.

The Git documentation also flags a caveat: multiple checkout support is still considered experimental, and submodule support is incomplete, so making multiple checkouts of a superproject is not recommended.

A Practical Switch Without Stashing

The official docs give a direct example of the main benefit. When an urgent fix is needed during an in-progress refactor, a developer can spin up a separate tree rather than disturb the current work:

git worktree add -b emergency-fix ../temp main
cd ../temp
# make the fix and commit
git commit -a -m 'emergency fix'
cd -
git worktree remove ../temp

Worktrees From a Terminal UI

Terminal tools have started exposing worktrees directly. The lazygit project, documented at https://github.com/jesseduffield/lazygit, lets a user create a worktree from a selected branch and switch to it immediately by pressing a single key in its branches view. Its README frames the goal the same way the Git docs do: keeping several branches active at once without stashing changes or making temporary commits when moving between them. For developers who track work across parallel branches, that turns context switching into a navigation step rather than a cleanup chore.