Menu
MANDATORY: Use instead of `git filter-branch` - safer git-filter-repo with recovery
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Guide for writing clear, descriptive commit messages
Merge task branch to base branch with linear history (works from task worktree)
MANDATORY: Use instead of `git rebase` - provides automatic backup and conflict recovery
MANDATORY: Use instead of `git rebase -i` for squashing - unified commit messages
Analyze mistakes with conversation length as potential cause (CAT-specific)
Run scheduled retrospective analysis, derive action items, and track effectiveness
| name | git-rewrite-history |
| description | MANDATORY: Use instead of `git filter-branch` - safer git-filter-repo with recovery |
Purpose: Safely rewrite git history using git-filter-repo, the modern replacement for
git filter-branch.
Always use git-filter-repo instead of git filter-branch. Git itself warns against filter-branch:
git-filter-branch has a glut of gotchas generating mangled history rewrites. Use git-filter-repo instead.
| Feature | git-filter-repo | git-filter-branch |
|---|---|---|
| Speed | 10-50x faster | Slow |
| Safety | Handles edge cases | Many gotchas |
| Maintenance | Actively maintained | Deprecated |
| Syntax | Simple, intuitive | Complex, error-prone |
pip install git-filter-repo
# or
pip install --break-system-packages git-filter-repo
ALWAYS follow this pattern:
--partial (preserves reflog for recovery)Always include the --partial flag with git-filter-repo. Without it:
git gc runs (objects permanently deleted)With --partial:
git reset --hard HEAD@{n} possible# Fresh clone required
git clone --mirror <url> repo-filter
cd repo-filter
# Remove file (--partial preserves reflog for recovery)
git filter-repo --partial --path secrets.txt --invert-paths
# Verify
git log --all --oneline -- secrets.txt # Should return nothing
# If wrong, recover: git reflog && git reset --hard HEAD@{n}
# Push only after verification (requires explicit user approval)
git push origin --force --all
git filter-repo --partial --path vendor/ --invert-paths
# This removes the gitlink entry for a submodule
git filter-repo --partial --path submodule-name --invert-paths
# Rename a file across all history
git filter-repo --partial --path-rename old-name.txt:new-name.txt
# Move directory
git filter-repo --partial --path-rename old-dir/:new-dir/
# Remove files larger than 10MB
git filter-repo --partial --strip-blobs-bigger-than 10M
# Keep only src/ directory (remove everything else)
git filter-repo --partial --path src/
# Replace text patterns
git filter-repo --partial --replace-text expressions.txt
# Where expressions.txt contains:
# PASSWORD=secret123==>PASSWORD=REDACTED
# regex:api_key=\w+==>api_key=REDACTED
By default, git-filter-repo requires a fresh clone. To work on an existing repo:
# --partial preserves reflog, --force allows non-fresh clone
git filter-repo --partial --force --path file-to-remove --invert-paths
git push --force-with-lease origin <branch>git log --all -- <path>git diff --stat <old-commit>..<new-head>If something goes wrong (before force-push):
# With --partial, old history is in reflog
git reflog # Find old commit (e.g., HEAD@{2})
git reset --hard HEAD@{2} # Restore to pre-filter state
# If you have original remote (after force-push)
git fetch origin
git reset --hard origin/<branch>
# If you kept a backup branch
git reset --hard backup-before-filter
CRITICAL: Recovery from reflog only works if:
--partial flaggit gc)