[github, git-lfs, large files, versioning, organizing]


Work with Large Files on GitHub

Overview

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.

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:

./install.sh
  • Once installed, set up LFS for your account:
git lfs install

If it was successful, you should see Git LFS initialized.

Usage

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.