filter-repo Git Command Guide
The git filter-repo command is a modern, safe, and fast tool for rewriting Git history. It replaces the deprecated git filter-branch and provides better performance and fewer pitfalls. It can remove files, rewrite paths, anonymize data, and perform various history transformations.
git filter-repo Syntax:
Section titled “git filter-repo Syntax:”git filter-repo [--path <path>] [--invert-paths] [--path-rename <old>:<new>] [--message-callback <command>] [--name-callback <command>] [--email-callback <command>] [...other options]Options:
Section titled “Options:”| Option | Description |
|---|---|
| —path | Include/exclude paths from filtering |
| —invert-paths | Invert path selection |
| —path-rename | Rename file paths |
| —message-callback | Modify commit messages |
| —name-callback | Modify author/committer names |
| —email-callback | Modify author/committer emails |
| —replace-text | Perform text replacements across all files |
| —subdirectory-filter | Extract subdirectory as new root |
| —commit-callback | Custom commit modifications |
| —preserve-merge-parents | Maintain merge parent relationships |
| —force | Overwrite existing .git/filter-repo directory |
| —analyze | Analyze repository and show filtering suggestions |
Parameters:
Section titled “Parameters:”| Parameter | Description |
|---|---|
| (operates on current repository) | Works on current Git repository |
git filter-repo Command Samples:
Section titled “git filter-repo Command Samples:”Remove large files from history
Section titled “Remove large files from history”git filter-repo --path big-file.zip --invert-pathsRemove big-file.zip from all commits (keep everything except that file).
Extract subdirectory as new project
Section titled “Extract subdirectory as new project”git filter-repo --subdirectory-filter my-projectRewrite history to contain only my-project/ directory.
Rename directory path
Section titled “Rename directory path”git filter-repo --path-rename old-dir/:new-dir/Rename old-dir to new-dir in all files and commits.
Change author email globally
Section titled “Change author email globally”git filter-repo --email-callback 'return email.replace(b"old@email.com", b"new@email.com")'Replace author/committer email addresses.
Remove file by pattern
Section titled “Remove file by pattern”git filter-repo --path-glob '*.log' --invert-pathsRemove all .log files from history.
Modify commit messages
Section titled “Modify commit messages”git filter-repo --message-callback 'return message.replace(b"old text", b"new text")'Replace text in all commit messages.
Analyze repository before filtering
Section titled “Analyze repository before filtering”git filter-repo --analyzeShow suggestions for cleaning repository history.
Preserve merge commits
Section titled “Preserve merge commits”git filter-repo --path unwanted-file.txt --invert-paths --preserve-merge-parentsRemove file while maintaining merge structure.
How do I remove a large file from Git history?
Section titled “How do I remove a large file from Git history?”To remove a large file from history, use —path with —invert-paths:
git filter-repo --path big-file.zip --invert-pathsHow can I extract a subdirectory as a separate repository?
Section titled “How can I extract a subdirectory as a separate repository?”To extract a subdirectory, use —subdirectory-filter:
git filter-repo --subdirectory-filter my-subdirHow do I rename files or directories?
Section titled “How do I rename files or directories?”To rename paths, use —path-rename:
git filter-repo --path-rename old-name.txt:new-name.txtHow can I change author information?
Section titled “How can I change author information?”To change author info, use callback options:
git filter-repo --email-callback 'return email.replace(b"old@example.com", b"new@example.com")'How do I preview what filter-repo will do?
Section titled “How do I preview what filter-repo will do?”To analyze before running, use —analyze:
git filter-repo --analyzeHow do I remove files matching a pattern?
Section titled “How do I remove files matching a pattern?”To remove files by pattern, use —path-glob:
git filter-repo --path-glob '*.tmp' --invert-pathsHow do I force overwrite an existing filter-repo directory?
Section titled “How do I force overwrite an existing filter-repo directory?”To force filter-repo operations, use —force:
git filter-repo --force --path bad-file.txt --invert-pathsHow does filter-repo handle merge commits?
Section titled “How does filter-repo handle merge commits?”Use —preserve-merge-parents to maintain merge relationships:
git filter-repo --preserve-merge-parents --path removed.txt --invert-pathsApplications of the git filter-repo command
Section titled “Applications of the git filter-repo command”- Removing sensitive files from repository history
- Extracting subdirectories as independent projects
- Cleaning up repository bloat from large files
- Rewriting author information for privacy
- Fixing repository structure and file organization
- Creating sanitized repositories for public sharing