Git Course 0%

git rm

Beginner Git CLI Careful ≈ 4 min

Summary: git rm <file> deletes a tracked file from disk and stages the deletion. git rm --cached <file> removes it from tracking only, leaving the file where it is — the fix for "committed but should have been ignored".

Careful — the plain form deletes the file from your disk (recoverable from the last commit, but any uncommitted edits in it are lost). --cached touches nothing on disk.

What it does

Stages the removal of the path from the next commit; without --cached, also deletes the working-tree file. Earlier commits still contain the file, so history is not affected.

Why it exists

Deleting in the editor leaves Git with a "deleted, not staged" entry to stage separately; git rm does both. And --cached is the only clean way to untrack a file that stays on disk.

When to use it

  • Removing a file or folder from the project.
  • Untracking a generated file or a secret that was committed by mistake (--cached, plus a .gitignore entry, plus rotating the secret).

When not to use it

  • On a file with uncommitted edits you want: Git refuses unless forced; commit or stash first.
  • To delete an untracked file: just delete it (Git never knew it).
  • To remove a file from past history: that needs lesson 8.7.

Syntax

Form Meaning
git rm <file> Delete from disk and stage the deletion
git rm --cached <file> Stop tracking; keep the file on disk
git rm -r <folder> Recursively, for a folder
git rm -f <file> Force, even with uncommitted edits (loses them)

Examples

Terminal
$ git rm docs/scratch.md
rm 'docs/scratch.md'
Terminal
$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	deleted:    docs/scratch.md

A file already deleted in the file manager:

Terminal
$ git status -s
 D docs/tmp.md
Terminal
$ git rm docs/tmp.md
rm 'docs/tmp.md'
Terminal
$ git status -s
D  docs/tmp.md

Untrack without deleting (after adding todo.txt to .gitignore):

Terminal
$ git rm --cached todo.txt
rm 'todo.txt'
Terminal
$ git status -s
 M .gitignore
D  todo.txt

ls todo.txt still finds the file; after the commit, Git ignores it.

Expected result

git status shows deleted: under "Changes to be committed" (D in the first column); the file is gone from disk unless --cached. Commit to record the removal.

Common mistakes

  • git rm on a modified file. error: the following file has local modifications. Decide: commit the edits first, or -f to discard them.
  • Expecting --cached to delete. It does not; that is its purpose.
  • Thinking the file is gone from history. Every earlier commit still has it: git show HEAD~1:<path> prints it. For secrets, rotate them.
  • Forgetting the .gitignore entry after --cached: the file reappears as untracked and someone adds it again.

How to undo or recover

  • Before committing: git restore --staged <file> (unstage the deletion) then git restore <file> (bring the file back from the last commit).
  • After committing: git restore --source=HEAD~1 <file> and commit, or git revert the commit (lesson 12.5).

In VS Code

Delete in the Explorer, then stage the D entry in Source Control; Discard Changes on a deleted file restores it.

In IntelliJ IDEA

Delete in the Project view; IntelliJ asks whether to remove the file from Git as well.

git mv renames · git restore brings a file back · git add stages a deletion made by hand · git clean deletes untracked files.

Lessons that use this command

Create, rename, move, delete · .gitignore · File states.

Key terms

Tracked Staged Ignored

Related