Auto-Finance/.agents/skills/clean-git-history/SKILL.md

name, description

name	description
clean-git-history	Remove sensitive files and directories from Git commit history using git-filter-repo. Use when the user wants to remove secrets, credentials, uploaded files, or any sensitive data that was accidentally committed to Git history. Also use when the user mentions cleaning Git history, removing leaked files, or scrubbing sensitive information from repositories.

Clean Git History

Remove sensitive files from Git history using git-filter-repo. This is a destructive operation that rewrites commit history.

Prerequisites

Install git-filter-repo if not already available:

python -m pip install git-filter-repo

Safety Checklist

Before proceeding, verify:

• Local source code is intact (git log --oneline shows expected commits)
• Remote repository is accessible (git fetch origin succeeds)
• Sensitive files are identified in history (git log --all --pretty=format: --name-only | Select-String "pattern")

Step-by-Step Workflow

1. Identify Sensitive Files

Check what sensitive paths exist in history:

git log --all --pretty=format: --name-only | Select-String "\.env|uploads/|images/|scripts/data/|logs/" | Sort-Object -Unique

2. Clean One Path at a Time

Remove each sensitive path separately, verifying after each step:

# Remove .env from history
python -m git_filter_repo --path .env --invert-paths --force

# Remove uploads directory from history
python -m git_filter_repo --path src/web/uploads/ --invert-paths --force

# Remove images directory from history
python -m git_filter_repo --path images/ --invert-paths --force

Critical: Always use --invert-paths to exclude files. Without it, --path keeps only those files and deletes everything else.

3. Verify Cleanup

Confirm sensitive files are gone:

git log --all --pretty=format: --name-only | Select-String "\.env|uploads/|images/" | Sort-Object -Unique

Result should be empty.

4. Restore Remote and Push

git-filter-repo removes the origin remote. Re-add and force push:

# Re-add remote (replace with actual URL)
git remote add origin <remote-url>

# Force push cleaned history
git push --force origin <branch-name>

If multiple branches exist, push each one:

git push --force origin master
git push --force origin feature/table

5. Final Verification

Verify remote history is clean:

git fetch origin
git log --all --pretty=format: --name-only | Select-String "\.env|uploads/|images/" | Sort-Object -Unique

Common Pitfalls

Mistake	Consequence	Fix
Missing --invert-paths	Deletes all files except the listed ones	Restore from remote: git reset --hard origin/<branch>
Wrong Python environment	No module named git_filter_repo	Use python -m pip install git-filter-repo in current environment
Forgetting to restore remote	Cannot push changes	Re-add remote with git remote add origin <url>

Post-Cleanup Actions

• Rotate any secrets that were exposed in history
• Update .gitignore to prevent re-committing sensitive files
• Notify team members to re-clone the repository (old clones still contain sensitive history)