Output and Control Options

Options that control where git-filter-repo reads from and writes to, plus general operational controls.

Location Options

—source

--source

string

Git repository to read from.Type: Path to git repositoryDefault: Current directory (.)Effect: Implies --partialSpecifies a different repository to read history from. When used with --target, allows filtering from one repository into another without mixing old and new history.Example:

git filter-repo --source /path/to/source-repo --target /path/to/new-repo

Using --source automatically enables --partial mode.

—target

--target

string

Git repository to overwrite with filtered history.Type: Path to git repositoryDefault: Current directory (.)Effect: Implies --partialSpecifies a different repository to write filtered history to. The target repository will be overwritten with the filtered history.Example:

git filter-repo --source ./old-repo --target ./new-repo --path src/

The target repository will be completely overwritten. Make sure you have backups.

Operational Mode Options

—force, -f

--force

boolean

default:"false"

Bypass fresh clone checks and rewrite history anyway.Aliases: -fWarning: History rewriting is IRREVERSIBLEBy default, git-filter-repo checks if the repository is a fresh clone to prevent accidental data loss. This flag bypasses those safety checks.When to use:

You’re certain you have backups
Repository fails fresh clone checks but you want to proceed anyway
You’re running git-filter-repo multiple times on the same repo

Example:

git filter-repo --path src/ --force

DO NOT use --force habitually. Always work in a fresh clone when possible. If you need --force, make absolutely sure you have backups.

—partial

--partial

boolean

default:"false"

Perform partial history rewrite, mixing old and new history.Effects:

