How to use Git Large File Storage (LFS)

Git Large File Storage (LFS) is an open-source extension for Git that allows you to manage large files with Git more efficiently. This guide provides a comprehensive overview of Git LFS, including what it is, how to install and configure it, and how to use it in your projects.

What is Git LFS?

Git Large File Storage (LFS) replaces large files such as audio samples, videos, datasets, and graphics with text pointers inside Git, while storing the file contents on a remote server. This setup allows you to work with large files without overloading the Git repository.

Installing Git LFS

To start using Git LFS, you need to install it on your machine. Here’s how to install Git LFS on various operating systems:

Windows and macOS

Git LFS can be installed via a binary or through package managers like Homebrew for macOS:

brew install git-lfs

Linux (including Ubuntu)

On Ubuntu, you can install Git LFS using curl:

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs

Post-installation setup

After installing Git LFS, you need to configure it by running the install command:

git lfs install

This command needs to be run once per user account. It sets up Git LFS in your Git configuration.

Configuring Git LFS

Tracking large files

To track large files with Git LFS, use the git lfs track command followed by the file types you want to track. For example, to track all .mp4 video files, you would use:

git lfs track "*.mp4"

This command will update your .gitattributes file, marking the specified patterns for LFS tracking.

Viewing tracked files

To see what patterns and files are currently being tracked by LFS, you can run:

git lfs ls-files

Using Git LFS

Adding files

Once you have configured Git LFS to track certain file types, you can add files as you would normally:

git add file.mp4
git commit -m "Add large file"

When you use Git Large File Storage (LFS) and perform the actions described—adding and committing a large file like file.mp4—here's what happens under the hood:

1. File tracking: When you execute git add file.mp4, Git LFS intercepts this operation because file.mp4 matches a pattern specified in the .gitattributes file for LFS tracking. Git LFS then replaces the large file in the repository with a small, lightweight text pointer. This pointer references the large file but does not contain its actual data.

2. Storing the file: Instead of storing the large file in the Git repository, Git LFS uploads the actual binary content of file.mp4 to a separate LFS storage area configured for your repository. This storage is usually on the same platform as your Git repository (like GitHub, GitLab, etc.), but it handles large files separately from your standard Git storage to avoid bloating the repository with large binary files.

3. Committing the change: When you commit the change with git commit -m "Add large file", the commit records the pointer file instead of the actual large file. The commit log will show that file.mp4 was added, but the repository only contains the pointer to where the actual data is stored in the LFS cache.

4. Pushing changes: When you push your changes to the remote repository, git push sends both the commits and any necessary Git LFS objects to their respective stores. The pointers go into the Git repository, while the large file data stored by LFS is transferred to the LFS store. Collaborators pulling the changes will receive the pointer file and then automatically download the large file from LFS storage if they have LFS installed and configured.

This setup with Git LFS enables efficient management of large files by keeping the repository size small and making cloning and fetching operations faster while still versioning large files alongside your source code.

Pushing and pulling files

When you push to a remote repository, Git LFS files are transferred to a separate Git LFS storage. Use the standard push command:

git push origin main

Similarly, when you clone a repository or pull updates, Git LFS files are downloaded as needed:

git clone <repository-url>
git pull

Best practices

• Use Git LFS for files that exceed 100 MB: This is particularly important for repositories on platforms like GitHub, which have strict limits on file sizes.
• Regularly prune LFS cache to save space: You can use git lfs prune to remove old objects from your local LFS cache.
• Be cautious with bandwidth and storage: Although Git LFS handles large files, it still uses bandwidth and storage, which might be limited depending on your Git server or hosting service.

For further reading on Git LFS see the official documentation.