Managing large files in Git repositories can be tricky. By default, Git isn’t designed for large binary files (like ZIPs, videos, datasets). If you try to commit a file over 100 MB, you’ll likely hit a size limit, especially on platforms like GitLab.
This guide will walk you through the proper way to add large files to GitLab using Git Large File Storage (Git LFS) — keeping your repo clean and efficient.
🚫 Why You Shouldn’t Commit Large Files Directly
Before we dive in, here’s why you shouldn’t just push a large file directly:
- Git history bloats and slows down.
- GitLab may reject files >100 MB (similar to GitHub).
- Every clone/download becomes painful for collaborators.
- No version control benefit for binary files.
✅ What is Git LFS?
Git Large File Storage (Git LFS) replaces large files such as audio, video, zip files, and other binaries with lightweight references in your Git history. The actual file content is stored on a separate server.
🚀 Step-by-Step: Add Large Files to GitLab using Git LFS
1. Install Git LFS
Install Git LFS based on your operating system:
- macOS (Homebrew):
brew install git-lfs - Ubuntu/Debian:
sudo apt install git-lfs - Windows:
Download and install from git-lfs.github.com
2. Initialize Git LFS in Your Repository
Inside your Git repo folder:
git lfs install
This sets up Git LFS for your system and repository.
3. Track Specific File Types
Tell Git LFS which files to manage. For example, to track ZIP and MP4 files:
git lfs track "*.zip"
git lfs track "*.mp4"
This creates a .gitattributes file with tracking rules.
4. Add and Commit the Large Files
Now add and commit as usual:
git add .gitattributes
git add large-video.mp4
git commit -m "Add large video using Git LFS"
git push origin main
✅ Git stores a small pointer in the repo, and LFS manages the large file behind the scenes.
🧩 What If You Can’t Use Git LFS?
If you absolutely must push a large file without Git LFS (not recommended):
Increase Git Client Buffer:
git config --global http.postBuffer 524288000
Increase GitLab Server Upload Limit (Admin Access Required):
Edit /etc/gitlab/gitlab.rb and add:
nginx['client_max_body_size'] = '500m'
Then reconfigure:
sudo gitlab-ctl reconfigure
⚠️ Warning: This approach can bloat the repository and cause long-term issues.
| Scenario | Solution |
|---|---|
| Files < 100MB | Use regular git add |
| Files > 100MB | Use Git LFS |
| Gigantic datasets | Use external storage (S3, Google Drive, etc.) and link in README |
🏁 Conclusion
Using Git LFS is the best way to manage large files in GitLab without bloating your repo or running into errors. It’s fast, reliable, and built for this purpose.
