Git Worktree Command•Step #4

git worktree move: Move a Git Worktree Safely

The git worktree move command relocates a linked worktree directory to a new path while automatically updating the bi-directional Git administrative pointers.

Basic Syntax

Terminal

# Move worktree and update internal pointers

$git worktree move <worktree> <new-path>

For example, to organize a loose worktree into a structured features/ folder:

Terminal

# Relocate directory to new destination

$git worktree move project-feature-auth ../features/auth

Before move:

projects/
├── project/
└── project-feature-auth/

After git worktree move:

projects/
├── project/
└── features/
    └── auth/

Why you should not use standard 'mv' or Finder

Linked worktrees rely on two synchronized pointers:

The .git text file inside the worktree folder points to the primary repo's .git/worktrees/<id>.
The gitdir file inside .git/worktrees/<id> points back to the worktree's physical directory.

If you move the folder manually with mv or your desktop file explorer, pointer #2 is severed. Git will lose track of the worktree and mark it as missing.

Accidentally moved a folder manually?

Don't panic! You can easily re-link the severed pointers by running git worktree repair.

Move Rules & Restrictions

Primary worktree cannot be moved with this command: git worktree move only works on linked worktrees.
Locked worktrees: A locked worktree cannot be moved unless you pass --force or unlock it first via git worktree unlock.
Destination must not exist: The new path target must not already exist as a folder or file.

WorktreeWise

Move Worktree

Try Free

WorktreeWise allows you to rename or relocate any worktree instantly from the UI without typing terminal paths. All underlying Git metadata links and IDE configurations are updated automatically.

Relocate a Git worktree folder in WorktreeWise

Related commands

To prevent automatic cleanup from removing a worktree located on an external drive or pending reorganization, use git worktree lock. If a move has severed administrative links, run git worktree repair.