Git Worktree Repair After Moving a Directory

To repair a moved Git worktree directory, run git worktree repair from a worktree Git can still access. If you moved only the agent worktree, run it from the main repository and pass the agent worktree’s new path. If you moved only the main repository, run it from the main repository’s new location. If you moved both, run it from the relocated main repository and pass every moved linked worktree’s new path. Git’s repair command updates worktree administrative files when their recorded paths have become outdated.

The commands below use /projects/app for a main repository and /projects/agents/task-a for one agent worktree as examples. Replace them with your actual paths; a path passed to repair must name the worktree at its new location.

Why a directory move breaks the link

A linked worktree is more than a second checkout. Its top-level .git is a file that points to a private administrative directory under the main repository’s Git directory. That private directory also records a path back to the linked worktree. Moving either directory outside Git can leave one direction of that link pointing at an old location.

The failure can look different depending on which directory moved. A command inside the linked worktree may be unable to find its Git directory after the main repository moves. Conversely, the main repository may still work while git worktree list shows the linked worktree at its old path, potentially marked prunable. Treat that listing as a clue to investigate, especially when an agent may have edits in the moved directory.

Before repairing anything, identify which directories still exist and where they are now. Check the linked directory for its .git file, and confirm that the main repository you intend to use is the one that originally owned it. If the path in the listing is stale, locate the actual directory before running a cleanup command. For background on the shared repository and separate working directories, see how Git worktrees are organized.

Case 1: Only the agent worktree moved

Suppose /projects/agents/task-a was moved to /archive/agents/task-a, while /projects/app stayed in place. Run the repair from the main repository and name the new linked path:

cd /projects/app
git worktree repair /archive/agents/task-a
git worktree list --verbose

The path argument tells Git where to find the linked worktree now. Use the directory containing that worktree’s .git file, not a source subdirectory inside it. git worktree list --verbose then gives you the recorded paths and any locked or prunable explanation. The moved entry should identify the new location.

Git also supports running git worktree repair inside the recently moved linked worktree. Running from the main repository with an explicit path is useful when you have already confirmed that the main repository still works, or when you need to repair several moved worktrees together. For example:

cd /projects/app
git worktree repair /archive/agents/task-a /archive/agents/task-b
git worktree list --verbose

Pass each new worktree path as its own argument. Do not substitute the old paths shown by a stale listing; those paths are precisely what the repair needs to replace.

Case 2: Only the main repository moved

Suppose the main repository moved from /projects/app to /archive/app, while the agent worktree remained at /projects/agents/task-a. Run repair in the relocated main repository:

cd /archive/app
git worktree repair
git worktree list --verbose

In this case, the main repository still contains the worktree administrative directories, but the linked worktree’s .git file may point to their former location. Running repair from the main repository reconnects its linked worktrees to the repository’s new path. Check the linked worktree itself afterward; a successful listing from the main repository alone is not the whole verification.

Case 3: The main repository and agent worktrees moved

When both sides changed location, give repair the new location of every linked worktree you need to reconnect. For example, if the main repository is now /archive/app and two agent worktrees are now under /archive/agents:

cd /archive/app
git worktree repair /archive/agents/task-a /archive/agents/task-b
git worktree list --verbose

This is the case in which an argument-free repair is easiest to misapply. Git needs the new linked paths to update its records in both directions. If an agent worktree was not moved, leave its path out of the argument list and verify it along with the moved ones.

If you copied directories rather than moving them, first decide which copies you intend to keep. The repair command accepts moved or copied paths, but a list of old and new directories is a poor place to guess which working copy contains an agent’s latest edits. Inspect the files at each location and choose the intended paths before running the command.

Verify the worktree and its changes

After repair, inspect the relationship from the main repository and from each linked directory. Git’s rev-parse options report the worktree root and common Git directory, so they help distinguish a repaired link from a directory that merely has the expected name. For Cases 1 and 3, enter /archive/agents/task-a as shown below. For Case 2, enter /projects/agents/task-a instead; that worktree did not move.

cd /archive/agents/task-a
git rev-parse --show-toplevel
git rev-parse --git-common-dir
git worktree list --verbose

The first command should name the agent worktree you entered. The common Git directory should resolve to the main repository’s Git directory at its current location. The worktree listing should show the intended locations for the main and linked worktrees. If a path is still stale, check which directory moved and rerun the corresponding repair command with its actual new path.

Then check the agent’s local work from the same case-specific directory. git status --short --branch shows branch information and concise file status:

cd /archive/agents/task-a
git status --short --branch

For Case 2, replace that cd path with /projects/agents/task-a. Confirm that the branch and modified or untracked files are the ones you expect. A successful repair reconnects Git’s administrative paths; it does not decide which agent changes to keep or review their content. Repeat this check in each moved worktree before resuming an agent session. If the worktree is accessible but its changes look wrong, investigate the directory and branch you selected rather than treating another repair run as a file recovery step.

Avoid turning a move into a cleanup

git worktree prune removes administrative information for worktrees whose working directories are missing. A manually moved worktree can look missing at its old recorded path, so repair the link before pruning. If you are assessing genuinely stale entries later, git worktree prune --dry-run reports what pruning would remove without removing it. The related guide to cleaning up stale agent worktrees covers the separate decision to retire a worktree.

For a planned move of a linked worktree, git worktree move <worktree> <new-path> lets Git perform the move and update its link. That command does not move the main worktree, and Git does not support using it to move a linked worktree containing submodules. If you must move the main repository manually, use repair afterward. A worktree on an intermittently mounted drive can be locked with git worktree lock --reason "portable drive" <worktree> to protect its administrative entry from pruning; a lock also restricts moving or deleting the worktree until it is unlocked.

For layouts that are routinely relocated as a unit, Git also offers worktree.useRelativePaths=true and the --relative-paths option when linking or repairing worktrees. Relative links can suit a main repository and linked directories whose positions stay the same relative to one another. This setting enables the extensions.relativeWorktrees repository extension, which is incompatible with older Git versions, so check the Git versions used by everyone who opens the repository before changing the format. It does not remove the need to repair paths when the relative layout itself changes.

Where Parallel Code fits

Parallel Code is our free, open-source desktop app for macOS and Linux. It runs AI coding agents in parallel, each isolated in its own Git worktree, and provides a diff-first review surface. When a worktree directory is moved outside Git, use Git’s repair command to reconnect it before continuing work in that directory.

Frequently asked questions

Can I run git worktree repair from the moved agent worktree?

Yes. Git supports running it inside a recently moved linked worktree. If the main repository is still accessible, running from there with the linked worktree’s new path also makes the target explicit.

What if I moved the main repository and several agent worktrees?

Run git worktree repair from the main repository’s new location and pass the new path of each moved linked worktree. Then check git worktree list --verbose and git status --short --branch inside each linked directory.

Should I prune a worktree marked prunable after a move?

First locate the directory and determine whether you still need its files. If it was moved, repair it at its new path; use git worktree prune --dry-run only when you are evaluating entries you may actually discard.

Does repair restore deleted agent files?

No. git worktree repair repairs worktree administrative links where possible; it is not a command for recreating a deleted working directory. Check the actual directory and its file status before resuming the agent.