Git Worktree Command•Step #8

git worktree repair: Fix Broken Git Worktree Links

The git worktree repair command re-establishes bi-directional administrative links between the main repository and worktrees after directories or repositories have been moved or renamed manually.

Basic Syntax

Terminal

# Reconcile metadata pointers for all or specific worktrees

$git worktree repair [<path>...]

Running git worktree repair without arguments inside the main repository checks all registered worktrees and fixes their administrative pointers.

How git worktree repair Restores Broken Administrative Links

❌ Broken: Directory moved manually via Finder / Explorer.git pointer still references old path

↓ Running: git worktree repair

✓ Restored: Bi-directional link between repository and worktree repairedBoth pointers updated to new location

Common Scenarios Where Repair is Essential

Scenario A: You manually moved a linked worktree folder

If you used mv ../old-path ../new-path instead of git worktree move, simply provide the new path to repair:

Terminal

# Repairs the connection to the moved worktree

$git worktree repair ../new-path

Output Example

repair: updated worktree at '/path/to/new-path'

Scenario B: The main parent repository folder was renamed or relocated

If you renamed your main project folder (e.g. from ~/projects/app to ~/projects/my-new-app), all linked worktrees will lose their reference to the primary .git folder. Navigate into any worktree or the main directory and run:

Terminal

# Scans and heals all linked pointer references

$git worktree repair

How git worktree repair works under the hood

Every linked worktree requires two reciprocal links:

Worktree → Repository: The .git file in the worktree directory contains gitdir: /path/to/main/.git/worktrees/<name>.
Repository → Worktree: The gitdir file inside .git/worktrees/<name>/ contains /path/to/worktree/.git.

git worktree repair reads the available pointer in whichever directory is valid and writes the matching updated pointer into the other side, instantly healing severed links.

WorktreeWise

Repair Damaged Worktrees

Try Free

WorktreeWise identifies damaged worktrees directly in the sidebar, disables unsafe actions, and provides a dedicated Repair action to reconnect a moved directory without deleting its files or branch.

Repair action for a damaged Git worktree in WorktreeWise

Related commands

To move worktrees in the future without breaking administrative pointers, use git worktree move. If a worktree directory is permanently gone and no longer needed, use git worktree prune.