Git Multiple Worktrees

Intermediate

Learner goal

By the end of this lesson, you should be able to create a linked working tree, understand how it relates to the main worktree and the shared repository, create a worktree for a new branch or an existing branch, create a detached worktree for temporary experimentation, and inspect the set of worktrees without treating them as separate repositories.

One repository can have multiple working trees

Git worktrees let one repository have a main working tree plus zero or more linked working trees. The linked trees share the repository data, while worktree-specific state such as HEAD and the index is kept distinct. This lets you have more than one branch checked out at the same time without cloning another repository.

git worktree list
git worktree add ../feature-work feature

The new directory is a linked worktree associated with the same repository. It is not an independent clone: commits and other repository objects are shared, while each worktree has its own checked-out files and worktree-specific state.

The repository has multiple working trees.?The linked worktree shares repository data but has its own checkout state.

Create a worktree for a new branch

The simplest `git worktree add <path>` form creates a new branch whose name is the final component of the path, starting from the current HEAD. You can make the branch name explicit with `-b` when the path and branch name should differ.

git worktree add ../hotfix
git worktree add -b emergency-fix ../temp

The first command uses the final path component as the new branch name when that form is applicable. The explicit `-b` form is clearer when teaching or scripting because the branch name is visible rather than inferred from a filesystem path.

The repository has multiple working trees.?The new worktree is created at ../temp with branch emergency-fix checked out.

Use an existing branch in another worktree

You can create a linked worktree from an existing branch by supplying the branch as the commit-ish argument. Git checks out that branch in the new worktree when the command is permitted. The fact that a branch is already used by another worktree matters; branch/worktree constraints are handled in depth in V464.

git worktree add ../release release

The repository has multiple working trees.?The linked worktree is created from the existing release branch when allowed.

Create a detached worktree for experiments

For temporary experimentation or testing that should not create or move a branch, use a detached worktree. The `--detach` form creates a linked worktree whose HEAD is detached at the selected commit. This is useful when the worktree itself is disposable or branchless.

git worktree add --detach ../experiment HEAD

Because the new worktree is detached, changes can be committed there without advancing a named branch. This lesson does not teach detached-HEAD recovery; the goal here is understanding why a detached worktree is a distinct checkout context.

The repository has multiple working trees.?The new worktree is linked to the repository and its HEAD is detached.

Inspect the worktrees

Use `git worktree list` to see the worktrees associated with the repository. The ordinary form is human-readable; `--porcelain` provides a stable machine-oriented format, and `-z` can terminate porcelain records with NUL characters when paths may contain newlines.

git worktree list
git worktree list --porcelain
git worktree list --porcelain -z

The list lets you confirm which paths are attached to the repository and which commit or branch each worktree represents. Prefer the documented command output over inspecting internal `$GIT_DIR/worktrees` paths directly.

The repository has multiple working trees.?Use `git worktree list --porcelain` when a script needs structured worktree information.

The worktree is attached to one repository

A linked worktree shares the repository with the main worktree rather than creating a second object database. At the same time, Git maintains worktree-specific state so that each checkout can have its own HEAD and index. This distinction is why two worktrees can hold different branches concurrently while still referring to the same repository history.

git rev-parse --git-common-dir
git rev-parse --git-dir
git rev-parse --show-toplevel

When a worktree is the right model

A linked worktree is useful when you need two local checkout contexts at once: for example, one directory can remain on a feature branch while another checks out a maintenance branch or a detached test state. This avoids repeatedly switching one working tree back and forth and avoids creating another independent clone just to obtain another checkout.

git worktree add -b maintenance ../maintenance
git worktree list

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.

Official references

This lesson is based only on the live official Git documentation. The `git-worktree` documentation defines the main and linked worktree model, `add`, `list`, new-branch and detached worktrees, shared repository data, and worktree-specific state. The `git-rev-parse` documentation supplies the path-resolution commands used to avoid assumptions about internal repository layout. Lifecycle management and branch constraints are intentionally deferred to V464.