Git Worktree Lifecycle: Lock, Move, Repair, Prune, and Remove
Safely manage the lifecycle of linked Git worktrees: lock and unlock them, move them, repair manually moved worktrees, remove clean or forced worktrees, and prune stale administrative records.
Advanced
A worktree lifecycle has repository-side administrative state
A linked worktree is more than its directory on disk. Git keeps administrative information in the repository so the main worktree and linked worktrees can stay connected. Removing or moving a directory outside Git can leave that administrative information stale. The lifecycle commands exist to manage that relationship deliberately rather than treating the filesystem directory as the whole worktree.
git worktree list
git worktree list --verboseQuick check
Why can a deleted worktree directory leave something for Git to clean up later?
A repository has a linked worktree.The repository retains worktree administrative state even though the working directory is separate.Lock a worktree when its path may disappear temporarily
`git worktree lock <worktree>` marks a worktree as locked so its administrative information is protected from automatic pruning. The official documentation gives portable devices and intermittently mounted network shares as examples. A lock also prevents normal move and remove operations. Use `--reason` to record why the worktree is locked.
git worktree lock --reason "portable test worktree" ../feature-tree
git worktree list --verboseQuick check
What does locking a linked worktree protect against?
The worktree may be temporarily unavailable.The worktree is marked locked and its reason can be inspected with verbose listing.Unlock before normal lifecycle operations
`git worktree unlock <worktree>` removes the lock so the worktree can again be pruned, moved, or removed under the normal safety rules. Unlocking does not move the worktree or delete any files.
git worktree unlock ../feature-tree
git worktree list --verboseQuick check
What does `git worktree unlock` change?
A worktree is locked.The worktree is unlocked and can be managed normally.Move a linked worktree through Git
`git worktree move <worktree> <new-path>` moves a linked worktree while updating Git's administrative connection. The main worktree cannot be moved by this command, and the official documentation also excludes linked worktrees containing submodules from this operation.
git worktree move ../feature-tree ../moved-tree
git worktree listQuick check
Why prefer `git worktree move` over manually moving a linked worktree directory?
The linked worktree exists at its old path.The linked worktree is registered at its new path.Repair a worktree that was moved outside Git
If a linked worktree is moved manually, its administrative connection can point at the old location. `git worktree repair <path>` reestablishes that connection when possible. Repair is for fixing the metadata relationship after an external filesystem change; it is not a general-purpose relocation command.
mv ../repair-tree ../manually-moved-tree
git worktree list
git worktree repair ../manually-moved-tree
git worktree listQuick check
When is `git worktree repair` the appropriate lifecycle operation?
The worktree directory was moved manually and Git reports stale worktree metadata.repair reconnects the moved worktree to the repository's administrative state.Remove a clean worktree deliberately
`git worktree remove <worktree>` removes a linked worktree when it is clean: the official safety rule rejects worktrees with untracked files or modifications in tracked files unless force is requested. The main worktree cannot be removed with this command. Removing a worktree removes the linked working directory and its associated administrative entry; it does not delete the branch name that was checked out there.
git worktree remove ../manually-moved-tree
git worktree listQuick check
What is the normal safety condition for `git worktree remove`?
The linked worktree has no untracked files and no tracked-file modifications.The linked worktree is removed under the normal safety rule.Force removal is a deliberate destructive exception
`git worktree remove --force <worktree>` overrides the clean-worktree safety check. This is appropriate only when the learner has deliberately decided that uncommitted work in the disposable or otherwise expendable worktree should be discarded. In a teaching environment, demonstrate this only in a disposable repository and inspect the worktree state before and after the operation.
git worktree remove --force ../dirty-treeQuick check
Why should `git worktree remove --force` be demonstrated only with deliberate safety checks?
A disposable linked worktree contains an uncommitted change.The linked worktree is removed despite being unclean.Prune stale worktree administrative records
If a linked worktree directory disappears without `git worktree remove`, Git can retain stale administrative information. `git worktree prune` removes administrative information for worktrees whose working trees are missing. Use `--dry-run` (`-n`) to inspect what would be removed before making the cleanup, and `-v` to report removals.
git worktree prune -n -v
git worktree prune -v
git worktree listQuick check
What is the purpose of `git worktree prune -n`?
A worktree directory was manually removed and its administrative record is stale.The dry run identifies the stale record; the subsequent prune removes it.Practice what you learned
Use the dedicated Git code-completion exercise for this lesson.
Official-source boundary
This lesson uses only the official Git project documentation for `git worktree`. The current official manual is the Git 2.56.0 documentation baseline; its change history records no 2.56.0 change after the 2.54.0 update. Local command verification was performed with Git 2.47.3. The lesson therefore distinguishes official specification from locally executed evidence and does not claim that the local executable is Git 2.56.0.
Thanks for your feedback.
Mark this learning resource complete to track your learning progress.