Skip to content
Tutorials Center
My learning

Topics

Lesson 55 of 78 ยท Customizing and Automating Git

Git LFS Workflows

Use Git LFS in practice: how pointers and the LFS store work, tracking patterns, migrating existing history, partial fetches, file locking, hosting quotas and CI.

Git is wonderful for source code and miserable for big binaries. Every version of a 200 MB design file is stored in full, every clone downloads every version, and a repository that was nimble last year now takes ten minutes to clone. Git LFS (Large File Storage) fixes this by keeping the large files outside the repository and storing only tiny text pointers in history. The earlier lesson .gitattributes, Line Endings and Large Files introduced the idea. Here you will see how the mechanism works, then walk through the daily workflow: tracking, committing, migrating an existing repository, fetching only what you need, locking and hosting.

The git lfs command is not installed in the sandbox and there is no LFS server to talk to, so the real commands appear as read-only transcripts. The runnable examples use plain Git to build a miniature LFS of our own, so the pointer, the store and the filters become something you have seen with your own eyes.

How LFS works

LFS plugs into three standard Git features: .gitattributes selects which paths are handled, a clean filter converts a file to a pointer when you git add, and a smudge filter converts the pointer back when a file is checked out. The real content travels separately, at push and fetch time, to the LFS store of your hosting service.

sequenceDiagram
  participant W as Working tree
  participant G as Git repository
  participant S as LFS store (server)
  W->>G: git add (clean filter makes a pointer)
  W->>S: git push (uploads the real file)
  G-->>W: git checkout (smudge filter reads the pointer)
  S-->>W: downloads the real file

History holds only pointers; the big content is uploaded and downloaded on demand.

A pointer is a three-line text file: the spec version, the SHA-256 of the content (oid) and its size in bytes. Everything else is derived from those lines.

A miniature LFS you can run

This example implements the same idea with two shell scripts. The clean script saves the content under its SHA-256 name in a local folder and prints a pointer. The smudge script reads a pointer and prints the stored content. Then we ask Git what it really stored.

Bash Clean and smudge filters, the LFS way

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The 3,000-byte file became a three-line blob of 129 bytes. The store holds one file named after the hash of its content. After deleting model.dat and checking it out, the smudge filter looked up the pointer's oid and restored all 3,000 bytes, and git status stays clean. That is precisely what git lfs does, with the extras of talking to a server, caching, batching and progress bars.

Tracking files

On a real machine, the daily workflow is a few commands. Run git lfs install once per machine to register the filters and hooks. Then tell LFS which patterns to manage:

CONSOLE
$ git lfs install
Updated Git hooks.
Git LFS initialized.
$ git lfs track "*.psd" "assets/video/*.mp4"
Tracking "*.psd"
Tracking "assets/video/*.mp4"
$ git add .gitattributes
$ git add design/logo.psd
$ git commit -m "Track Photoshop and video files with LFS"
$ git lfs ls-files
a1b2c3d4e5 * design/logo.psd
$ git push origin main
Uploading LFS objects: 100% (1/1), 48 MB | 12 MB/s, done.

git lfs track does not move anything. It only writes lines to .gitattributes. Commit that file before the big files, or the files will be stored normally. You can check the effect of the rules without LFS installed by asking Git which attributes apply:

Bash What does .gitattributes say about each path?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

