# git rm: Usage, Options & Common CI Errors

> git rm removes files from the working tree and the index. Reference for --cached, -r, -f, and the "has staged changes" and pathspec errors in CI.

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

git rm deletes files and stages the removal in one step.

Use git rm to delete tracked files; --cached untracks a file while keeping it on disk.

## What it does

git rm removes files from both the working tree and the index, staging the deletion for the next commit. With --cached it removes only from the index, leaving the file in place.

## Common usage

```Terminal
git rm file.txt
git rm -r dir/                # recursive
git rm --cached secrets.env  # stop tracking, keep file
git rm -f file.txt           # force when modified/staged
```

## Options

| Flag | What it does |
| --- | --- |
| --cached | Remove from index only, keep on disk |
| -r | Recurse into directories |
| -f / --force | Override the up-to-date safety check |
| -n / --dry-run | Show what would be removed |

## Common errors in CI

error: the following file has staged content different from both the file and the HEAD / 'X' has changes staged in the index - git protects unsaved changes. Use -f to force, or git rm --cached to merely untrack (commonly after adding a path to .gitignore).

## 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 rm: Usage, Options & Common CI Errors?

Use git rm to delete tracked files; --cached untracks a file while keeping it on disk.

### What it does?

git rm removes files from both the working tree and the index, staging the deletion for the next commit. With --cached it removes only from the index, leaving the file in place.

### Common errors in CI?

error: the following file has staged content different from both the file and the HEAD / 'X' has changes staged in the index - git protects unsaved changes. Use -f to force, or git rm --cached to merely untrack (commonly after adding a path to .gitignore).

---

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