Lorixen.
EN

Git repo too big? Move design and video files to Git LFS

Short answer: If your Git repository has become slow to clone because it holds design files, videos or large images, move those file types to Git Large File Storage (Git LFS). LFS keeps a small text pointer in Git and stores the real file on a separate server. Set it up with git lfs track before adding big files. If they're already in history, use git lfs migrate import, but note that this rewrites history, so plan it with your team.

Why big files hurt a Git repository

Git keeps every version of every file forever. That's ideal for code, which is small text that compresses well and changes in small pieces. It's a poor fit for a 300 MB product video or a layered design file that changes completely each time someone saves. Every edit adds a full new copy to history, and everyone who clones the repository downloads all of them.

The signs are familiar to small teams that keep a website, app and marketing assets together:

  • A fresh clone takes many minutes, even on fast connections.
  • CI jobs spend more time checking out the code than running tests.
  • Pushes fail or warn about file size.
  • New team members are told to "leave it running overnight".

GitHub's own documentation sets hard edges here: Git warns when you add a file larger than 50 MiB, and GitHub blocks files larger than 100 MiB, pointing users to Git LFS for anything beyond that. Other hosts have their own limits, but the underlying problem is the same everywhere.

How Git LFS works

The Git LFS project describes it simply: it 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. The pointer is a few lines naming the file's hash and size.

When you clone or check out, the LFS client downloads only the versions you need for the commit you're on. Old versions stay on the server until someone actually asks for them. Your history stays small, and day-to-day work feels like normal Git.

Setting it up for new files

  1. Install the Git LFS client on every machine and CI runner that will work with the repository, then run git lfs install once per user account.
  2. Choose file types to track, for example: git lfs track "*.psd", git lfs track "*.mp4", git lfs track "*.sketch".
  3. Commit the .gitattributes file that the track command writes. The Git LFS site stresses this step: defining tracked types doesn't, by itself, convert files that are already in history.
  4. Add and commit files as usual. From now on, matching files go to LFS automatically.

Good candidates for LFS are binary files that are large and change as whole units: video, audio, raw photos, design source files, 3D models, large PDFs and compiled assets you must version. Keep ordinary source code, small icons and text files in normal Git.

Moving files that are already in history

If the big files were committed months ago, tracking them now won't shrink the repository, because the old copies are still in history. The git lfs migrate command handles this. Its import mode converts Git files to LFS objects across history; its info mode summarises file sizes by type so you can see what's taking space first.

The command's documentation is clear that import and export modes are generally destructive: they rewrite history and produce new commit hashes. In practice that means:

  • Agree a quiet time with everyone who uses the repository.
  • Make a full backup or mirror before you start.
  • Ask everyone to push their work and pause new commits.
  • Run the migration, then force-push the rewritten branches.
  • Have everyone re-clone, rather than pulling, to avoid mixing old and new history.
  • Update open pull requests, which may need rebasing onto the new history.

The docs also describe a "no-rewrite" import option that converts files in a new commit without touching history. It's less disruptive but leaves old copies in place, so it doesn't make clones smaller.

Things to plan for

  • Storage and bandwidth. LFS objects count against your hosting plan's storage and transfer allowance. Check your provider's current terms before moving gigabytes of video.
  • CI configuration. Make sure your build pipeline fetches LFS files only when a job needs them. Many pipelines can skip LFS downloads for test jobs that never touch assets.
  • Locking. Binary files can't be merged. Git LFS supports file locking, so a designer can lock a file while editing and avoid two people overwriting each other.
  • Alternatives. If assets don't need version history alongside the code, a shared drive or a digital asset manager may be simpler. LFS shines when assets must change in step with the code that uses them.

A worked example

Consider a hypothetical Galway app studio whose repository had grown to several gigabytes, mostly marketing videos and design files. A new developer's first clone took most of a morning. The team ran git lfs migrate info and found that video and design files made up nearly all of it. On a Friday afternoon they backed up the repository, ran an import migration for those types, force-pushed and asked everyone to re-clone on Monday. Clones became quick again, and the designers started using LFS locks on shared files.

FAQ

Can I use Git LFS with any Git host?

Most major hosts support it, but limits and pricing differ. Check your host's documentation before migrating.

What happens if someone without LFS installed clones the repository?

They'll see pointer files instead of real content. Make installing the client part of your onboarding notes.

Will LFS fix a repository that's already huge?

Only if you migrate history. Tracking file types from now on prevents future growth but doesn't remove old copies.

Should images for my website go into LFS?

Small optimised web images are usually fine in normal Git. Large originals and source files are better candidates.

If your repository has become slow and you're not sure what to move, describe how your team works with files and we'll help plan the change.

Sources

WhatsAppBook a call