git worktree remove: Usage, Options & Common CI Errors
git worktree remove cleanly deletes a linked working tree and its bookkeeping.
After a parallel build finishes, remove tears down the extra worktree properly - unlike rm -rf, it also clears the repo-side metadata so listings stay accurate.
What it does
git worktree remove deletes the working directory of a linked tree and its administrative files under .git/worktrees, provided the tree is clean. It refuses to remove the main worktree.
Common usage
git worktree remove ../feature
git worktree remove --force ../feature # even if dirty
git worktree prune # clean up stale entries
git worktree prune -n # dry runOptions
| Flag / subcommand | What it does |
|---|---|
| <path> | Remove the worktree at path |
| -f / --force | Remove even with local changes (twice if locked) |
| prune | Drop metadata for already-deleted trees |
| prune -n | Show what prune would remove |
Common errors in CI
fatal: '<path>' contains modified or untracked files, use --force to delete it - the tree is dirty; pass --force when you are sure. A locked worktree needs --force twice. If you deleted the directory with rm instead, the entry lingers until git worktree prune.
Using this in CI
CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.
- uses: actions/checkout@v4
with:
fetch-depth: 0 # history, tags, and git describe all need this
- run: |
git rev-parse --is-shallow-repository # expect false
git rev-parse --abbrev-ref HEAD # prints HEAD when detached