---
name: clean-git-history
description: >-
  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:

```powershell
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:

```powershell
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:

```powershell
# 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:

```powershell
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:

```powershell
# 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:

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

### 5. Final Verification

Verify remote history is clean:

```powershell
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)