Use a linked worktree for a second task

How-to Last tested 26 October 2026

A linked worktree gives an existing Git repository another working directory, with its own checked-out state and staging area. Use it when a second task needs different files checked out without disturbing the first directory’s unfinished edits. The branch history remains shared, so the extra directory is not an independent backup.

Start with a task and an existing branch

Suppose the primary directory is on main, while a second task belongs on topic. The example explicitly creates the topic branch, then names it when adding the linked worktree. That avoids relying on the destination directory’s name to decide whether Git should create a branch. The directory and branch have separate names because they identify different things.

Before using an existing branch, check where it is already checked out. A worktree is useful for separate tasks precisely because each directory has an identifiable current state. Trying to have the same branch checked out in two places can make that state harder to reason about. Git’s default guard refuses that situation rather than silently creating another checkout¹.

The example exercises the guard with main, which is already active in the primary directory. It expects refusal and stops if the command unexpectedly succeeds. It does not use a force option to bypass the check. In real work, choose another appropriate branch or use the directory that already has the branch, after inspecting its unfinished work.

A complete local example

This script creates a parent folder with a primary repository and a linked sibling directory. It changes the same file differently in each directory, stages only the second directory’s edit, and then checks both states. Finally it demonstrates a refused removal followed by a clean removal. Run it from an empty directory with Git 2.56.0 available.

Download the exact MIT-licensed example. It leaves the primary repository and the committed topic branch available for inspection.

#!/bin/sh
# SPDX-License-Identifier: MIT
set -eu
export TZ=UTC LC_ALL=C
export GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL=/dev/null
export GIT_AUTHOR_NAME='Example Author'
export GIT_AUTHOR_EMAIL='author@example.invalid'
export GIT_COMMITTER_NAME='Example Author'
export GIT_COMMITTER_EMAIL='author@example.invalid'
export GIT_AUTHOR_DATE='2026-10-25T12:00:00Z'
export GIT_COMMITTER_DATE='2026-10-25T12:00:00Z'
test "$(git --version)" = 'git version 2.56.0'
mkdir worktree-example
cd worktree-example
mkdir primary
cd primary
git -c init.templateDir= init -q -b main
printf 'base\n' > note.txt
git add note.txt
git commit -qm 'Base'
git branch topic
git worktree add -q ../second topic
test "$(git branch --show-current)" = main
test "$(git -C ../second branch --show-current)" = topic
if git worktree add -q ../refused main 2>/dev/null; then
  printf 'Expected branch-in-use refusal\n' >&2
  exit 1
fi
printf 'guard: second checkout of main refused\n'
printf 'main draft\n' > note.txt
printf 'topic draft\n' > ../second/note.txt
git -C ../second add note.txt
test -z "$(git diff --cached)"
test -n "$(git -C ../second diff --cached)"
test "$(cat note.txt)" = 'main draft'
test "$(cat ../second/note.txt)" = 'topic draft'
printf 'state: working files and staged changes are separate\n'
if git worktree remove ../second 2>/dev/null; then
  printf 'Expected dirty-worktree refusal\n' >&2
  exit 1
fi
printf 'guard: removal with staged work refused\n'
git -C ../second commit -qm 'Topic draft'
topic_tip=$(git rev-parse topic)
test "$(git show topic:note.txt)" = 'topic draft'
git worktree remove ../second
test ! -d ../second
test "$(git rev-parse topic)" = "$topic_tip"
printf 'remove: directory removed; topic branch retained\n'

Check the branch before editing

The first assertions ask each directory which branch is current. The primary directory reports main; the linked directory reports topic. These checks are deliberately separate from checking filenames. Both directories contain a file called note.txt, and that matching name says nothing about which branch a later commit would update.

Keep the location of your editor and shell in mind when moving between tasks. The example uses Git’s directory option for operations on the second worktree, making the destination explicit in the command. A terminal prompt or open editor tab can help, but the branch and diff checks are the evidence used here. The example never depends on a machine-specific path.

The failed attempt to create another checkout of main demonstrates a boundary rather than a command to repeat. Read the refusal, identify the active checkout, and decide where the task belongs. Repeatedly adding overrides until a command succeeds would remove the very protection this case is meant to show.

Separate files and staging, shared history

Next, the primary file receives main draft, while the linked file receives topic draft. Only the linked directory stages its file. The script verifies that the primary staged diff is empty and the linked staged diff is not. It also reads the two working files, showing that the later edit in one directory did not replace the other’s text.

These observations establish separation of the checked-out files and staging in this case. They do not establish isolation of every repository setting or operation. For example, the primary repository can inspect the topic commit after it is created in the linked directory. The history and branch references are part of the same repository, which is why that inspection can work without a network transfer.

Treat this arrangement as two workspaces for related history. It helps when switching the first directory would interrupt an unfinished task. It does not replace a backup, a separately controlled repository or a team agreement about shared branches. Keep those purposes distinct when deciding whether an additional directory solves the actual problem.

Remove only after deciding what to keep

The script tries to remove the linked directory while its edit is staged. Git refuses. The failure is expected, and the example checks that it happened before proceeding. The refusal gives you a chance to decide what should happen to the work rather than treating directory cleanup as permission to discard it.

For this example, the decision is to commit the topic edit. That is appropriate only because it is fictional, intentional content prepared for this demonstration. A real unfinished change may require further review, a different branch or another preservation step. The guide does not prescribe committing arbitrary work merely to make a removal command pass.

Once the linked worktree is clean, the script removes it without force. It checks that the directory has gone and that the topic branch still points to the recorded commit. Removing a worktree and deleting a branch are different operations. The result lets the directory disappear while the committed task remains named in the shared repository.

Understand the newer branch-cleanup option

Git 2.56.0’s merged-branch cleanup option concerns local branch references whose configured upstream and reachability satisfy its rules². It is not a replacement for removing a linked working directory. Its documented exclusions include branches checked out in worktrees. That reinforces the need to distinguish the workspace from the branch it currently uses.

This page does not turn that option into a broad cleanup recipe. The example proves directory removal and branch retention, and the branch-recovery guide separately inspects a retained commit before giving it a new branch name. Choosing what to delete is a different decision from knowing where a second task should run.

Keep the handoff small

When returning to the first task, inspect its status and both relevant diffs before continuing. Its unfinished text remained in place in this example, but another command or application could have changed it meanwhile. Identify the current branch, the content intended for the next commit and anything still only in the working file. That gives the next task a defined starting point.

Not covered on this page

• Moving worktrees between devices or repairing moved metadata.
• Submodules, sparse checkouts or concurrent changes to shared settings.
• Force-removing a directory with work that has not been preserved.
• Remote collaboration or backup guarantees.