cheatsheets/removing-files-from-git-history.md

Removing Files from Git History

This document outlines a secure, resource-efficient method to completely remove a file (and its traces) from a Git repository's history using git-filter-repo. This is useful for privacy-sensitive operations, such as removing accidentally committed secrets or sensitive data.

Prerequisites

• Git installed.
• git-filter-repo installed (install via sudo apt install git-filter-repo on Debian-based systems if needed).
• Admin access to the repository and remote (e.g., Gitea).

Steps

1. Verify the File in History:

   cd /path/to/repo
   git log -- <file-path>
   

   This lists commits involving the file.

2. Remove the File from History:

   git filter-repo --path <file-path> --invert-paths
   

   • --invert-paths excludes the specified path from all commits.
   • This rewrites history and removes remotes as a safety measure.

3. Re-add Remote (if removed):

   git remote add origin <remote-url>
   

4. Force Push Changes:

   git push origin --force --all
   

   • Use --force to overwrite remote history. Caution: This can break shared repos.

5. Verify Removal:

   git log -- <file-path>
   

   No output means the file is gone.

Security Notes

• Always back up your repo before rewriting history.
• Use secure remotes (e.g., SSH).
• Avoid if the repo is public or has multiple collaborators without coordination.
• Follow least privilege: Run without sudo unless necessary.

This method is lightweight and respects resource constraints (low RAM/CPU usage).

Last updated: [Current Date]