git worktree lock: Prevent Accidental Pruning

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):

# Create a worktree on a USB drive
git worktree add /Volumes/ExternalSSD/acme-hotfix hotfix/checkout-crash

# Lock it to prevent pruning when the drive is unmounted
git worktree lock /Volumes/ExternalSSD/acme-hotfix

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

# Create and lock in one step
git worktree add --lock /Volumes/ExternalSSD/acme-hotfix hotfix/checkout-crash

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:

git worktree lock --reason "On external USB SSD, may not always be mounted" \
  /Volumes/ExternalSSD/acme-hotfix

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

$ git worktree list -v
/home/you/code/acme              d1e2f3a [feature/payments]
/Volumes/ExternalSSD/acme-hotfix      7a8b9c0 [hotfix/checkout-crash] 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:

git worktree unlock /Volumes/ExternalSSD/acme-hotfix

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:

# Option 1: unlock then remove
git worktree unlock /Volumes/ExternalSSD/acme-hotfix
git worktree remove /Volumes/ExternalSSD/acme-hotfix

# Option 2: force remove (bypasses the lock)
git worktree remove -ff /Volumes/ExternalSSD/acme-hotfix

Checking Lock Status

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

# Standard list output shows "locked" annotation
$ git worktree list
/home/you/code/acme              d1e2f3a [feature/payments]
/Volumes/ExternalSSD/acme-hotfix      7a8b9c0 [hotfix/checkout-crash] locked

# Verbose output includes the lock reason
$ git worktree list -v
/home/you/code/acme              d1e2f3a [feature/payments]
/Volumes/ExternalSSD/acme-hotfix      7a8b9c0 [hotfix/checkout-crash] locked (reason: On external USB SSD)

# Porcelain output includes a "locked" line
$ git worktree list --porcelain
worktree /home/you/code/acme
HEAD d1e2f3ad1e2f3ad1e2f3ad1e2f3ad1e2f3a4b5c6d
branch refs/heads/feature/payments

worktree /Volumes/ExternalSSD/acme-hotfix
HEAD 7a8b9c07a8b9c07a8b9c07a8b9c07a8b9c0d1e2f3
branch refs/heads/hotfix/checkout-crash
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.