Path Filtering Options

Path filtering options control which files and directories are included in the filtered repository history.

Renames are NOT automatically followed. If a file or directory was renamed in history, you need to specify both the old and new paths.

Basic Path Selection

—path, —path-match

--path

string

Exact path (file or directory) to include in filtered history.Type: File or directory pathMultiple: Yes - can be specified multiple times for union of pathsExample:

git filter-repo --path src/ --path README.md

This includes only the src/ directory and README.md file.

—path-glob

--path-glob

string

Glob pattern of paths to include in filtered history.Type: Glob patternMultiple: Yes - can be specified multiple times for union of pathsExample:

git filter-repo --path-glob '*.py' --path-glob 'docs/**/*.md'

This includes all Python files and all Markdown files in the docs directory.

Use quotes to prevent shell glob expansion

—path-regex

--path-regex

string

Regular expression of paths to include in filtered history.Type: Python regex patternMultiple: Yes - can be specified multiple times for union of pathsExample:

git filter-repo --path-regex '^src/.*\.(py|js)$'

This includes Python and JavaScript files in the src directory.

Uses Python regex syntax: https://docs.python.org/3/library/re.html

Path Selection Modifiers

—invert-paths

--invert-paths

boolean

default:"false"

Invert the selection of files from path options.When enabled, only files matching NONE of the path options are selected.Example:

git filter-repo --path-glob '*.log' --invert-paths

This removes all .log files from history.

—use-base-name

--use-base-name

boolean

default:"false"

Match on file basename instead of full path.Incompatible with: --path-renameCannot match: Directory namesExample:

git filter-repo --use-base-name --path README.md

This includes all README.md files regardless of their directory.

Path Shortcuts

—paths-from-file

--paths-from-file

string

Specify multiple path filtering and renaming directives from a file.Format: One directive per linePrefixes:

literal: (default) - Exact match
glob: - Glob pattern
regex: - Regular expression

Renames: Use ==> separatorComments: Lines starting with # are ignoredExample file (paths.txt):

# Keep source directories
literal:src/
literal:tests/

# Rename old directory
literal:old-name/==>new-name/

# Keep all Python files
glob:**.py

# Keep date-formatted files
regex:.*[0-9]{4}-[0-9]{2}-[0-9]{2}\.txt$

Usage:

git filter-repo --paths-from-file paths.txt

—subdirectory-filter

--subdirectory-filter

string

Extract a subdirectory and make it the project root.Only history touching the subdirectory is kept, and that directory becomes the new root.Equivalent to:

--path DIRECTORY/ --path-rename DIRECTORY/:

Example:

git filter-repo --subdirectory-filter mysubdir/

Contents of mysubdir/ become the new repository root.

—to-subdirectory-filter

--to-subdirectory-filter

string

Move the project root into a subdirectory.All files are moved into the specified subdirectory.Equivalent to:

--path-rename :DIRECTORY/

Example:

git filter-repo --to-subdirectory-filter myproject/

All repository contents are moved under myproject/.

Usage Examples

Keep Only Specific Directories

git filter-repo --path src/ --path docs/ --path README.md

Keeps only the src/ and docs/ directories plus the README file.

Remove Specific Files

git filter-repo --path-glob '*.log' --invert-paths

Removes all log files from repository history.

Keep Files by Pattern

git filter-repo --path-regex '^.*/.*/[0-9]{4}-[0-9]{2}-[0-9]{2}\.txt$'

Keeps only text files with date format YYYY-MM-DD.txt that are at least two subdirectories deep.

Combined Filtering

git filter-repo --path src/main/
git filter-repo --path-glob 'src/*/data' --invert-paths

First keeps only src/main/, then removes any files named data under any subdirectory.

Multiple filter-repo runs can be chained for complex filtering scenarios.

Important Notes

Renames are NOT followed automaticallyIf you renamed olddir/ to newdir/ in commit history, you must specify both:

git filter-repo --path olddir/ --path newdir/

Trailing Slashes

Directory names can be specified with or without trailing slashes:

--path src/    # Same as
--path src     # this

Processing Order

All path arguments are processed in the order specified. This matters for renames:

# Correct - filter selects the final destination
git filter-repo --path-rename old/:new/ --path new/

# Wrong - new/ doesn't exist yet when filter runs
git filter-repo --path new/ --path-rename old/:new/

Command Line

Python Library

Path Filtering Options

Path Filtering Options

Basic Path Selection

—path, —path-match

—path-glob

—path-regex

Path Selection Modifiers

—invert-paths

—use-base-name

Path Shortcuts

—paths-from-file

—subdirectory-filter

—to-subdirectory-filter

Usage Examples

Keep Only Specific Directories

Remove Specific Files

Keep Files by Pattern

Combined Filtering

Important Notes

Trailing Slashes

Processing Order

See Also

Build docs developers (and LLMs) love

Command Line

Python Library

Documentation Index

​Path Filtering Options

​Basic Path Selection

​—path, —path-match

​—path-glob

​—path-regex

​Path Selection Modifiers

​—invert-paths

​—use-base-name

​Path Shortcuts

​—paths-from-file

​—subdirectory-filter

​—to-subdirectory-filter

​Usage Examples

​Keep Only Specific Directories

​Remove Specific Files

​Keep Files by Pattern

​Combined Filtering

​Important Notes

​Trailing Slashes

​Processing Order

​See Also

Build docs developers (and LLMs) love

Path Filtering Options

Basic Path Selection

—path, —path-match

—path-glob

—path-regex

Path Selection Modifiers

—invert-paths

—use-base-name

Path Shortcuts

—paths-from-file

—subdirectory-filter

—to-subdirectory-filter

Usage Examples

Keep Only Specific Directories

Remove Specific Files

Keep Files by Pattern

Combined Filtering

Important Notes

Trailing Slashes

Processing Order

See Also