Removing Files from Git (git rm)

As you build your project history, you might realize that certain files tracked by Git are no longer needed or were added by mistake. Simply deleting a file from your project folder using your operating system's file explorer or the command line (rm on Linux/macOS, del on Windows) isn't enough. Git will notice the file is missing from your working directory, but it won't automatically stage this deletion for the next commit. You need a specific Git command to properly record the removal of a file from your project's history.

Using git rm for File Removal

The command designed for this task is git rm. It performs two essential actions in one step:

1. Removes the file from your working directory (just like the standard rm or del command).
2. Stages the removal of the file in the Git index (staging area), preparing it to be recorded in the next commit.

To remove a file named obsolete_feature.js, you would run:

git rm obsolete_feature.js

After running this command, if you check the status, Git will show that the deletion is staged:

git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        deleted:    obsolete_feature.js

The file is now gone from your working directory, and its removal is staged. The next git commit will record this deletion in the project's history.

git commit -m "Remove obsolete feature code"

This ensures the file is properly removed from future versions of your project tracked by Git.

Keeping the File Locally, Untracking with Git

Sometimes, you might want Git to stop tracking a file, but you still want to keep the actual file in your working directory. This often happens if you accidentally committed a file that shouldn't be tracked, like a configuration file with sensitive information, a large data file, or editor-specific settings.

For this scenario, you use the --cached option with git rm:

git rm --cached config.local

This command removes config.local from the Git index (staging area), effectively telling Git to stop tracking it. However, it leaves the config.local file untouched in your working directory.

After running git rm --cached, git status will show the removal staged, and if the file wasn't previously ignored, it will likely appear as an "Untracked file":

git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        deleted:    config.local

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        config.local

After using git rm --cached, it's highly recommended to add the filename (config.local in this example) to your .gitignore file immediately. This prevents you or collaborators from accidentally adding it back into Git tracking in a future commit.

Commit the staged removal:

git commit -m "Stop tracking local configuration file"

Now, Git no longer tracks config.local, but the file remains available in your local project folder.

Illustrates the state of a file in the Working Directory and the Git Index (Staging Area) after different removal operations: OS delete (rm), git rm, and git rm --cached.

In summary, git rm is the standard command for removing files tracked by Git, handling both the working directory deletion and staging the change. Use git rm --cached when you need Git to forget about a file while keeping it locally, remembering to update your .gitignore afterward. Both commands require a subsequent git commit to finalize the removal in the project's history.