Understanding git rm: Removing Files from Git Repositories

As a software project grows, some files eventually become unnecessary.

You may want to:

• Remove an old Java class.

• Delete an outdated image.

• Remove a configuration file.

• Delete temporary files.

• Stop tracking a file while keeping it on your computer.

Simply pressing the Delete key removes a file from your computer, but Git also needs to know that the file should be removed from version control.

This is where the git rm command becomes useful.

The git rm command removes files from both your Working Directory and Git's index (Staging Area) so that the deletion becomes part of your next commit.

In this article, you will learn:

• What git rm is

• Why it is needed

• How it differs from manually deleting files

• Removing tracked files

• Removing files only from Git

• Removing directories

• Using wildcards

• Common mistakes

• Best practices

By the end of this article, you will know how to safely remove files from a Git repository.

---

Why Can't We Just Delete Files?

Suppose your project contains:

StudentManagement
│
├── Main.java
├── Student.java
├── Database.java
└── README.md

You manually delete:

Student.java

Now run:

git status

Git displays:

Changes not staged for commit:

    deleted: Student.java

Git knows the file has disappeared, but the deletion has not yet been staged.

You still need to tell Git that this deletion should become part of the next commit.

---

What is git rm?

The git rm command removes a tracked file from:

• The Working Directory

• The Staging Area (Index)

After that, the removal is ready to be committed.

Basic syntax:

git rm <filename>

Example:

git rm Student.java

Git removes the file and stages the deletion immediately.

---

Understanding the Git Workflow

Before removal:

Working Directory
        │
        ▼
Staging Area
        │
        ▼
Repository

After running:

git rm Student.java

The file is:

• Removed from the Working Directory.

• Marked for deletion in the Staging Area.

The deletion becomes permanent in Git history only after a commit.

---

First Practical Example

Suppose your project contains:

Main.java

Student.java

Database.java

Run:

git rm Student.java

Git may display:

rm 'Student.java'

Now run:

git status

Output:

Changes to be committed:

    deleted: Student.java

The deletion is staged.

---

Completing the Removal

The file is not yet permanently removed from Git history.

Create a commit:

git commit -m "Remove Student.java"

Now the deletion becomes part of the repository history.

---

Manually Deleting vs git rm

Suppose you manually delete:

Student.java

Git status:

deleted: Student.java

You must still stage the deletion:

git add Student.java

or

git add -A

In contrast,

git rm Student.java

performs both steps at once:

• Deletes the file.

• Stages the deletion.

---

Visual Comparison

Manual Delete

Delete File
      │
      ▼
git status
      │
      ▼
git add
      │
      ▼
git commit

Using git rm

git rm
     │
     ▼
git commit

git rm saves one extra step.

---

Removing Multiple Files

Suppose your project contains:

Student.java

Teacher.java

Course.java

Run:

git rm Student.java Teacher.java

Git removes both files and stages their deletions.

---

Removing an Entire Directory

Suppose your project contains:

images/
    logo.png
    banner.png

To remove the entire directory, use:

git rm -r images

The option:

-r

means:

Recursive

Git removes every tracked file inside the directory.

---

Removing Files Using Wildcards

Suppose your repository contains:

Test1.java

Test2.java

Test3.java

Remove every Java file beginning with Test:

git rm Test*.java

Git removes all matching files.

Be careful when using wildcards.

Always verify which files match before running the command.

---

What Happens If the File Has Local Changes?

Suppose:

Student.java

has been modified but not committed.

Running:

git rm Student.java

may produce an error similar to:

error: the following file has local modifications

Git protects you from accidentally losing work.

---

Forcing File Removal

If you are absolutely sure, you can force the removal.

Example:

git rm -f Student.java

The option:

-f

means:

Force

Use this option carefully because local modifications may be lost.

---

Keeping the File but Removing It from Git

Sometimes you want:

• The file to remain on your computer.

• Git to stop tracking it.

This commonly happens with:

• Configuration files

• Environment files

• Generated files

Use:

git rm --cached Main.java

The option:

--cached

removes the file from Git's index but leaves the actual file on disk.

---

Practical Example: .env File

Suppose you accidentally committed:

.env

The file contains:

• Database password

• API keys

• Secret tokens

You should stop tracking it.

Run:

git rm --cached .env

Then create a .gitignore file containing:

.env

Now Git will stop tracking the file while it remains on your computer.

We will study .gitignore in detail in the next few articles.

---

Removing Files Already Deleted Manually

Suppose you manually delete:

OldReport.pdf

Git shows:

deleted: OldReport.pdf

You can stage the deletion using:

git rm OldReport.pdf

Since the file is already gone from the Working Directory, Git simply stages its removal from version control.

---

Recovering After git rm

Suppose you accidentally run:

git rm Student.java

but have not committed yet.

You can restore the file using:

git restore --staged Student.java

to unstage the deletion, and then:

git restore Student.java

to restore the file in the Working Directory.

Once the deletion has been committed, recovery typically involves restoring the file from a previous commit, which we will cover later in this series.

---

Real-World Example

Suppose you are developing an Online Shopping System.

Your project contains:

OldPayment.java

NewPayment.java

Main.java

The old payment module is no longer needed.

Run:

git rm OldPayment.java

Commit the change:

git commit -m "Remove obsolete payment module"

Your project history now clearly records when the old module was removed.

---

Common Beginner Mistakes

Mistake 1

Deleting a file manually and forgetting to stage the deletion.

Always check:

git status

before committing.

---

Mistake 2

Using:

git rm -f

without understanding that local changes may be lost.

---

Mistake 3

Using:

git rm --cached

and expecting the file to disappear from the computer.

The file stays on your computer.

Only Git stops tracking it.

---

Mistake 4

Removing important project files accidentally.

Review the list of files before pressing Enter.

---

Best Practices

• Check git status before removing files.

• Commit removals with meaningful messages.

• Use --cached for configuration or generated files you want to keep locally.

• Avoid -f unless necessary.

• Review staged deletions before committing.

---

Useful git rm Commands

Command	Purpose
git rm Main.java	Remove one tracked file
git rm file1 file2	Remove multiple files
git rm -r folder	Remove a directory recursively
git rm --cached file	Stop tracking a file but keep it locally
git rm -f file	Force removal of a modified file

---

Summary

The git rm command removes tracked files from your project and stages the deletion so it can be recorded in the next commit.

Unlike manually deleting a file, git rm updates both the Working Directory and Git's index, making file removal a smoother process.

The --cached option is particularly useful when you want Git to stop tracking a file while keeping it on your computer, such as environment files or generated assets.

Understanding git rm helps you maintain a clean repository and accurately record when files are removed from your project's history.