This warning appears when you try to add a file larger than 50MB to Git. Large files bloat repository size and slow down operations. Use Git LFS or .gitignore to handle large files properly.
The "File is too large to be efficiently tracked by Git" warning indicates that you're attempting to add a file that exceeds Git's recommended size threshold (typically 50MB). While Git will still track the file, doing so is problematic because Git stores the complete file content in its history for every version. Unlike text files where Git stores only the differences (diffs) between versions, binary files like videos, datasets, archives, and compiled binaries must be stored in their entirety with each change. This causes several issues: repository size grows rapidly, clone and fetch operations become slow, and local disk usage increases significantly. GitHub and other hosting services enforce hard limits (100MB on GitHub) and will reject pushes containing files exceeding these limits. Even below these limits, large files in Git history cannot be easily removed and will permanently bloat the repository.
First, find which files are triggering the warning or are too large:
# Find files larger than 50MB in your working directory
find . -type f -size +50M -not -path "./.git/*"
# Check what files are staged
git status
# See sizes of staged files
git diff --cached --statIf the file is already committed, find large files in history:
# List the 10 largest files in the repository history
git rev-list --objects --all | \
git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
sed -n 's/^blob //p' | sort -rnk2 | head -10Choose the appropriate solution based on your needs:
Option A: Ignore the file - If the file doesn't need version control (build artifacts, temp files)
- Add to .gitignore and remove from staging
Option B: Remove from history - If the file was accidentally committed
- Use git filter-repo or BFG to remove it from all commits
Option C: Use Git LFS - If you need to version control the large file
- Install Git LFS and track the file type
For most cases, Option A or C is the right choice.
If you don't need to track the large file, add it to .gitignore:
# Add specific file
echo "large_file.zip" >> .gitignore
# Add file patterns
echo "*.zip" >> .gitignore
echo "*.tar.gz" >> .gitignore
echo "data/*.csv" >> .gitignore
# Remove from staging if already added
git reset HEAD large_file.zip
# Commit the .gitignore
git add .gitignore
git commit -m "Add large files to .gitignore"Common patterns to ignore:
# Build outputs
dist/
build/
*.exe
*.dll
# Data files
*.csv
*.json.gz
*.parquet
# Archives
*.zip
*.tar.gz
*.rar
# Media
*.mp4
*.mov
*.psdGit Large File Storage (LFS) replaces large files with small pointer files while storing the actual content on a remote server.
Install Git LFS:
# macOS
brew install git-lfs
# Ubuntu/Debian
sudo apt install git-lfs
# Windows (with Git for Windows 2.29+)
# Git LFS is included, just initialize it
# Fedora/RHEL
sudo dnf install git-lfsInitialize Git LFS in your repository:
git lfs installThis only needs to be run once per user account, not per repository.
Tell Git LFS which file types to track:
# Track specific file types
git lfs track "*.zip"
git lfs track "*.psd"
git lfs track "*.mp4"
# Track a specific file
git lfs track "data/large_dataset.csv"
# Track files in a directory
git lfs track "assets/**"This creates or updates a .gitattributes file. You must commit this file:
git add .gitattributes
git commit -m "Track large files with Git LFS"Now add and commit your large files normally:
git add large_file.zip
git commit -m "Add large file via LFS"Verify LFS is tracking correctly:
git lfs ls-filesIf large files are already in your Git history, use git lfs migrate:
# Migrate specific file types in all branches
git lfs migrate import --include="*.zip,*.psd" --everything
# Migrate files over a certain size
git lfs migrate import --above=50mb --everything
# Migrate only in the current branch
git lfs migrate import --include="*.zip"Important: This rewrites history. After migration:
# Force push to update remote (coordinate with your team!)
git push --force-with-lease
# Team members must re-clone or run:
git lfs fetch --all
git lfs checkoutIf you want to completely remove large files from history (not track them at all):
Using git filter-repo (recommended):
# Install git-filter-repo
pip install git-filter-repo
# Remove a specific file from all history
git filter-repo --path large_file.zip --invert-paths
# Remove all files larger than 50MB
git filter-repo --strip-blobs-bigger-than 50MUsing BFG Repo-Cleaner:
# Clone the repo as a mirror
git clone --mirror [email protected]:user/repo.git
# Remove files larger than 100MB
java -jar bfg.jar --strip-blobs-bigger-than 100M repo.git
# Clean up
cd repo.git
git reflog expire --expire=now --all && git gc --prune=now --aggressive
# Push changes
git push --forceWarning: Both methods rewrite history. All collaborators must re-clone the repository.
After implementing your solution, verify everything is correct:
# Check repository size
git count-objects -vH
# Verify no large files are staged
git diff --cached --stat
# Check LFS tracking (if using LFS)
git lfs ls-files
git lfs status
# Push changes
git push origin mainIf using Git LFS, the push will upload large files to the LFS server separately from the main Git push.
Git LFS Quotas and Costs: GitHub offers 1GB of free LFS storage and 1GB of bandwidth per month. Additional storage is $5/month per 50GB data pack. GitLab offers 5GB free. Consider costs for large projects.
Pre-commit Hook for Size Limits: Prevent large files from being committed:
# .git/hooks/pre-commit
#!/bin/bash
MAX_SIZE=50000000 # 50MB in bytes
for file in $(git diff --cached --name-only); do
if [ -f "$file" ]; then
size=$(wc -c < "$file")
if [ $size -gt $MAX_SIZE ]; then
echo "Error: $file is larger than 50MB"
exit 1
fi
fi
doneAlternative to Git LFS: For very large datasets or files that change rarely, consider:
- Storing files in cloud storage (S3, GCS) and referencing them
- Using DVC (Data Version Control) for ML projects
- Git annex for distributed large file storage
GitHub Actions and LFS: Add this to your workflow to use LFS:
- uses: actions/checkout@v4
with:
lfs: true.gitattributes Best Practices: Include common large file types in .gitattributes from the start:
*.psd filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.mov filter=lfs diff=lfs merge=lfs -text
*.pdf filter=lfs diff=lfs merge=lfs -text
*.ai filter=lfs diff=lfs merge=lfs -textDetecting History Issues: Use git-sizer to analyze repository bloat:
brew install git-sizer # or download from GitHub
git-sizer --verbosekex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server
fatal: unable to access: Proxy auto-configuration failed
How to fix 'Proxy auto-configuration failed' in Git
fatal: unable to access: Authentication failed (proxy requires basic auth)
How to fix 'Authentication failed (proxy requires basic auth)' in Git
fatal: unable to access: no_proxy configuration not working
How to fix 'no_proxy configuration not working' in Git
fatal: unable to read tree object in treeless clone
How to fix 'unable to read tree object in treeless clone' in Git