Fix: Worktree “Not a Git Repository”

You cd into a git worktree directory and run a Git command, but Git responds with:

$ git status
fatal: not a git repository (or any parent up to mount point /home)
Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).

This error means Git cannot find the repository metadata for this worktree. Here is why it happens and how to fix it.

Why This Happens

Unlike the main worktree (which has a full .git directory), linked worktrees have a .git file— a plain text file that contains a single line pointing back to the main repository’s .git directory:

$ cat /home/user/project-feature/.git
gitdir: /home/user/project/.git/worktrees/project-feature

The “not a git repository” error appears when this link is broken. Common causes:

• The main worktree was moved or renamed. If you move the main repository from /home/user/project to /home/user/repos/project, the path in the linked worktree’s .git file is now wrong.
• The main worktree was deleted.If the main repository’s .git directory no longer exists, all linked worktrees become broken.
• The .git file is corrupted or missing. If the .git file in the worktree was accidentally deleted or modified, Git cannot find the repository.
• The worktree metadata was pruned. If someone ran git worktree prunewhile this worktree’s directory was temporarily inaccessible (e.g., on an unmounted drive), Git removed its metadata from .git/worktrees/.

How to Fix It

Fix 1: Repair the .git File (Main Worktree Was Moved)

If you moved the main repository, update the path in the linked worktree’s .git file:

# Check the current (broken) path
cat /home/user/project-feature/.git
# gitdir: /home/user/project/.git/worktrees/project-feature  <-- old path

# Fix it by writing the correct path
echo "gitdir: /home/user/repos/project/.git/worktrees/project-feature" > /home/user/project-feature/.git

# Also update the reverse link in the main repo
echo "/home/user/project-feature" > /home/user/repos/project/.git/worktrees/project-feature/gitdir

Fix 2: Use git worktree repair (Git 2.30+)

Git 2.30 introduced git worktree repair, which automatically fixes broken links between the main repository and its worktrees:

# Run from the main worktree to repair all linked worktrees
cd /home/user/repos/project
git worktree repair

# Or specify specific worktree paths to repair
git worktree repair /home/user/project-feature /home/user/project-hotfix

You can also run git worktree repair from inside a linked worktree to fix its link back to the main repo.

Fix 3: Recreate the Worktree

If the worktree metadata is gone and repair does not work, the simplest fix is to recreate it. Save any uncommitted changes first:

# Copy any uncommitted work out of the broken worktree
cp -r /home/user/project-feature/src/my-changes /tmp/my-changes-backup

# Remove the broken worktree directory
rm -rf /home/user/project-feature

# Clean up stale references
cd /home/user/repos/project
git worktree prune

# Recreate the worktree
git worktree add /home/user/project-feature feature-branch

# Restore your uncommitted changes
cp -r /tmp/my-changes-backup /home/user/project-feature/src/my-changes

Prevention Tips

• Do not move the main worktree after creating linked worktrees. If you must move it, run git worktree repair immediately afterwards.
• Lock worktrees on removable drives. Use git worktree lock <path> to prevent git worktree prune from removing metadata when the drive is disconnected.
• Use git worktree remove instead of rm -rf to properly clean up worktree metadata when you are done with a worktree.
• Keep worktrees near the main repo. Using relative paths (e.g., ../project-feature) makes moves less likely to break links.