git rm

git rm does more than delete a file. It removes the tracked path and stages that deletion for the next commit.

Common patterns

git rm app/old-file.ts
git rm -r legacy-folder
git rm --cached .env.local

Typical scenarios

• delete a tracked file and commit that deletion
• stop tracking a file while keeping it locally with --cached
• remove whole tracked directories with -r

Why it differs from plain rm

You can delete a file with your shell and later stage the deletion another way. git rm simply bundles the file removal and staging step together.

Practical caution

Once committed and shared, the deletion becomes part of project history, so use it deliberately for tracked paths.

What problem this command solves in a workflow

git rm removes tracked files and stages that deletion in one step. It bundles the filesystem removal and index update together, making it easier to separate the act of deleting a file from the commit that records that deletion in history.

Typical use cases

• Delete a tracked file and stage the removal for the next commit with git rm <file>.
• Stop tracking a file while keeping it on disk using git rm --cached <file> — common when adding files to .gitignore after they were already committed.
• Remove entire tracked directories recursively with git rm -r <directory>.

Diagram view

Input

Tracked file or directoryIndex state

→git rm

Output

File removed from diskDeletion staged in indexClean working tree

Once the deletion is committed and pushed, the file is removed from project history — use --cached to keep the local file.

Special cases and boundaries

• git rm only removes tracked files; untracked files are ignored and must be handled with git clean or shell rm.
• Using --cached removes the file from the index but keeps it in the working tree — useful when you realize a file should have been gitignored.
• The -f flag is required when the file has uncommitted changes that differ from HEAD, to confirm you really want to discard them.
• Once the deletion is committed and shared, recovering the file requires digging through commit history — git rm itself does not destroy data, but the commit that records the removal changes the project's visible state.