Skip to main content

​
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/

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us