skip to content

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

level: juniorimportance: should knowfreq 36%

answer

  1. downloading versus writing files
  2. the local object store
  3. which one touches the network
  4. recent branches widen the scope

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.

solid answer

~40 s

`git lfs fetch` downloads LFS objects for the current ref, or refs you name, from the remote into the local store under `.git/lfs/objects`; the working tree is untouched. `git lfs checkout` does the other half: it replaces pointer files in the working tree with content already in the local store, downloads nothing, and never overwrites files you have modified. `git lfs pull` is generally fetch followed by checkout, which is what you run when files show up as small pointer text files, for example after a clone that skipped LFS downloads. Fetch and pull accept `--include`/`--exclude` path filters, checkout takes glob patterns, and `git lfs fetch --recent` also downloads objects for recently changed branches so later checkouts work offline.

go deeper

for a junior

Recall the split: fetch downloads, checkout writes files from the local store, pull does both. Pointer text in a file means content is missing.

for a middle

Explain the local LFS store, the default ref and remote fetch uses, and how --recent and path filters change what is downloaded.

for a senior

Pick the right command for offline work, partial downloads and mirroring, and explain why per-file smudge on clone is slower than a batched pull.

for a principal

Set team conventions for which objects developers and agents keep locally, balancing disk use against re-download time and bandwidth.

## Two stores, two steps A Git LFS repository has two places where content lives on your machine: - **Git's object database**, which holds commits, trees and the small **pointer files** for LFS-tracked paths; - the **local LFS store**, usually `.git/lfs/objects`, which holds the large objects themselves, named by their SHA-256. Putting a real file in your working tree therefore takes two steps: **download** the object from the LFS server into the local store, then **write** it over the pointer in the working tree. A normal `git clone` or `git checkout` does both automatically, file by file, through the LFS smudge step. The three commands below let you do the steps yourself. ## The three commands | Command | Downloads from the server? | Changes the working tree? | Typical use | |---|---|---|---| | `git lfs fetch` | yes | no | prefetch objects, for example before going offline | | `git lfs checkout` | no | yes, from the local store | replace pointers once objects are present | | `git lfs pull` | yes | yes | fix a clone that holds pointers; the usual one-liner | `git lfs pull` is generally equivalent to `git lfs fetch` followed by `git lfs checkout`. It downloads in batches and in parallel, which is why it is faster than leaving a clone to download one file at a time. ## When you reach for each - **Files show up as three-line text files** (a version line, an `oid` line and a `size` line): content is missing. Run `git lfs pull`. If the objects are already in the local store, `git lfs checkout` is enough. - **Preparing to work offline**: `git lfs fetch --recent` downloads objects for recently changed branches as well, so later checkouts work without the network. - **A clone that deliberately skipped LFS downloads**, as CI jobs often do: `git lfs pull` with path filters downloads only what is needed. - **Mirroring or backing up every version**: `git lfs fetch --all` downloads objects for every commit reachable from the refs you name, or from all refs. ## Choosing what to download By default `git lfs fetch` and `git lfs pull` work on the **currently checked-out ref** and the **default remote** (the tracked branch's remote, otherwise `origin`). You can widen or narrow that: 1. **Name refs**: `git lfs fetch origin main develop` fetches objects for those refs. 2. **Add recent work**: `--recent`, or `lfs.fetchrecentalways`, adds branches with commits in the last `lfs.fetchrecentrefsdays` days (default 7), including remote branches by default, and older commits within `lfs.fetchrecentcommitsdays` (default 0). 3. **Filter paths**: `--include`/`-I` and `--exclude`/`-X`, or the `lfs.fetchinclude` and `lfs.fetchexclude` settings, restrict downloads by path with gitignore-style wildcards. `git lfs checkout` instead takes glob patterns as arguments. 4. **Everything**: `--all` covers every reachable commit. It cannot be combined with `--recent` or path filters, and it ignores configured filters so that nothing is missed. ## A worked session A developer clones a repository on a slow connection with LFS downloads skipped, works on code for a while, then needs the level files: 1. `git lfs fetch origin main` downloads the objects for `main` into the local store; the working tree still shows pointers. 2. `git lfs checkout levels` writes the downloaded content over the pointers under `levels/`, with no further network traffic. 3. Later, after switching to a teammate's branch, `git lfs pull` fetches that branch's objects and writes them in one step. 4. Before a flight, `git lfs fetch --recent` stocks the store with objects for recently active branches, so checkouts work offline. ## Common traps - **Fetch alone changes nothing you can see.** The objects arrive in `.git/lfs/objects`, but the working tree still holds pointers until checkout runs. - **Checkout never downloads.** If an object is missing locally, `git lfs checkout` leaves the pointer in place. - **Your edits are safe.** `git lfs checkout` only replaces files that are missing or still contain the matching pointer; modified files are never overwritten. - **History is not fetched by default.** Older versions are downloaded only when you ask with refs, `--recent` or `--all`, which keeps everyday fetches small.

  • When would you run git lfs fetch on its own?
    When you want objects locally without changing the working tree: `git lfs fetch --recent` before travelling, so switching to a recently active branch works offline; fetching a colleague's branch by name before checking it out; or `git lfs fetch --all` to mirror every version for a backup or migration.
  • A teammate sees three-line text files where images should be. What happened, and which command fixes it?
    Their working tree holds pointers, so the content was never downloaded: Git LFS was not installed when they cloned, the clone skipped LFS downloads on purpose, or downloads failed. `git lfs pull` downloads and writes the content; if the objects are already in the local store, `git lfs checkout` alone is enough.

  • git lfs fetch updates the working copy with the downloaded files.
  • git lfs checkout downloads any objects that are missing locally.
  • git lfs fetch downloads every version of every LFS file by default.
  • git lfs checkout overwrites local edits to tracked binaries.