How to use `git worktree list` to see all your linked branches and folders
If you've started using Git Worktrees to juggle multiple branches at once, your file system can quickly become a bit of a maze. You might forget which folder is tracking which feature, or worse, why Git won't let you delete a branch because it's "in use" somewhere you can't find.
git worktree list is your GPS. It tells you exactly how your main repository is linked to various folders on your machine.
๐บ๏ธ Mapping Your Workspaceโ
The list command is the primary way to audit your linked working trees. It provides a high-level view of every active directory associated with your .git history.
๐ Basic Usageโ
Simply run:
git worktree list
๐ Reading the Outputโ
When you run the command, you'll see lines that look like this:
/Users/dev/project a1b2c3d [main]
/Users/dev/project-fix e5f6g7h [hotfix-v1]
- The Path: The absolute location of the worktree folder on your hard drive.
- The Commit Hash: The specific commit that is currently checked out in that folder.
- The Branch: The name of the branch inside the brackets. If it's a "detached HEAD," it will show the hash again or the specific tag.
๐ ๏ธ Advanced Listing (Flags)โ
Sometimes the default output isn't enough, especially if you are writing a script or need deep technical details.
1. The "Machine Readable" Modeโ
If you are building a tool or a bash alias, use --porcelain. It breaks the data into individual lines that are much easier to parse with grep or awk.
git worktree list --porcelain
Output:
worktree /Users/dev/project
HEAD a1b2c3d...
branch refs/heads/main
2. The Verbose Modeโ
Adding -v (verbose) will show you if the worktree is currently "locked." A locked worktree prevents it from being pruned or moved-useful for when you're working on a network drive or a portable disk.
git worktree list -v
๐ก Why You Actually Use This (Practical Scenarios)โ
Scenario A: Finding the "Stolen" Branchโ
You try to run git branch -D feature-x and Git screams: fatal: cannot delete branch 'feature-x' used by worktree at....
The Fix: Run git worktree list. Find the path associated with feature-x. You now know exactly which folder you need to cd into or git worktree remove.
Scenario B: Mass Cleanupโ
If you have five worktrees and you can't remember which ones you finished, the list lets you quickly see which branches are still active so you can prune the dead weight.
# See them
git worktree list
# Remove the ones you're done with
git worktree remove ../old-feature-folder
๐ Quick Flag Referenceโ
| Flag | Purpose | Best Used For... |
|---|---|---|
| (None) | Standard summary | Quick manual check. |
--porcelain | Key-value pairs | Scripting and automation. |
-v / --verbose | Shows "locked" status | Troubleshooting "un-removable" folders. |
๐ก๏ธ Pro-Tip: The "Stale" Worktreeโ
If git worktree list shows a folder that you already deleted using your computer's File Explorer or Trash, the list will still show it as active. This is because the internal .git index hasn't been updated.
To sync the list with reality, run:
git worktree prune
This will "clean" the list and remove any entries that no longer exist on your hard drive.
๐ Sources & Technical Refsโ
- [1.1] Git Documentation: git-worktree(1) Manual Page - Official list of arguments and flags.
- [2.1] Pro Git Book: Git Branching - Worktrees - A conceptual guide to managing multiple trees.
