git rm: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

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

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

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.

- 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

Frequently asked questions

Related guides

References

• GitHub Actions documentation