GitHub limits the size of files allowed in repositories. It warns you if you’re trying to push a 50MB file, and completely stops you if the push exceed 100MB.
However, even if it didn’t stop you, versioning large files would be very impractical. That’s because a repository contains every version of every file – that’s the point of versioning, right? Having multiple versions of large files cloned locally can become expensive in terms of disk space and fetch time.
The solution? Use Git LFS, an open-source Git extension for “large file storage”. In short, it allows you to version large files while saving disk space and cloning time, using the same Git workflow that you’re used to. It does not keep all your project’s data locally. It only provides the version you actually need in your checked out revision.
When you mark a file as LFS file, the extension replaces the actual large file with a small pointer on your PC. The actual files are located on the remote server and only the pulled actual files are stored in a local cache. In other words, when you
pull to your local repository, the pointer is replaced with the actual file.
Check out this video for a brief explanation on how Git LFS works.
Install Git LFS
Make sure that Git is already installed.
- Go to git-lfs.github.com and download directly. Or, if you use Brew:
brew install git-lfs
If you used Brew, go to the next step. If you downloaded directly from the website, open the terminal and change the current working directory to the downloaded and unzipped folder of Git LFS. Then, install:
- Once installed, set up LFS for your account:
git lfs install
If it was successful, you should see
Git LFS initialized.
Git LFS doesn’t do anything autonomously for you. You need to explicitly tell it which files to track.
git lfs track "largefile.png"
Or, to track a file type (if you don’t want to manually specify every single file you wish to track):
git lfs track "*.png"
!!! warning “Be careful” Do not forget the quotes around your file name!
Now you can resume your usual Git workflow. You just need to make sure to track the
.gitattributes file too.
git add .gitattributes
Simply add your file(s), commit and push as you’d normally do!
git add largefile.png git commit -m "Add large file" git push origin master
Advanced use cases
You can follow this tutorial by Atlassian for more advanced use cases, like moving a LFS repository between hosts or deleting local LFS files.