​

Command Line API Overview

​

Usage Synopsis

git filter-repo --analyze
git filter-repo [<path_filtering_options>] [<content_filtering_options>]
	[<ref_renaming_options>] [<commit_message_filtering_options>]
	[<name_or_email_filtering_options>] [<parent_rewriting_options>]
	[<generic_callback_options>] [<miscellaneous_options>]

​

Option Categories

​

Analysis Options

• --analyze - Generate reports about repository contents
• --report-dir - Specify directory for analysis reports

​

Path Filtering Options

• --path, --path-match - Exact path matching
• --path-glob - Glob pattern matching
• --path-regex - Regular expression matching
• --invert-paths - Invert path selection
• --use-base-name - Match on basename only
• --paths-from-file - Load path specifications from file
• --subdirectory-filter - Extract subdirectory as project root
• --to-subdirectory-filter - Move project root to subdirectory

​

Path Renaming Options

• --path-rename, --path-rename-match - Rename paths

​

Content Editing Options

• --replace-text - Replace text patterns in files
• --strip-blobs-bigger-than - Remove large files
• --strip-blobs-with-ids - Remove specific blob objects

​

Commit Message Options

• --replace-message - Replace text in commit/tag messages
• --preserve-commit-hashes - Don’t update commit hash references
• --preserve-commit-encoding - Don’t re-encode messages to UTF-8

​

Name & Email Filtering Options

• --mailmap - Apply mailmap file for name/email translation
• --use-mailmap - Use .mailmap from repository

​

Ref Renaming Options

• --tag-rename - Rename tags by prefix

​

Parent Rewriting Options

• --replace-refs - Control replace ref handling
• --prune-empty - Control empty commit pruning
• --prune-degenerate - Control degenerate merge pruning
• --no-ff - Preserve merge commit topology

​

Generic Callback Options

• --filename-callback - Process filenames
• --file-info-callback - Process file metadata and content
• --message-callback - Process commit/tag messages
• --name-callback - Process person names
• --email-callback - Process email addresses
• --refname-callback - Process ref names
• --blob-callback - Process blob objects
• --commit-callback - Process commit objects
• --tag-callback - Process tag objects
• --reset-callback - Process reset objects

​

Sensitive Data Removal Options

• --sensitive-data-removal, --sdr - Enable sensitive data removal mode
• --no-fetch - Skip fetching all refs from origin

​

Location Options

• --source - Source repository to read from
• --target - Target repository to write to

​

Ordering Options

• --date-order - Process commits by timestamp order

​

Miscellaneous Options

• --help, -h - Show help
• --version - Show version
• --force, -f - Skip fresh clone checks
• --partial - Partial history rewrite
• --refs - Limit to specific refs
• --dry-run - Preview changes without applying
• --debug - Show debug information
• --stdin - Read fast-export stream from stdin
• --quiet - Suppress output
• --no-gc - Skip garbage collection

​

Quick Reference

​

Most Common Operations

git filter-repo --path src/ --path docs/

git filter-repo --strip-blobs-bigger-than 10M

git filter-repo --path-rename old-name/:new-name/

git filter-repo --replace-text expressions.txt

git filter-repo --subdirectory-filter mysubdir/

​

Combining Options

git filter-repo \
  --path src/ \
  --path-rename src/:lib/ \
  --replace-text secrets.txt \
  --strip-blobs-bigger-than 5M

​

Next Steps

• Path Options → - Detailed path filtering documentation
• Content Options → - Content modification options
• Commit Options → - Commit-related options
• Examples → - Real-world usage examples