Disables refs/remotes/origin/* → refs/heads/* migration
Disables removal of origin remote
Disables removal of unexported refs
Disables reflog expiration
Disables automatic git gc
Changes --tag-rename and --refname-callback to create new refs instead of replacing

Automatically enabled by:

--source
--target
--refs

Example:

git filter-repo --path src/ --partial

Partial rewrites mix old and new history. Use with caution as this can lead to confusion.

—refs

--refs

string[]

Limit history rewriting to specified refs.Type: One or more ref specificationsEffect: Implies --partialFormat: Same as git fast-export (ref names, ranges, globs)Only the specified refs will be rewritten. All other refs remain unchanged.Examples:

# Rewrite only main branch
git filter-repo --refs refs/heads/main

# Rewrite specific branches
git filter-repo --refs refs/heads/feature-1 refs/heads/feature-2

# Rewrite all feature branches
git filter-repo --refs 'refs/heads/feature-*'

# Rewrite range
git filter-repo --refs main~10..main

This can cause issues with degenerate merge pruning when negative revisions are specified.

—dry-run

--dry-run

boolean

default:"false"

Preview changes without modifying the repository.Effects:

Runs git fast-export and filters output
Saves original export to .git/filter-repo/fast-export.original
Saves filtered export to .git/filter-repo/fast-export.filtered
Does NOT modify repository
Does NOT run git fast-import
Disables commit message hash rewriting (new hashes unknown)
Disables some empty commit filtering (can’t query fast-import)

Example:

git filter-repo --path src/ --dry-run

# Review the filtered output
cat .git/filter-repo/fast-export.filtered

Always test with --dry-run first for complex operations.

—debug

--debug

boolean

default:"false"

Show additional debugging information.Output includes:

Commands being run
File locations for input/output
Processing steps
Extra operational details

With --dry-run: Shows what WOULD be runWithout --dry-run: Shows what IS being runExample:

git filter-repo --path src/ --debug

Input Options

—stdin

--stdin

boolean

default:"false"

Read fast-export stream from stdin instead of running git fast-export.Requirements:

Input must be in expected fast-export format
Must include original-oid directives

Use cases:

Custom pre-processing of export stream
Combining multiple export streams
Testing with pre-generated exports

Example:

# Generate export separately
git fast-export --show-original-ids --all > export.dat

# Filter it
cat export.dat | git filter-repo --stdin

Sensitive Data Removal

—sensitive-data-removal, —sdr

--sensitive-data-removal

boolean

default:"false"

Enable sensitive data removal mode.Aliases: --sdrAdditional actions:

Fetches all refs from origin (unless --no-fetch)
Tracks and reports first changed commits
Tracks orphaned LFS objects
Provides detailed cleanup instructions

Example:

git filter-repo --replace-text secrets.txt --sensitive-data-removal

May discard local-only changes during fetch. Use --no-fetch if you have unpushed changes.

—no-fetch

--no-fetch

boolean

default:"false"

Skip the automatic fetch when using --sensitive-data-removal.Effect: Prevents overwriting local-only changesRisk: May leave sensitive data in unfetched refsAutomatically enabled by: --partial or any flag implying --partialExample:

git filter-repo --sdr --no-fetch --replace-text secrets.txt

Output Control

—quiet

--quiet

boolean

default:"false"

Suppress progress output and pass --quiet to git commands.Example:

git filter-repo --path src/ --quiet

—no-gc

--no-gc

boolean

default:"false"

Skip running git gc after filtering.Default behavior: Runs git gc --aggressive after filteringUse --no-gc when:

You’ll run multiple filter-repo commands
You want to run gc manually later
You’re doing partial filtering

Example:

git filter-repo --path src/ --no-gc

Ordering Options

—date-order

--date-order

boolean

default:"false"

Process commits in commit timestamp order.Default: Topological order (parents before children)Effect: Processes commits by author/commit date insteadExample:

git filter-repo --date-order

Utility Options

—help, -h

--help

boolean

Show help message and exit.Aliases: -hExample:

git filter-repo --help

—version

--version

boolean

Display git-filter-repo version and exit.Example:

git filter-repo --version

—analyze

--analyze

boolean

default:"false"

Analyze repository without modifying it.Output: Creates reports in .git/filter-repo/analysis/Reports include:

Blob sizes by path/extension
Path renames over time
Large objects
Directory statistics

Example:

git filter-repo --analyze
ls .git/filter-repo/analysis/

Learn more about analysis →

—proceed

--proceed

boolean

default:"false"

Avoid triggering the no-arguments-specified check.Use this when you want to run git-filter-repo with only callback options and no filtering flags. Without this flag, git-filter-repo will complain if you don’t specify any filtering options.Example:

# Run with only a callback, no filtering
git filter-repo --commit-callback 'print(commit.message)' --proceed

Usage Examples

Filter Between Repositories

# Filter from source to new clean repository
git filter-repo \
  --source ./messy-repo \
  --target ./clean-repo \
  --path important-code/

Dry Run Before Real Filtering

# Test first
git filter-repo --path src/ --dry-run

# Review output
less .git/filter-repo/fast-export.filtered

# If looks good, run for real
git filter-repo --path src/

Multiple Sequential Filters

# Run multiple filters, skip gc until done
git filter-repo --path src/ --no-gc
git filter-repo --replace-text secrets.txt --no-gc
git filter-repo --strip-blobs-bigger-than 10M --no-gc

# Now run gc once at end
git gc --aggressive

Sensitive Data Removal

# Remove sensitive data with full cleanup
git filter-repo \
  --replace-text secrets.txt \
  --sensitive-data-removal

# Check generated reports
cat .git/filter-repo/first-changed-commits
cat .git/filter-repo/orphaned_lfs_objects

Partial History Rewrite

# Rewrite only specific branches
git filter-repo \
  --refs refs/heads/feature-1 refs/heads/feature-2 \
  --path src/

Important Notes

Fresh Clone Requirementgit-filter-repo expects to run on a fresh clone. Use --force to override this check, but ONLY if you have backups.

Mixing Old and New History--partial mode mixes old and new history. This is usually not what you want for a clean history rewrite.

Always Test FirstUse --dry-run and --debug for complex operations:

git filter-repo --path src/ --dry-run --debug

Command Line

Python Library

Output and Control Options

Output and Control Options

Location Options

—source

—target

Operational Mode Options

—force, -f

—partial

—refs

—dry-run

—debug

Input Options

—stdin

Sensitive Data Removal

—sensitive-data-removal, —sdr

—no-fetch

Output Control

—quiet

—no-gc

Ordering Options

—date-order

Utility Options

—help, -h

—version

—analyze

—proceed

Usage Examples

Filter Between Repositories

Dry Run Before Real Filtering

Multiple Sequential Filters

Sensitive Data Removal

Partial History Rewrite

Important Notes

See Also

Build docs developers (and LLMs) love

Command Line

Python Library

​Output and Control Options

​Location Options

​—source

​—target

​Operational Mode Options

​—force, -f

​—partial

​—refs

​—dry-run

​—debug

​Input Options

​—stdin

​Sensitive Data Removal

​—sensitive-data-removal, —sdr

​—no-fetch

​Output Control

​—quiet

​—no-gc

​Ordering Options

​—date-order

​Utility Options

​—help, -h

​—version

​—analyze

​—proceed

​Usage Examples

​Filter Between Repositories

​Dry Run Before Real Filtering

​Multiple Sequential Filters

​Sensitive Data Removal

​Partial History Rewrite

​Important Notes

​See Also

Build docs developers (and LLMs) love

Output and Control Options

Location Options

—source

—target

Operational Mode Options

—force, -f

—partial

—refs

—dry-run

—debug

Input Options

—stdin

Sensitive Data Removal

—sensitive-data-removal, —sdr

—no-fetch

Output Control

—quiet

—no-gc

Ordering Options

—date-order

Utility Options

—help, -h

—version

—analyze

—proceed

Usage Examples

Filter Between Repositories

Dry Run Before Real Filtering

Multiple Sequential Filters

Sensitive Data Removal

Partial History Rewrite

Important Notes

See Also