Today, we’re diving into a technical guide on doing a “deep clean” of a Git repository.<\/p>\n
When you’re deep in the zone of development, it’s surprisingly easy to accidentally commit something you shouldn’t have and push it to the remote repository.<\/p>\n
If you panic, run git rm to delete the file, and commit again, all you’ve really done is added a new history entry saying “this was deleted.” The data for that file still stubbornly remains in your past commit logs (inside the .git directory).
\nThe repository size won’t decrease, and anyone going back through the history will still be able to see the contents.<\/p>\n
In this post, I’ll walk through the surgical procedure to make specific files “as if they never existed from the very beginning of history” using git-filter-repo, the modern tool officially recommended by Git.<\/p>\n
Our goals for this operation are as follows:<\/p>\n
While git filter-branch and BFG Repo-Cleaner used to be the go-to tools, git-filter-repo is now the official recommendation. Written in Python, it runs extremely fast and is designed to handle complex histories safely.<\/p>\n
pip install git-filter-repo<\/pre>\n*If you are on a Mac using Homebrew, you can also install it via brew install git-filter-repo.<\/p>\n
[WARNING] Backup Before You Begin<\/h3>\n
The operation we are about to perform is destructive.
\nJust in case you accidentally wipe out necessary files, make sure to copy the entire repository directory to create a backup first.<\/p>\nPractical Steps: Eradicating a Specific File<\/h2>\n
We will proceed with the steps to purge a secret.txt file that was mistakenly mixed into the repository.
\n*The procedure is completely identical for huge video files or binary data\u2014just substitute the file name.<\/p>\nConfirming Existence<\/h3>\n
First, let’s check how deeply embedded that file is within Git’s history.<\/p>\n
git log --all -- secret.txt\ncommit 476b4bcd36ee3e1b900db9edb98ea82e12d61f90 (HEAD -> master)\nAuthor: nando <xxx@gmail.com>\nDate: Wed Feb 11 18:51:51 2026 +0900\n\nDELETE secret.txt\n\ncommit c0676094dab6734d147f14273275340655d5f513\nAuthor: nando <xxx@gmail.com>\nDate: Wed Feb 11 18:51:40 2026 +0900\n\nADD secret.txt<\/pre>\nIf logs are displayed, Git remembers the file.<\/p>\n
Erasing from History (Execution)<\/h3>\n
Run the following command. This is where we perform the surgery.<\/p>\n
git filter-repo --path secret.txt --invert-paths<\/pre>\nOption Breakdown:<\/h4>\n
\n
- –path secret.txt: Specifies the file you want to delete (if it’s an entire directory, specify the directory name).<\/li>\n
- –invert-paths: This is crucial. It instructs Git to **”keep everything except (invert) the specified path”** = **”discard the specified path.”**<\/li>\n<\/ul>\n
If an Error Occurs Here<\/h3>\n
If you encounter the error
Aborting: Refusing to destructively overwrite repo history...<\/code>, that is a safety mechanism.
\nTo prevent accidental operations, git-filter-repo may refuse to run unless you are in a “clean state right after cloning.”
\nIf this happens, append the –force option to force execution.<\/p>\ngit filter-repo --path secret.txt --invert-paths --force\ngit log\ncommit 60219177b930da26f899b0675a2b8a67fdbc3b3c (HEAD -> master)\nAuthor: nando <xxx@gmail.com>\nDate: Wed Feb 11 18:51:13 2026 +0900\ninitial commit\ngit log --all -- secret.txt\n<If nothing outputs, you're good><\/pre>\nAfter running, the process completes in an instant. Run git log again to check, and if nothing appears, your local repository has been purified.<\/p>\n
The Tough Part: Pushing to a Protected Remote<\/h2>\n
This is where many people stumble.
\nYour local environment is now clean, but the remote (GitHub, etc.) still holds the “corrupted history.” Furthermore, if this file has already been merged into the main branch, things get a bit more complicated.<\/p>\nNormally, the main branch is “Protected” to prevent accidental operations, meaning Force Pushes that rewrite history are configured to be rejected.<\/p>\n
If you try to run git push origin main –force as-is, it will be blocked by an error like this:<\/p>\n
! [remote rejected] main -> main (protected branch hook declined)<\/pre>\nTo break through this, you need administrator privileges to temporarily disable the rule.<\/p>\n
Lifting Protection Rules<\/h3>\n
Open your GitHub or GitLab repository settings page (Settings -> Branches) and edit the protection rules for the main branch.
\nTemporarily disable the rules altogether or check the box for “Allow force pushes.”<\/p>\nExecuting the Force Push<\/h3>\n
The exact moment you lift the protection, push without delay.<\/p>\n
git push origin main --force<\/pre>\n*If the change affects all branches, include the –all flag as well.<\/p>\n
Restoring Protection Rules (Most Important)<\/h3>\n
As soon as the push succeeds, immediately return to the settings page and restore the protection rules.
\nLeaving this undone leaves a lingering risk that someone might accidentally destroy the history again later.<\/p>\nThorough Communication with Team Members<\/h3>\n
Rewriting history comes with major side effects.
\nBecause every single commit ID in the repository has changed, your history will no longer align with the repositories your teammates have on their local machines.<\/p>\nIf a team member continues working from their “locally corrupted history” without knowing about your fix and pushes their changes, secret.txt will rise like a zombie, tangling the history beyond easy recovery.<\/p>\n
Once you finish the operation, make sure to thoroughly communicate the following:<\/p>\n
\n[Important Notice]
\nWe have rewritten the history to remove unnecessary files (such as secret.txt) from the repository.
\nPlease do not push or pull from the repository you currently have on your local machine.
\nDelete your existing folder and perform a fresh git clone.<\/p>\n<\/blockquote>\nThis is the safest and only real solution.<\/p>\n
Summary<\/h2>\n
\n
- Deletion tool: git-filter-repo is the only way to go.<\/li>\n
- Error handling: If an error pops up, muscle through it with –force.<\/li>\n
- Remote synchronization: Temporarily lift branch protection and run push –force.<\/li>\n
- Team coordination: Have everyone re-clone the repository.<\/li>\n<\/ul>\n
They say “water spilled cannot be gathered,” but in the world of Git, you *can* gather it back\u2014at the cost of powerful tools, administrative rights, and some friction for your team.
\nHowever, that cost is by no means cheap.<\/p>\n","protected":false},"excerpt":{"rendered":"Today, we’re diving into a technical guide on doing a “deep clean” of a Git repository. When […]<\/p>\n","protected":false},"author":4,"featured_media":2671,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_locale":"en_US","_original_post":"https:\/\/donguri3.net\/?p=2670","footnotes":""},"categories":[1172],"tags":[125,1072,51,430,47,835,251],"class_list":["post-5344","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-development-programming-git","tag-api","tag-cli","tag-git","tag-github","tag-python","tag-tips","tag-251","en-US"],"_links":{"self":[{"href":"https:\/\/donguri3.net\/wp-json\/wp\/v2\/posts\/5344","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/donguri3.net\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/donguri3.net\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/donguri3.net\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/donguri3.net\/wp-json\/wp\/v2\/comments?post=5344"}],"version-history":[{"count":1,"href":"https:\/\/donguri3.net\/wp-json\/wp\/v2\/posts\/5344\/revisions"}],"predecessor-version":[{"id":5347,"href":"https:\/\/donguri3.net\/wp-json\/wp\/v2\/posts\/5344\/revisions\/5347"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/donguri3.net\/wp-json\/wp\/v2\/media\/2671"}],"wp:attachment":[{"href":"https:\/\/donguri3.net\/wp-json\/wp\/v2\/media?parent=5344"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/donguri3.net\/wp-json\/wp\/v2\/categories?post=5344"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/donguri3.net\/wp-json\/wp\/v2\/tags?post=5344"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}