Remove files (git rm)

What is git rm

git rm is a command provided by Git for removing files from version control. It not only deletes the file from the working directory but also records this deletion in the staging area. In other words, git rm is equivalent to executing the rm command followed immediately by git add, thereby incorporating the deletion into version management.

Basic Usage

The simplest usage is to directly specify the filename to be deleted:

git rm filename.txt

This command will delete the filename.txt file from the working directory and record this deletion in the staging area. If the file has been modified but not committed, Git will refuse the deletion unless the -f option is used to force it.

Deleting Modified Files

When attempting to delete a modified but unstaged file, Git will issue a warning:

$ git rm modified_file.txt
error: the following file has local modifications:
    modified_file.txt
(use --cached to keep the file, or -f to force removal)

In this case, you can:

1. Force deletion:

   git rm -f modified_file.txt
   

2. Remove from version control but keep the local file:

   git rm --cached modified_file.txt
   

Preserving Files in the Working Directory (--cached)

Sometimes you only want to remove a file from version control while keeping the actual file in the working directory. In such cases, use the --cached option:

git rm --cached file_to_keep_locally.txt

This is commonly used in scenarios such as:

• Accidentally adding files that should be ignored to version control
• Needing to retain local configuration files without sharing them with other developers

Recursively Deleting Directories

To delete an entire directory and its contents, use the -r option:

git rm -r directory_name

This is equivalent to:

rm -r directory_name
git add directory_name

Using Wildcards to Delete Multiple Files

git rm supports wildcards for batch deletion:

git rm *.tmp

This will delete all files with the .tmp extension.

Deleting Files That Have Been Manually Removed

If you have already deleted a file using the regular rm command, you can use git rm to record this deletion in the staging area:

rm deleted_file.txt
git rm deleted_file.txt

Or a simpler alternative:

git add -u

The -u option updates tracked files that have been modified or deleted.

Comparison with Other Commands

1. Difference from rm:

   • rm only deletes files from the working directory
   • git rm also records the deletion in the staging area

2. Relationship with git add:

   • git rm is essentially a combination of rm + git add
   • git add -u can handle files that have already been deleted

Practical Use Cases

Scenario 1: Removing Sensitive Information from Version Control

Suppose you accidentally committed a configuration file containing passwords:

git rm --cached config/secrets.yml
echo "config/secrets.yml" >> .gitignore
git commit -m "Remove sensitive config file"

Scenario 2: Cleaning Up Temporary Files in a Project

# First, check which temporary files are being tracked
git ls-files | grep '\.tmp$'

# Delete after confirmation
git rm *.tmp
git commit -m "Remove temporary files"

Undoing a git rm Operation

If you accidentally delete a file, you can undo it:

# Undo the deletion in the staging area (file remains in the working directory)
git reset HEAD deleted_file.txt

# If the file was also deleted from the working directory, restore it from the latest commit
git checkout -- deleted_file.txt

Batch Cleaning of Deleted Files

When many files have been manually deleted, you can process them in bulk:

# List all deleted files
git ls-files --deleted

# Remove in bulk
git ls-files --deleted | xargs git rm

Comparison with git filter-repo

For deleting files from the commit history, git rm only affects the latest commit. To completely remove files from history (e.g., large files), use git filter-repo:

git filter-repo --path large_file.zip --invert-paths

Notes

1. Irreversible Operation: git rm will actually delete files from the working directory unless you have a backup or can restore them from commit history.
2. Collaboration Impact: Deleting files affects other collaborators, who will need to handle potential conflicts after git pull.
3. .gitignore Coordination: After deletion, update .gitignore to prevent the files from being accidentally added again.

Advanced Usage: Interactive Deletion

Combine with git add -i to enter interactive mode and select files to delete:

git add -i

Then choose the remove option and follow the prompts.

Using git rm in Scripts

In automation scripts, you can safely delete files like this:

# Check if the file exists and is tracked by Git
if git ls-files --error-unmatch file_to_remove.txt >/dev/null 2>&1; then
    git rm file_to_remove.txt
fi

Performance Considerations

When deleting a large number of files, using git rm directly may be slow. An alternative approach:

# First, delete all files
rm -rf large_directory/

# Then record the changes in one go
git add -u

Combining with Other Git Commands

1. Delete and Commit Immediately:

   git rm old_file.txt && git commit -m "Remove outdated file"
   

2. Delete and Rename:

   git rm old_name.txt
   git mv new_name.txt
   

Handling Special Cases

Filenames with Special Characters:

# Filename contains spaces
git rm "file with spaces.txt"

# Filename contains special symbols
git rm -- 'file#with$special@chars.txt'

Deleting Symbolic Links:

git rm symlink_name

This will only delete the symbolic link itself, not the target file.