How do I delete a file from a Git repository?

How to Delete Files from a Git Repository Effectively

Learn the correct methods to remove files from your Git repository, whether you want to delete them from your working directory and Git history, or just from Git's tracking while keeping them locally.

Deleting files from a Git repository isn't as simple as just using your operating system's delete command. While that removes the file from your local working directory, Git will still track its absence as a modification. To properly remove a file from Git's history and tracking, or to untrack it while keeping it locally, you need to use specific Git commands. This article will guide you through the various scenarios and the appropriate commands to use.

Understanding git rm

The primary command for deleting files from a Git repository is git rm. This command not only removes the file from your working directory but also stages the deletion for the next commit. It's crucial to understand that git rm affects both your local filesystem and Git's index. Once committed, the file will be removed from the repository's history from that point forward.

flowchart TD
    A[Start: File exists in repo and working directory] --> B{Decide to delete file}
    B --> C[Run `git rm <file>`]
    C --> D[File removed from working directory]
    D --> E[Deletion staged in Git index]
    E --> F[Commit changes: `git commit -m "Removed file"`]
    F --> G[File removed from repository history (from this commit onwards)]
    G --> H[End]

Process of deleting a file from Git using git rm

# Delete a single file
git rm my_old_file.txt

# Delete multiple files
git rm file1.txt file2.js

# Delete files matching a pattern
git rm *.log

# Commit the deletion
git commit -m "Removed unnecessary files"

Basic usage of git rm to delete files and commit the changes.

Deleting Files from Git but Keeping Them Locally (--cached)

Sometimes, you might want Git to stop tracking a file, but you still need to keep a local copy of it in your working directory. This is common for configuration files, large data files, or temporary build artifacts that were accidentally committed. The --cached option with git rm allows you to achieve this. It removes the file from Git's index (staging area) but leaves the physical file untouched on your disk.

# Stop tracking 'config.ini' but keep it locally
git rm --cached config.ini

# Commit the change to stop tracking
git commit -m "Untracked config.ini, keeping local copy"

Using git rm --cached to untrack a file while preserving it locally.

Removing Files from Git History (Advanced)

The methods above remove files from the repository's history from the point of the commit forward. If a sensitive file (e.g., a password or private key) was committed several commits ago and you need to completely purge it from the entire repository history, you'll need more advanced tools like git filter-repo (recommended) or git filter-branch (legacy). This is a destructive operation that rewrites history and should be used with extreme caution, especially in shared repositories.

# Install git-filter-repo (if not already installed)
# pip install git-filter-repo

# Example: Remove a file named 'secrets.txt' from all history
git filter-repo --path secrets.txt --invert-paths

# Force push the rewritten history (DANGEROUS!)
git push --force --all

Example of using git filter-repo to remove a file from entire Git history. Use with extreme caution.