Git warns when you attempt to commit files larger than 50 MB, as large binary files can bloat repositories and slow down operations. This warning recommends using Git Large File Storage (LFS) for better handling of large assets.
This warning appears when Git detects you are trying to add or commit a file that exceeds the recommended size threshold. Git is optimized for tracking text-based source code, not large binary files like videos, datasets, or compiled artifacts. When large files are committed directly into Git history, they are stored in their entirety with every clone, causing repository bloat and performance degradation. Git hosting platforms enforce stricter limits: GitHub warns at 50 MB and blocks files over 100 MB, while GitLab typically rejects files larger than 100 MB. Even if you delete a large file in a subsequent commit, it remains in the repository history, continuing to impact performance until the history is rewritten. The warning is Git's way of suggesting you use Git Large File Storage (LFS), which stores large files externally while keeping lightweight pointer files in your repository. This keeps your repository fast and manageable while still versioning large assets.
Identify the large files in your staging area or working directory:
# Show sizes of files in staging area
git ls-files -s | awk '{if($4) print $4}' | xargs ls -lh
# Find large files in current directory (over 50MB)
find . -type f -size +50M -not -path "*/.git/*"
# Check size of files about to be committed
git diff --cached --name-only | xargs ls -lhIf you haven't committed yet, remove the large file from staging:
# Unstage the specific large file
git reset HEAD large_file.bin
# Or unstage all files
git reset HEADPrevent accidentally committing the file again:
# Add specific file to .gitignore
echo "large_file.bin" >> .gitignore
# Or ignore by pattern
echo "*.bin" >> .gitignore
echo "*.mp4" >> .gitignore
echo "dist/" >> .gitignore
# Commit the .gitignore update
git add .gitignore
git commit -m "Add large files to gitignore"For files that need to be versioned but are too large:
# Install Git LFS (macOS)
brew install git-lfs
# Install Git LFS (Ubuntu/Debian)
sudo apt-get install git-lfs
# Install Git LFS (Windows)
# Download from https://git-lfs.com/
# Initialize Git LFS in your repository
git lfs install
# Track specific file types
git lfs track "*.bin"
git lfs track "*.mp4"
git lfs track "*.zip"
# This creates/updates .gitattributes
git add .gitattributes
git commit -m "Configure Git LFS for large files"Once LFS is configured, add your large files:
# Add the large file (now tracked by LFS)
git add large_file.bin
git commit -m "Add large file via LFS"
# Verify it's tracked by LFS
git lfs ls-files
# Push to remote (LFS files uploaded separately)
git push origin mainIf you already committed the large file before setting up LFS:
# Migrate existing files to LFS (rewrites history)
git lfs migrate import --include="*.bin" --everything
# For specific file
git lfs migrate import --include="large_file.bin" --everything
# Force push (coordinate with team first!)
git push --force origin mainWarning: This rewrites Git history. All team members will need to re-clone or rebase their branches.
Alternative strategies for large files:
Use GitHub Releases or GitLab Packages: For distributing large compiled artifacts, binary releases, or installer packages, use your platform's release mechanism instead of committing them to the repository.
External storage: Store large assets in cloud storage (S3, Google Cloud Storage, Azure Blob) and reference them via URLs or download scripts. This is ideal for datasets, media libraries, or rarely-changing binaries.
Git history cleanup: If large files are deep in your history and causing issues, consider using git filter-repo (recommended) or BFG Repo-Cleaner to remove them entirely. Note that git filter-branch is deprecated. Always coordinate with your team before rewriting shared history:
# Install git-filter-repo
pip install git-filter-repo
# Remove all *.bin files from entire history
git filter-repo --path-glob "*.bin" --invert-paths
# Force push (all team members must re-clone)
git push --force origin mainRepository size limits: GitHub recommends repositories under 1 GB, strongly recommends under 5 GB. GitLab and Bitbucket have similar guidelines. Git LFS allows files up to 2 GB on GitHub. Consider monorepo strategies or splitting large repositories if approaching these limits.
Pre-commit hooks: Install pre-commit hooks to prevent large files from being staged in the first place. This provides immediate feedback and prevents the warning entirely.
kex_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