skip to content

Git LFS

The extension that keeps binaries out of your Git history: the commit stores a small pointer file while the real bytes live on an LFS server, swapped in at checkout by clean and smudge filters. Interviewers ask about it whenever a repo carries design assets, models or game content.

on this pageshow

questions

11

With Git LFS, what does a commit actually store for a tracked 300 MB PSD file, and where do the real bytes live?

level: juniorimportance: must knowfreq 55%

answer

  1. a stand-in, not the file
  2. three short text lines
  3. content hash names the object
  4. local cache under .git/lfs
  5. uploaded when you push

basics

~20 s

A Git LFS commit stores a small text pointer holding a spec version, the file's SHA-256 oid and its size; the real bytes sit in the local LFS cache and on the LFS server, swapped in at checkout.

solid answer

~40 s

When a path matches a `filter=lfs` pattern, Git LFS's **clean** filter runs on `git add`: it hashes the content with SHA-256, copies it into `.git/lfs/objects/`, and hands Git a pointer instead. The blob in the commit is three lines — `version https://git-lfs.github.com/spec/v1`, `oid sha256:<64 hex>` and `size <bytes>` — and the specification caps a pointer below 1024 bytes. Nothing is uploaded at commit time: Git LFS's `pre-push` hook sends the referenced objects to the LFS server before Git sends the commits. On checkout the **smudge** filter recognises the pointer, takes the object from the local cache or downloads it, and writes the real file into the working tree. History stays small, and a version of the PSD is downloaded only when a checkout needs it.

code

bash · 7 lines
bash
$ git show HEAD:art/hero.psd
version https://git-lfs.github.com/spec/v1
oid sha256:5eea10d5b561e1692e30ca706e71caaa9848ed05456ed35b1180e4643d6632c2
size 312459264

$ ls .git/lfs/objects/5e/ea/
5eea10d5b561e1692e30ca706e71caaa9848ed05456ed35b1180e4643d6632c2

go deeper

for a junior

Recall the three pointer lines (version, oid sha256, size) and that the real bytes live outside Git's history, in the LFS cache and on the LFS server.

for a middle

Walk through the lifecycle: the clean filter on add writes the cache entry and the pointer, the pre-push hook uploads, and the smudge filter restores the file on checkout.

for a senior

Use the pointer model to diagnose: a text file in place of art means the smudge never ran, and a push without its objects means the pre-push hook is missing.

for a principal

Explain what the pointer buys and costs: a small, fast Git history, against a second store that every clone, mirror and backup must also reach.

