DEV Community

Clay Pask
Clay Pask

Posted on

How I Built GitCleanse: A CLI Tool That Removes Secrets From Git History

#showdev #devtools #git #security

You committed a secret to git. Maybe an API key, a database password, a .env file that slipped through. It happens to everyone.

The bad news: deleting the file and pushing a new commit does not remove it. The secret is still there in git history, accessible to anyone who clones your repo.

I built GitCleanse to fix this.

What it does

GitCleanse is a CLI tool that scrubs secrets from your git history. Point it at a repo, tell it what to remove, and it rewrites history as if the secret was never there.

npx gitcleanse --repo ./my-project --pattern "AKIA[0-9A-Z]{16}"
Enter fullscreen mode Exit fullscreen mode

It uses git filter-branch under the hood but wraps the messy parts in a clean interface. No more staring at git documentation trying to remember the exact incantation.

Why git delete is not enough

When you delete a file and commit, git records the deletion — but the old commits still exist. Anyone with access to your repo history can run git log and find the file in a previous commit.

This is why secret leaks are so dangerous even after you "fix" them. The fix only works if you:

  1. Revoke and rotate the secret (always do this first)
  2. Remove it from git history so it cannot be retrieved

GitCleanse handles step 2.

How it works

GitCleanse rewrites your git history by:

  1. Identifying commits that contain the target secret or file
  2. Rewriting each affected commit to remove the secret
  3. Cleaning up refs and running garbage collection so the old data is not recoverable

After running it you will need to force-push to your remote. This is the expected behaviour — you are rewriting history.

The companion tool

GitCleanse pairs naturally with EnvGuard, which audits your .env files before commits and catches secrets before they reach git. EnvGuard is prevention. GitCleanse is the cure.

If you are reading this because something already leaked: revoke the secret first, then run GitCleanse, then switch to EnvGuard to make sure it never happens again.

Get it

GitCleanse is available on Gumroad for €15: https://incredibroxp.gumroad.com/l/hcunuf

One-time purchase, instant download.

Part of a series on building small developer tools. Also in this series: EnvGuard and ReadmeGen.

Top comments (0)