git worktree move: Relocate a Worktree

Basic Syntax

git worktree move <worktree> <new-path>

The worktree argument is the current path to the linked worktree you want to move. The new-path is the destination directory. The destination must not already exist — Git will create it as part of the move.

# Move the hotfix worktree to a better-organized location
git worktree move ../acme-hotfix ../acme-wt/hotfix

After the move, the worktree continues to track the same branch and retains all uncommitted changes. The old directory is removed automatically.

When to Use Move

The most common reasons to move a worktree:

• Reorganizing your directory structure— you want to group worktrees under a common parent directory (e.g., ~/worktrees/project/) instead of having them scattered across your filesystem.
• Renaming a worktree directory— you chose a poor directory name initially and want a more descriptive one.
• Moving to a different disk or partition— you need more space or want the worktree on an SSD for faster builds.

Examples

Rename a worktree directory

# Rename from a generic name to something descriptive
git worktree move ../acme-hotfix ../acme-checkout-crash-fix

Move into an organized directory structure

# Create a parent directory for all worktrees
mkdir -p ~/code/acme-wt

# Move existing worktrees into the organized structure
git worktree move ../acme-hotfix ~/code/acme-wt/hotfix
git worktree move ../acme-review ~/code/acme-wt/review

# Verify the new layout
git worktree list

Move a locked worktree

Locked worktrees cannot be moved by default. You must unlock them first, move, then optionally re-lock:

# Unlock, move, then re-lock
git worktree unlock ../acme-hotfix
git worktree move ../acme-hotfix ../acme-wt/hotfix
git worktree lock ../acme-wt/hotfix --reason "On external SSD"

Alternatively, use --force --force to move a locked worktree without unlocking it first:

git worktree move --force --force ../acme-hotfix ../acme-wt/hotfix

Moving to External Drives

You can move a worktree to an external drive or USB stick. This is useful for working on different machines or keeping a backup copy:

# Move worktree to an external drive (macOS example)
git worktree move ../acme-review /Volumes/ExternalSSD/acme-wt/review

# Lock it so Git doesn't prune it when the drive is unmounted
git worktree lock /Volumes/ExternalSSD/acme-wt/review \
  --reason "Located on external SSD"

When the drive is not mounted, Git will see the worktree as missing. Without the lock, git worktree prune would remove the administrative data for it. Locking prevents this. See the git worktree lock tutorial for more details.

Limitations

There are a few restrictions to be aware of:

• The main worktree cannot be moved. The git worktree move command only works with linked (non-main) worktrees. To relocate the main worktree, you must move the entire repository directory.
• Linked worktrees with submodules cannot be moved. If the worktree contains submodules, git worktree move will refuse the operation.
• The destination must not exist. Git will not overwrite an existing directory. If the target path already exists, the command fails.
• Locked worktrees require double force or unlocking. As shown above, you need to either unlock the worktree first or use the --force --force flag.

# Trying to move the main worktree fails
$ git worktree move . ../acme-new
fatal: cannot move a bare repository or the main working tree

# Trying to move to an existing directory fails
$ git worktree move ../acme-hotfix ../acme-review
fatal: '../acme-review' already exists