## Why large binaries hurt plain Git Git keeps every version of every committed file as an object in the repository, and a normal clone downloads the whole history. That is cheap for source code and painful for art: a 300 MB PSD file saved forty times is forty large objects that every clone, every fork and every backup carries forever, and binary formats such as **PSD** and **FBX** rarely compress or delta well against their previous versions. **Git LFS** (Large File Storage) is an open-source Git extension that keeps those bytes out of Git's history. Git still versions the path, the commit and the tree; only the *content* of tracked files moves to a separate object store. ## What the pointer file contains For a tracked path, the blob Git commits is a **pointer file** defined by the Git LFS specification: | Key | Example value | Meaning | |---|---|---| | `version` | `https://git-lfs.github.com/spec/v1` | Identifies the pointer format. Parsers compare it as a plain string; it is not an address to download from. | | `oid` | `sha256:5eea10d5…6632c2` | Hash method plus the lowercase hexadecimal SHA-256 of the file's content. Only `sha256` is supported. | | `size` | `312459264` | Size of the real file in bytes. | The specification adds a few rules worth knowing: - Each line is `key value` followed by a Unix newline, with a single space between key and value. - `version` always comes first; any other keys follow in **alphabetical order**. - A pointer must be **smaller than 1024 bytes**, including any extension lines. - There is exactly one valid encoding of a pointer for a given file, so pointers are **canonical** and can be compared byte for byte. - The pointer keeps the **executable bit** of the file it replaces. - An **empty file** is its own pointer: empty files pass through Git LFS unchanged. ## Where the real bytes go The swap happens through Git's filter hooks, configured by `git lfs install` and switched on per path by the `filter=lfs` attribute that `git lfs track` writes into `.gitattributes`: 1. **`git add`** — Git runs Git LFS's **clean** filter on the file. It streams the content to a temporary file while computing its SHA-256, moves it into the local cache at `.git/lfs/objects/5e/ea/5eea10d5…` (the first two pairs of hex digits shard the directory), and writes the pointer back to Git, which stores the pointer as the blob. 2. **`git commit`** — records a tree that references the pointer blob. Nothing leaves the machine. 3. **`git push`** — Git LFS's **pre-push hook** works out which LFS objects the pushed commits reference and uploads them to the LFS server *before* Git sends the commits. 4. **Checkout or clone** — Git hands each pointer blob to the **smudge** filter, which recognises the pointer format, takes the object from the local cache or downloads it from the server, and writes the real bytes into the working tree. Content that is not a pointer passes straight through. How the client finds the LFS server and transfers objects is a separate subject from the pointer itself; for this question it is enough that the server is a second store sitting beside the Git remote. ## Seeing it for yourself ```bash $ git show HEAD:art/hero.psd version https://git-lfs.github.com/spec/v1 oid sha256:5eea10d5b561e1692e30ca706e71caaa9848ed05456ed35b1180e4643d6632c2 size 312459264 $ git lfs pointer --file=art/hero.psd ``` `git show` prints the blob exactly as the commit stores it, so you see the pointer, not the image. `git lfs pointer --file=<path>` builds the pointer Git LFS would write for a local file and also prints the **Git blob OID** of that pointer. The two hashes are different things: the `oid` inside the pointer hashes the *content*, while Git's blob id hashes the *pointer text*. ## What a team notices day to day - **Clones stay small.** Git's history holds pointers, and the smudge filter downloads the objects for the files a checkout actually writes, not every historical version. - **A machine without Git LFS sees text files.** With no `lfs` filter configured, Git checks the pointer out as is, so a PSD arrives as a file of roughly 130 bytes starting with the `version` line; `git lfs install` followed by `git lfs pull` fixes it. - **`git diff` shows pointer changes.** Editing a tracked PSD and running `git diff` shows the `oid` and `size` lines changing rather than anything about the image. - **The saving only applies from tracking onwards.** Files committed as plain blobs before the pattern was tracked stay in history as full objects until the history is migrated. The pointer is, in short, a content-addressed reference: a stable, tiny stand-in that Git versions like any other text file, while the bytes it names travel through a separate channel.

  • What does a teammate see if they clone the repository on a machine where Git LFS was never installed?
    Their Git has no `lfs` filter configured, so it checks out each pointer blob as it is: the PSD on disk is a text file of roughly 130 bytes starting with `version https://git-lfs.github.com/spec/v1`. Running `git lfs install` and then `git lfs pull` replaces those pointers with the real files.
  • Is the `oid` in a Git LFS pointer the same as the Git blob id of that path?
    No. The `oid` is the SHA-256 of the file's content and names the object in the LFS store. The Git blob id is Git's hash of the pointer text itself. `git lfs pointer --file=art/hero.psd` prints the pointer Git LFS would write and, separately, the Git blob OID of that pointer.
  • When does the large file actually leave the developer's machine?
    Not on `git add` or `git commit`: the clean filter only writes the object into the local `.git/lfs/objects` cache. The `pre-push` hook that `git lfs install` puts in the repository uploads the objects the pushed commits reference, before Git sends the commits themselves. If that hook was skipped, the commits can reach the server without their objects.

A Git LFS pointer is a cloakroom ticket: the commit keeps only the small numbered ticket, the coat hangs in the cloakroom (the LFS store), and the attendant (the smudge filter) swaps ticket for coat when you check out.

  • The commit stores a compressed copy of the PSD inside Git's object database.
  • The pointer file contains the download URL of the file on the LFS server.
  • git commit uploads the large file to the LFS server.
  • The pointer's oid is the Git blob SHA-1 of the file.
  • Every clone downloads every historical version of every tracked file.
