What Is Git LFS? Managing Large Files in Git

Git is designed to track source code efficiently, but large binaries such as videos, datasets, and design files can make a repository slow to clone and expensive to store. Git Large File Storage (Git LFS) keeps those file contents outside ordinary Git objects while preserving a versioned pointer in the repository. This guide explains how that works, how to set it up, and when migration is needed.

Practice Git workflows →

What Git LFS does

Without LFS, Git stores each committed version of a file in its object database. This works well for text, which Git can compare and compress, but changing a large binary often means storing another large object. Over time, the repository can grow even if the latest copy of the file is small or has been deleted.

With LFS, Git commits a small pointer file that identifies the content, size, and SHA-256 object ID. The actual content is stored by an LFS server, commonly the hosting provider. Git still versions the pointer, so checking out a commit retrieves the corresponding large file when LFS is installed and the server has it.

When to use Git LFS

Consider LFS for large files that need to live alongside the project and change over time, including:

Video, audio, and other media assets.
Design source files, 3D models, and compiled binary assets.
Datasets or archives that the team intentionally versions.

LFS is not a way to avoid all hosting limits: providers may impose file-size, bandwidth, or storage quotas. For frequently changing datasets, generated build output, or files that do not belong in source control, use an artifact or object-storage service instead. Check your host's LFS limits before moving a large collection.

Set up Git LFS and track files

Install Git LFS using the instructions for your operating system, then initialize it for your user account:

git lfs install

From the repository, choose patterns that match the large files you intend to store. For example, to track Photoshop files:

git lfs track "*.psd"
git add .gitattributes
git add design/homepage.psd
git commit -m "Track homepage design with Git LFS"
git push

The tracking rule is saved in .gitattributes; commit that file so teammates use the same rules. The pattern applies to files added or re-added after tracking is configured. Confirm a file is tracked with git lfs ls-files. If other developers clone the repository, they should install Git LFS before checkout so Git can download the actual file contents.

A large file is already committed: what now?

Adding an LFS tracking rule does not convert an older Git commit. If a large file is already in history, future versions may be stored by LFS, but the original Git blob remains and still contributes to repository size. For an active file that needs to be moved out of history, Git LFS includes a migration command:

git lfs migrate info --include="*.psd"
git lfs migrate import --include="*.psd" --everything

Migration rewrites commits and changes their IDs. Treat it as a coordinated history rewrite: make a verified backup, agree on the patterns and branches to migrate, and coordinate with every collaborator before updating the remote. A force push may be required, and collaborators may need to re-clone or carefully realign their local branches. Consult the current Git LFS documentation for migration options and your hosting provider's procedure.

If the file contains a password, API key, or other sensitive information, removing it from history is not enough: revoke or rotate the exposed credential first. LFS is for large-file storage, not secret storage.

Git LFS FAQ

Does Git LFS make my repository smaller?

It can keep large file contents out of ordinary Git history for commits made after LFS tracking is configured. Existing blobs remain until you migrate or otherwise rewrite the history that contains them.

Can I use Git LFS without GitHub?

Yes. Git LFS works with hosting services that provide an LFS server. Configure the remote and authentication according to that provider.

What happens if a teammate does not have Git LFS installed?

They may see pointer text instead of the large file contents, and their Git client may show an LFS warning. Installing Git LFS and checking out the files again lets the client fetch their contents.