git worktree lock: Prevent Accidental Pruning

The git worktree lock command marks a worktree as locked, preventing it from being automatically pruned by git worktree prune. This is essential for worktrees on removable drives, network shares, or any location that may be temporarily unavailable.

Why Lock a Worktree?

When git worktree prune runs, it removes administrative data for any worktree whose directory no longer exists on disk. This is normally helpful — it cleans up after manually deleted worktrees. But in some scenarios, the directory is intentionally absent:

Removable drives— a USB stick or external SSD containing the worktree is unplugged.
Network shares— an NFS or SMB mount is temporarily disconnected.
Encrypted volumes— a VeraCrypt or LUKS container is not currently mounted.
Cloud-synced folders— a Dropbox or OneDrive folder is set to online-only and the files are not locally available.

Without locking, running git worktree prune (or creating a new worktree, which triggers an automatic prune) would remove the administrative entry, and the branch would no longer be recognized as checked out. Locking prevents this.

Basic Usage

git worktree lock <worktree-path>

Lock a worktree by specifying its path. The worktree must already exist as a linked worktree (visible in git worktree list):

Lock a worktree on a removable drive

# Create a worktree on a USB drive
git worktree add /media/usb/project-release release/v2.0

# Lock it to prevent pruning when the drive is unmounted
git worktree lock /media/usb/project-release

You can also lock a worktree at creation time using the --lock flag on git worktree add:

Create and lock simultaneously

# Create and lock in one step
git worktree add --lock /media/usb/project-release release/v2.0

Adding a Lock Reason (--reason)

The --reason flag lets you attach a human-readable explanation to the lock. This is helpful when you or a teammate later encounters the locked worktree and needs to understand why it should not be pruned:

Lock with a reason

git worktree lock --reason "On external USB SSD, may not always be mounted" \
  /media/usb/project-release

The reason is visible in git worktree list -v output and when running prune with --verbose:

Reason shown in verbose list output

$ git worktree list -v
/home/user/project              abc1234 [main]
/media/usb/project-release      def5678 [release/v2.0] locked (reason: On external USB SSD, may not always be mounted)

Unlocking (git worktree unlock)

To remove the lock from a worktree, use git worktree unlock:

Unlock a worktree

git worktree unlock /media/usb/project-release

Once unlocked, the worktree is subject to normal pruning rules again. If the directory does not exist on disk, the next prune operation will remove its administrative data.

You must unlock a worktree before you can remove it with git worktree remove, or use double force:

Removing a locked worktree

# Option 1: unlock then remove
git worktree unlock /media/usb/project-release
git worktree remove /media/usb/project-release

# Option 2: force remove (bypasses the lock)
git worktree remove -ff /media/usb/project-release

Checking Lock Status

There are several ways to check whether a worktree is locked:

Different ways to check lock status

# Standard list output shows "locked" annotation
$ git worktree list
/home/user/project              abc1234 [main]
/media/usb/project-release      def5678 [release/v2.0] locked

# Verbose output includes the lock reason
$ git worktree list -v
/home/user/project              abc1234 [main]
/media/usb/project-release      def5678 [release/v2.0] locked (reason: On external USB SSD)

# Porcelain output includes a "locked" line
$ git worktree list --porcelain
worktree /home/user/project
HEAD abc1234abc1234abc1234abc1234abc1234abc1234
branch refs/heads/main

worktree /media/usb/project-release
HEAD def5678def5678def5678def5678def5678def5678
branch refs/heads/release/v2.0
locked On external USB SSD

In porcelain mode, the locked line appears after the branch line. If a reason was provided, it follows the word "locked" on the same line. If no reason was given, the line simply reads locked.

Best Practices

Always lock worktrees on removable media. Make this part of your workflow whenever you create a worktree on a USB drive, external SSD, or network share.
Always provide a reason. A descriptive --reason helps future-you (or teammates) understand why the worktree is locked.
Unlock before cleanup. When you are done with a worktree, unlock it before running git worktree remove. This avoids the need for double force.
Audit locks periodically. Run git worktree list -v to review locked worktrees and remove locks that are no longer needed.