open as a page

With Git LFS, how do you stop a CI job that clones the repository from downloading binaries no build step opens?

level: middleimportance: must knowfreq 44%

basics

~20 s

Set GIT_LFS_SKIP_SMUDGE=1 before cloning so checkout leaves pointer files instead of downloading content, then run git lfs pull with --include for only the paths the build reads. A shallow clone does not reduce LFS downloads.

open as a page

With Git LFS, why does running `git lfs track "*.psd"` after a year of committing PSDs straight into Git leave clones just as large?

level: middleimportance: must knowfreq 38%

basics

~20 s

Tracking only changes how content is cleaned from now on; every PSD committed during that year is still a full blob reachable from history. Shrinking clones needs git lfs migrate import over all refs, which rewrites history.

open as a page

With Git LFS, how do git lfs fetch, git lfs checkout and git lfs pull differ?

level: juniorimportance: should knowfreq 36%

basics

~20 s

git lfs fetch downloads objects into the local LFS store without touching the working copy; git lfs checkout writes content from that store over pointer files without downloading; git lfs pull does both, like fetch followed by checkout.

open as a page

With Git LFS, what do `git lfs install` and `git lfs track "*.psd"` each set up, and what does the resulting .gitattributes line mean?

level: juniorimportance: should knowfreq 42%

basics

~20 s

git lfs install configures the lfs clean, smudge and process filters (globally by default) and installs Git LFS's hooks; git lfs track writes a filter=lfs diff=lfs merge=lfs -text line into .gitattributes, which must be committed.

open as a page

With Git LFS file locking, how do you stop two artists overwriting each other's work on the same binary scene file?

level: middleimportance: should knowfreq 30%

basics

~20 s

Mark the file type lockable and have artists run git lfs lock before editing. The LFS server records one owner, other clones keep the file read-only, and with lock verification on, a push changing someone else's locked file is refused.

open as a page

With Git LFS, how do `git lfs ls-files`, `status` and `fsck --pointers` reveal a tracked FBX committed as a plain Git blob?

level: middleimportance: should knowfreq 24%

basics

~20 s

git lfs ls-files omits it, since it lists only pointers; git lfs status labels each change Git or LFS; git lfs fsck --pointers flags files that should be pointers. Renormalizing and committing fixes the tip.

open as a page

On a host that meters Git LFS, why does storage keep growing after files are deleted, and what drives bandwidth use?

level: seniorimportance: should knowfreq 24%

basics

~20 s

Each pushed LFS version is stored whole and stays after files are deleted; on GitHub only deleting the repository or a support purge frees it. Every download, CI and forks included, counts against the owner's bandwidth.

open as a page

With Git LFS, what does `git lfs migrate import --everything --include="*.psd,*.fbx"` rewrite, and what does that cost everyone who already cloned the repository?

level: seniorimportance: should knowfreq 22%

basics

~20 s

It rewrites every commit, reachable from any local or remote ref, from the first matching file onwards, giving new IDs, and moves only local refs; you force-push, and every existing clone must move onto the new history.

open as a page

With Git LFS, how does the client find its LFS server and use the Batch API to move an object?

level: seniorimportance: nice to knowfreq 12%

basics

~10 s

Git LFS appends .git/info/lfs to the remote URL unless lfs.url or remote.<name>.lfsurl overrides it, then POSTs to <endpoint>/objects/batch naming the operation and objects; the response gives each object a URL for the actual transfer.

open as a page

With Git LFS, what does git lfs prune delete, and what keeps a local object from being pruned?

level: seniorimportance: nice to knowfreq 16%

basics

~20 s

git lfs prune deletes local copies in the LFS store that nothing current needs. It keeps objects for the checkout, stashes, worktrees, unpushed commits and recent branches, widened by lfs.pruneoffsetdays. It never frees server storage.

open as a page