check-attr reports filter: lfs for the three tracked paths, and lockable: set for the .mov rule only. For notes.txt both attributes are unspecified, so it is stored as ordinary text. The -text part tells Git not to touch line endings in these files. Patterns follow the usual .gitattributes rules, so choose them by file type (*.psd) or folder (assets/video/*).

A good rule of thumb is to track binary assets that change and are larger than a few hundred kilobytes: design files, video, audio, datasets, game assets, compiled libraries you cannot rebuild. Do not track things you can regenerate (put them in .gitignore) and do not track small text files.

Moving existing files to LFS

The most common mistake is adopting LFS after the big files are already in history. Tracking them now only affects new commits; the old blobs stay in the repository and in every clone. To convert history you must rewrite it with git lfs migrate.

First, find out what is large. This works with plain Git, so try it:

Bash Find the biggest blobs in history

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The list shows the 30,000-byte and 20,000-byte versions of asset1.bin as two separate blobs. Even though only the newest exists in the working tree, the old one is still part of every clone. This is the cost LFS removes.

The migration commands are read-only here, but this is how they look:

CONSOLE
$ git lfs migrate info --everything --above=1MB
migrate: Sorting commits: ..., done.
*.psd   312 MB   14/14 files(s)   100%
*.mp4   1.2 GB    3/3 files(s)    100%

$ git lfs migrate import --include="*.psd,*.mp4" --everything
migrate: Rewriting commits: 100% (212/212), done.

info reports sizes per extension and changes nothing. import --everything rewrites every branch and tag so the matching files become pointers. Because every commit hash changes, treat it as a history rewrite: agree on a date with the team, push with --force-with-lease, and have everyone re-clone (or reset hard to the new branches). Read Amending, Splitting and Rewriting Commits before you try it. Afterwards, the old objects only disappear from the server when the hosting service runs garbage collection, and from your clone after git reflog expire and git gc (Performance and Maintenance).

Working with LFS files

Once set up, LFS is mostly invisible. A few commands help when something looks odd:

CONSOLE
$ git lfs ls-files            # files that are stored in LFS in this checkout
$ git lfs status              # which LFS files are staged or modified
$ git lfs pointer --file=a.psd  # print the pointer for a file
$ git lfs fsck                # verify local LFS objects
$ git lfs prune               # delete old local LFS files you no longer need

When you check out a file and see a short text starting with version https://git-lfs.github.com/spec/v1, the pointer was not replaced, because LFS is not installed or the download did not run. Install git-lfs, then run git lfs pull.

Cloning less

A large LFS repository can still be heavy if you download every file on every clone. Three techniques help:

  • Skip downloads during clone, then fetch what you need: GIT_LFS_SKIP_SMUDGE=1 git clone <url> leaves pointers in the working tree. Later git lfs pull --include="design/*.psd" downloads only a folder.
  • Limit what is fetched by default with lfs.fetchinclude and lfs.fetchexclude in the repository config, for example excluding assets/video/* on a build server.
  • Shallow and partial clones reduce Git history; see Sparse Checkout and Large Repositories. They combine well with LFS.

By default LFS downloads only the files for the commit you check out, not every historical version, which is the main saving.

Locking

Binary files cannot be merged. If two designers edit the same .psd, one of them loses work. LFS supports file locking: mark a pattern lockable (git lfs track --lockable "*.psd"), and the file is read-only in the working tree until you lock it:

CONSOLE
$ git lfs lock design/logo.psd
Locked design/logo.psd
$ git lfs locks
design/logo.psd    Ada    ID:42
$ git lfs unlock design/logo.psd

Locks are stored on the LFS server, so they work across machines and need a hosting service that supports them. GitHub, GitLab and Bitbucket do.

Hosting, limits and cost

LFS needs a server that speaks the LFS API. GitHub, GitLab, Bitbucket and Gitea provide one, usually with storage and monthly bandwidth quotas on free plans, and paid add-ons beyond that. A few practical consequences:

  • Forks and pull requests. A fork may count against its owner's quota, and a push that references LFS objects the server does not have fails with an error about missing objects. Run git lfs push --all origin to upload them.
  • The .lfsconfig file (committed) can point to a custom LFS endpoint, so a self-hosted store can serve a project hosted elsewhere.
  • Deleting is hard. Because history still references old objects, they cost storage until the host runs cleanup. Another reason to decide early what belongs in LFS.
  • Alternatives exist for very large data: object storage with content-addressed tools, or dedicated artifact repositories. LFS is the simplest choice when the files belong to the code.

LFS in continuous integration

A CI job that checks out your repository needs LFS too, or it will build with pointer files. With GitHub Actions, enable it on the checkout step, as shown in GitHub Actions: CI for Your Repository:

YAML
steps:
  - uses: actions/checkout@v4
    with:
      lfs: true

On other servers, install git-lfs in the image and run git lfs pull after checkout. Cache the LFS store between runs when the files are big, and skip LFS on jobs that do not need the assets (a linting job, for instance) to save bandwidth.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does Git store in a commit for a file tracked by LFS?

    The clean filter replaces the content with a three-line pointer. The real content is uploaded to the LFS store.
  2. 2. You already committed several large videos last year. After running git lfs track '*.mp4' they are still in every clone. Why?

    git lfs track only edits .gitattributes. Old commits still contain the real blobs until you rewrite history, for example with git lfs migrate import.
  3. 3. A teammate sees a file that contains three lines starting with 'version https://git-lfs.github.com/spec/v1'. What is the most likely cause?

    That text is the pointer. When the smudge filter does not run or the download is skipped, the pointer stays in the working tree.
  4. 4. Which setting lets a CI job downloading your repository get real LFS files with GitHub's checkout action?

    The checkout action downloads LFS objects only when lfs is set to true.
  5. 5. Why mark a file type as lockable?

    Locks give a person exclusive editing rights to a file stored on the LFS server, avoiding unmergeable conflicts.

Summary

  • LFS stores a tiny pointer (version, oid, size) in Git and keeps the real content in a separate store, using .gitattributes and clean/smudge filters.
  • git lfs install once per machine; git lfs track "<pattern>" writes .gitattributes; commit that file before the large files.
  • Existing large files need git lfs migrate import, which rewrites history: coordinate with the team.
  • Reduce downloads with GIT_LFS_SKIP_SMUDGE, git lfs pull --include and lfs.fetchinclude.
  • lockable patterns plus git lfs lock protect binary files from concurrent edits.
  • Check hosting quotas, and enable LFS in CI checkouts.

Next: GitHub Basics