Git Worktree Commands Cheatsheet with Practical Examples

Mar 30, 2026

Cowrie

Dev @ Bswen

Purpose

This post provides a quick reference guide to all git worktree commands. I’ll show you real-world usage examples for each command.

Git worktree has 7 main commands: add, list, lock, move, remove, prune, repair. Each handles specific aspects of managing multiple working directories.

What is git worktree?

Git worktree lets you have multiple working directories attached to the same repository. You can work on different branches simultaneously without switching branches in your main directory.

1. git worktree add

The add command creates a new working directory linked to your repository.

Basic add with existing branch

Add existing branch to new worktree

git worktree add ../feat1 feat1

This creates a new directory feat1 at ../feat1 and checks out the existing feat1 branch.

Add with new branch

Create new branch in new worktree

git worktree add -b new-branch ../new-dir main

The -b flag creates a new branch new-branch based on main in the new worktree.

Add in detached HEAD mode

Add worktree in detached HEAD mode

git worktree add -d ../temp-work

The -d flag creates a worktree in detached HEAD state. Useful for quick experiments.

Add from a tag

Add worktree from specific tag

git worktree add ../release-v1 v1.0.0

You can checkout a specific tag or commit hash in a new worktree.

Why use worktree for branches?

Instead of stashing changes and switching branches, you can simply open a new terminal in your worktree directory. Each worktree has its own working directory, so you can work on multiple features at the same time.

2. git worktree list

The list command shows all worktrees associated with your repository.

List all worktrees

git worktree list

Example output:

/main/repo           9ec7370 [main]
/../feat1            d3bfa43 [feat1]
/../temp-work        a85d91a (detached)

Each line shows:

• The worktree path
• The current commit hash
• The branch name (or detached state)

3. git worktree lock

The lock command prevents a worktree from being pruned or deleted.

Lock a worktree with reason

git worktree lock ../feat1 --reason "Working on critical feature"

The --reason flag documents why the worktree is locked. This helps team members understand the lock status.

When to lock worktrees?

Lock worktrees when you have uncommitted work or when the worktree is shared with team members. This prevents accidental deletion.

4. git worktree unlock

The unlock command removes the lock from a worktree.

Unlock a worktree

git worktree unlock ../feat1

After unlocking, the worktree can be pruned or removed.

5. git worktree move

The move command relocates an existing worktree to a different path.

Move worktree to new location

git worktree move ../feat1 ../new-location

This moves the worktree from ../feat1 to ../new-location. Git updates all internal references automatically.

Moving worktrees

Make sure the destination path does not already exist. Also, close any IDEs or editors that have files open from the worktree before moving it.

6. git worktree remove

The remove command deletes a worktree.

Basic remove

Remove a worktree

git worktree remove ../feat1

This removes the worktree at ../feat1. The branch remains in the repository.

Force remove

Force remove worktree with uncommitted changes

git worktree remove -f ../feat1

The -f flag forces removal even when the worktree has uncommitted changes or is locked.

Removing worktrees

By default, remove requires a clean working directory. Use -f only when you’re certain you want to discard any uncommitted work.

7. git worktree prune

The prune command cleans up stale worktree references.

Basic prune

Prune stale worktree references

git worktree prune

This removes worktree administrative data for worktrees that were manually deleted.

Dry run prune

Show what would be pruned without actually pruning

git worktree prune -n

The -n or --dry-run flag shows what would be pruned without actually doing it.

When to use prune?

Use prune when you’ve manually deleted a worktree directory (using rm -rf or file explorer). Git still tracks the worktree reference, so prune cleans up these stale entries.

8. git worktree repair

The repair command fixes worktree administrative files.

Repair worktree references

git worktree repair

Use this after moving your main repository directory. It updates worktree paths and other administrative files.

Repair after repository move

If you move the main repository to a different location, worktrees may stop working. Run git worktree repair to fix the internal references.

Quick Reference Table

Here’s a summary of all git worktree commands:

Command	Description	Common Flags
add	Create new worktree	-b (new branch), -d (detached)
list	Show all worktrees	None
lock	Lock a worktree	--reason
unlock	Unlock a worktree	None
move	Move worktree to new path	None
remove	Delete a worktree	-f (force)
prune	Clean stale references	-n (dry run)
repair	Fix worktree references	None

Summary

In this post, I provided a quick reference guide for all git worktree commands with practical examples. The key commands are:

1. add - Create new working directories for different branches
2. list - View all worktrees and their status
3. lock/unlock - Protect worktrees from accidental deletion
4. move - Relocate worktrees to different paths
5. remove - Delete worktrees (clean directory required)
6. prune - Clean up after manually deleting worktree directories
7. repair - Fix references after moving the main repository

Git worktree helps you work on multiple branches simultaneously without the overhead of switching branches. It’s a powerful tool for developers who juggle multiple features or bug fixes.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

• 👨‍💻 Git Worktree Documentation
• 👨‍💻 Git Worktree Tutorial
• 👨‍💻 Multiple Working Directories with Git Worktree

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags:

• miscs

How to Use Git Worktree for Parallel Branch Development

Common Git Worktree Mistakes and How to Fix Them