Permanently Clear Files from Git History

Guide users to permanently remove files from Git repository history. Use this skill when users mention any of the following scenarios: - "git filter-repo", "...

Security Scan

The skill is an instruction-only guide to using git-filter-repo to remove files from Git history; its requirements and actions align with that purpose and it does not request unrelated credentials or install arbitrary code.

Purpose & Capability

The name/description match the SKILL.md instructions: all steps are about removing files from Git history using git-filter-repo, backing up, and force-pushing rewritten history. There are no unrelated environment variables, binaries, or external services requested.

Instruction Scope

The instructions stay on task (backup repository, install git-filter-repo, run filter-repo, verify, force-push, revoke keys, notify collaborators). They explicitly require user confirmation before destructive steps. They do include destructive operations (history rewrite and force-push) which are expected for the stated purpose and are appropriately warned.

Install Mechanism

Instruction-only skill (no install spec). It suggests installing git-filter-repo via brew or pip; those are reasonable but pip installs can affect the user's Python environment—user should prefer a system package manager or virtualenv and fetch the tool from trusted sources.

Credentials

The skill requests no credentials or environment variables. It does assume the user has Git remote access (SSH keys or auth tokens) to perform force-pushes, which is normal and proportional to the task.

Persistence & Privilege

Skill is instruction-only, not always-enabled, and does not request persistent system privileges or modify other skills or global agent settings.

Assessment

This is a coherent, instruction-only guide for rewriting Git history. Before running any commands: (1) make a full backup and test on the backup, (2) coordinate with collaborators because history rewrite and force-push will disrupt others, (3) be prepared to revoke and rotate any exposed secrets after removal, (4) prefer installing git-filter-repo from trusted package sources and consider using a virtualenv or system package manager rather than system-wide pip where possible, (5) double-check branch names (main vs master) and remote names before running git reset --hard or force-push, and (6) verify removal locally (git log --all) and check forks/CI caches — history rewriting cannot guarantee removal from every clone or third-party cache.

Permanently Remove Files from Git History

When you delete a file in Git, it still remains in the Git repository history. This skill guides users to use the git filter-repo tool to permanently delete specified files from the complete history of a Git repository.

Applicable Scenarios

• Accidentally committed sensitive information (passwords, API keys, private keys, tokens)
• Accidentally committed large files, causing repository bloat
• Need to clean up specific files from history
• Need to remove a file from all branches and tags

Core Workflow

1. Important! First Step: Ask the User

Ask the user to confirm:

• The repository path
• Whether it's the current working directory
• Whether they need to backup the repository (strongly recommended)

Must wait for user confirmation before proceeding with subsequent steps.

2. Backup Repository (Strongly Recommended)

Before performing any operations, backup the repository first:

# Method 1: Copy the entire repository directory
cp -r your-repo your-repo-backup

# Method 2: Create a bare repository backup
git clone --bare your-repo your-repo-backup.git

3. Install git filter-repo

Choose installation method based on your operating system:

macOS:

brew install git-filter-repo

Ubuntu / Debian:

pip install git-filter-repo

Windows:

pip install git-filter-repo

4. Verify Current Repository Status

After entering the repository directory, check:

git status
git remote -v

If there's no remote repository, add one first:

git remote add origin [e-mail]:username/repository.git

5. Use git filter-repo to Delete Files

Assuming the file to delete is secrets.txt:

git filter-repo --path secrets.txt --invert-paths

What this step does:

• Removes the file from all commits
• Removes the file from all branches
• Removes the file from all tags

Delete multiple files:

git filter-repo --path file1.txt --path file2.txt --path secrets/ --invert-paths

Delete entire directory:

git filter-repo --path directory-name/ --invert-paths

6. Verify File Has Been Deleted

Check if the file still exists in history:

git log --all -- filename

If there's no output, the file has been completely removed.

6. Force Push to Remote Repository

Because the history has been rewritten, a force push is required:

# Push all branches
git push origin --force --all

# Push all tags
git push origin --force --tags

Additional Steps After Removing Sensitive Information

If you deleted sensitive information (keys, tokens, passwords, private keys), in addition to deleting history, you should also:

Immediately Revoke Old Keys

• Immediately revoke/delete old keys on the corresponding service platform (GitHub, AWS, Azure, etc.)
• Generate new keys

Check Other Locations

• Check if anyone else has forked the repository
• Check CI/CD caches
• Check if local clones still retain old content

Important Reminder: Just because history is deleted doesn't mean others haven't copied it before. Once sensitive information is committed to a public repository, it should be considered leaked.

Notify Collaborators

Because the commit history has changed, other people's local repositories will be inconsistent with the remote. You need to notify them:

1. Re-clone the repository (recommended)

2. Or execute the following command to sync:

   git fetch origin
   git reset --hard origin/main  # Will lose unpushed local changes, use with caution
   

3. Warning: Do not continue development based on the old history, otherwise the deleted files will be reintroduced when pushing again

Common Issues

Q: Getting "fatal: not a git repository"?

Make sure you're executing commands in the Git repository root directory.

Q: Getting "git filter-repo: command not found"?

Install git-filter-repo first, refer to the installation steps above.

Q: Repository size hasn't decreased after deletion?

Run garbage collection:

git gc --aggressive --prune=now

Q: Only want to modify the most recent commit?

If the file is only in the most recent commit, you don't need filter-repo, use:

git rm --cached filename
git commit --amend

One-Liner Version

The most core commands:

# Delete file
git filter-repo --path filename --invert-paths

# If no remote, add first
git remote add origin <repo-url>

# Force push
git push origin --force --all
git push origin --force --tags