# git worktree remove: Usage, Options & Common CI Errors

> git worktree remove deletes a linked working tree and its admin files. Reference for --force, prune, and the dirty-tree and locked-worktree errors in CI.

Source: https://latchkey.dev/learn/command-reference/git-worktree-remove  
Updated: 2026-06-25

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

```Terminal
git worktree remove ../feature
git worktree remove --force ../feature   # even if dirty
git worktree prune                       # clean up stale entries
git worktree prune -n                    # dry run
```

## Options

| 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.

```.github/workflows/ci.yml
- 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git worktree remove: Usage, Options & Common CI Errors?

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt