Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/newren/git-filter-repo/llms.txt

Use this file to discover all available pages before exploring further.

​
Content Editing Options

Content editing options allow you to modify file contents or remove specific files based on size or blob ID.

​
Text Replacement

​
—replace-text

​
--replace-text
string
Replace text patterns found in file contents.Reads expressions from a file. Each expression found in files will be replaced with ***REMOVED*** by default.Type: Path to expressions fileDefault replacement: ***REMOVED***Expression formats:
  • Plain text (default) - Treated as literal string
  • regex:PATTERN - Regular expression
  • glob:PATTERN - Glob pattern
Custom replacement: End line with ==>REPLACEMENTExample expressions file (secrets.txt):
# Remove passwords (default replacement)
PASSWORD=secret123

# Replace API key with placeholder
regex:api[_-]key\s*=\s*[A-Za-z0-9]+==><API_KEY_REMOVED>

# Replace email domains
glob:*@oldcompany.com==>*@newcompany.com

# Literal text with default replacement
SECRET_TOKEN_HERE
Usage:
git filter-repo --replace-text secrets.txt
Binary files (containing null bytes in first 8KB) are skipped automatically.

​
Blob Removal

​
—strip-blobs-bigger-than

​
--strip-blobs-bigger-than
string
Remove files larger than the specified size.Type: Size with suffix (K, M, G)Size suffixes:
  • K - Kilobytes (1024 bytes)
  • M - Megabytes (1024²)
  • G - Gigabytes (1024³)
  • No suffix - bytes
Examples:
# Remove files larger than 5 megabytes
git filter-repo --strip-blobs-bigger-than 5M

# Remove files larger than 100 kilobytes
git filter-repo --strip-blobs-bigger-than 100K

# Remove files larger than 2 gigabytes
git filter-repo --strip-blobs-bigger-than 2G

# Remove files larger than 1000000 bytes
git filter-repo --strip-blobs-bigger-than 1000000
This removes the files from history, not just from the latest commit. The files will be gone from all commits.

​
—strip-blobs-with-ids

​
--strip-blobs-with-ids
string
Remove specific blob objects by their SHA-1 hash.Reads git object IDs from a file (one per line) and removes all of them from history.Type: Path to file containing blob IDsFormat: One SHA-1 hash per lineExample blob IDs file (blobs-to-remove.txt):
a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0a1
c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0a1b2
Finding blob IDs:
# Find blob ID for a specific file
git log --all --full-history -- path/to/file.bin
git ls-tree <commit-sha> path/to/file.bin

# Find large blobs
git rev-list --objects --all | 
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' |
  awk '/^blob/ {print $2, $3, $4}' |
  sort -k2 -n -r |
  head -20
Usage:
git filter-repo --strip-blobs-with-ids blobs-to-remove.txt

​
Usage Examples

​
Remove Passwords from All Files

Create expressions file (passwords.txt): 
PASSWORD=oldpassword123
api_secret=abc123xyz
regex:token\s*=\s*['\"][^'\"]+['\"]===><TOKEN_REMOVED>
Run filter: 
git filter-repo --replace-text passwords.txt

​
Remove Large Binary Files

# Remove all files larger than 10MB
git filter-repo --strip-blobs-bigger-than 10M

​
Remove Specific Problem Files

Step 1: Identify blob IDs 
# Find the commit where file was added
git log --all --full-history -- problematic-file.bin

# Get blob ID
git ls-tree <commit-hash> problematic-file.bin
# Output: 100644 blob a1b2c3d4... problematic-file.bin
Step 2: Create blob list file 
echo "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" > blobs.txt
Step 3: Remove the blobs 
git filter-repo --strip-blobs-with-ids blobs.txt

​
Combined Content Filtering

# Replace secrets AND remove large files
git filter-repo \
  --replace-text secrets.txt \
  --strip-blobs-bigger-than 5M

​
Expression File Syntax

​
Basic Format

# Comments start with #
# Blank lines are ignored

# Literal string (default)
secret_password

# With custom replacement
old_email@domain.com==>new_email@domain.com

# Regex pattern
regex:api[-_]key\s*=\s*[A-Za-z0-9]{32}

# Regex with replacement
regex:(password|passwd)\s*=\s*[^\s]+==><PASSWORD_REDACTED>

# Glob pattern
glob:*@oldcompany.com

# Glob with replacement  
glob:*@oldcompany.com==>*@newcompany.com

​
Escaping Special Characters

# For literal strings with special prefixes, use literal: explicitly
literal:regex:not_actually_a_regex
literal:glob:not_a_glob
literal:#not-a-comment

​
Important Notes

Binary File HandlingFiles containing null bytes (\0) in the first 8KB are automatically skipped by --replace-text to avoid corrupting binary files.
Irreversible ChangesContent filtering is irreversible. Always test with --dry-run first:
git filter-repo --replace-text secrets.txt --dry-run
Review the filtered output in .git/filter-repo/fast-export.filtered

​
Case Sensitivity

Text replacement is case-sensitive by default. Use regex with case-insensitive flag: 
regex:(?i)password\s*=\s*.+==><PASSWORD_REMOVED>

​
Performance Considerations

  • --replace-text processes every file in every commit
  • Complex regex patterns can slow down filtering
  • Consider using path filters to limit scope:
git filter-repo --path src/ --replace-text secrets.txt

​
Finding Large Files

Before removing large files, identify them: 
# Analyze repository
git filter-repo --analyze

# Check the generated report
cat .git/filter-repo/analysis/blob-shas-and-paths.txt
The analysis report shows:
  • Blob sizes
  • File paths
  • Commit history

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us