README
¶
git-lfs
git-lfs implements git lfs pull by reading pointers from a filtered Git
tree, downloading missing objects concurrently, and using the standard Git
LFS object layout.
Install
Install the latest release:
go install blake.io/git-lfs@latest
Make sure the Go install directory is on PATH. It is $(go env GOBIN) when
GOBIN is set, and $(go env GOPATH)/bin otherwise.
Alternatively, if Git's exec directory is writable, install there directly:
GOBIN="$(git --exec-path)" go install blake.io/git-lfs@latest
Git implements external subcommands with dashed executables. git lfs pull
finds git-lfs in its exec directory or PATH and runs it as git-lfs pull.
Check the selected command with:
PATH="$(git --exec-path):$PATH" command -v git-lfs
It should print the binary installed by Go. If it does not, another git-lfs
appears earlier in Git's search path.
Usage
Run the command through Git from a Git repository:
git lfs pull
git lfs pull origin main
The remote defaults to origin; the ref defaults to HEAD. A pull with an
explicit ref discovers that ref's tree. A pull without a ref discovers the
whole HEAD tree in a full checkout, or only the configured sparse-checkout
paths in a sparse checkout.
This release implements the pull command.
Other git lfs commands are delegated to a distinct upstream git-lfs on
PATH. Keep upstream Git LFS installed to use its other commands. This command
reports an error instead of recursively invoking itself when no upstream
binary is available.
Git does not pass resolved HTTP credentials to external commands. GitHub
authentication uses GH_TOKEN when it is set. Other named hosts use the
configured Git credential helper.
git lfs pull hydrates only paths selected by HEAD that are still unchanged
LFS pointers in both the index and worktree. It skips dirty, staged,
untracked, conflicted, sparse, and absent paths. A named ref, such as
git lfs pull origin main, prefetches its objects into the local LFS store
without changing the current worktree or index.
How it avoids work
The command first finds the LFS pointers named by the selected Git tree, then downloads objects missing from the local LFS store.
The filtered result is ordinary Git storage. Checkout, merge, and rebase can reuse its trees and pointer blobs instead of fetching those objects again. That can avoid Git-side lazy fetches for this tree. It does not make LFS clean, smudge, or filter processing faster, and it does not cover other trees.
This command treats the tree as the unit of work. If its pointer map is not
cached, it fetches the tree with Git's blob:limit=1024 filter. Git returns
the tree objects and small blobs, including LFS pointers, but leaves large
ordinary blobs on the server. The command walks those objects directly,
deduplicates their LFS object IDs, asks the LFS batch API only for missing
objects, and downloads up to 40 at once. Each download must match its declared
size and SHA-256 before it enters .git/lfs/objects.
A Git tree is immutable, so its hash is a complete cache key for a whole-tree pointer map. Sparse pulls include their sorted sparse-checkout paths in that cache key. Pulling the same selection again reads one cached map. Changing the tree or sparse selection runs discovery again.
The cache uses refs below refs/git-lfs/pull/. Remove them with:
git lfs pull --prune-cache
Afterward, normal Git maintenance can reclaim the now-unreachable cache objects.
This removes repeated discovery; it does not remove the cost of a cold pull. The first pull of a tree still fetches and parses its pointer blobs, and every missing LFS object still crosses the network.
Included gitfs fork
This repository includes a local fork of rsc.io/gitfs for filtered Git
fetches. It is imported as blake.io/git-lfs/gitfs; its upstream base and
local extensions are documented in gitfs/README.md and
gitfs/NOTICE.
License
The repository's original work is available under the MIT License.
The included gitfs fork remains under its BSD license.
See the command documentation for the pull algorithm, cache behavior, authentication, and server requirements. It is also available locally:
go doc .
Documentation
¶
Overview ¶
Git-lfs implements Git LFS pull using filtered Git trees.
Install ¶
Install the latest release:
go install blake.io/git-lfs@latest
Make sure the Go install directory is on PATH. It is $(go env GOBIN) when GOBIN is set, and $(go env GOPATH)/bin otherwise.
Alternatively, if Git's exec directory is writable, install there directly:
GOBIN="$(git --exec-path)" go install blake.io/git-lfs@latest
Git implements external subcommands with dashed executables. Git lfs pull finds git-lfs in its exec directory or PATH and runs it as git-lfs pull. Check the selected command with:
PATH="$(git --exec-path):$PATH" command -v git-lfs
It should print the binary installed by Go. If it does not, another git-lfs appears earlier in Git's search path.
Usage ¶
Run the command through Git from a Git repository:
git lfs pull git lfs pull --tree areas/apps/flow git lfs pull --tree . git lfs pull origin main
In full:
git lfs pull [--tree PATH] git lfs pull [remote [ref]]
The remote defaults to origin. The ref defaults to HEAD. An explicit ref discovers that ref's tree. An argumentless pull discovers the whole HEAD tree in a full checkout, or only configured sparse-checkout paths in a sparse checkout. --tree discovers only that tree; --tree . discovers only files immediately in the repository root. This release implements the pull command.
Other git lfs commands are delegated to a distinct upstream git-lfs on PATH. Keep upstream Git LFS installed to use its other commands. This command reports an error instead of recursively invoking itself when no upstream binary is available.
A pull of HEAD hydrates only paths that are still unchanged LFS pointers in the index and worktree. It skips dirty, staged, untracked, conflicted, sparse, and absent paths. A named ref, such as "git lfs pull origin main", prefetches its objects into the local LFS store without changing the current worktree or index.
Pull ¶
The command first finds the LFS pointers named by the selected Git tree, then downloads objects missing from the local LFS store.
The filtered result is ordinary Git storage. Checkout, merge, and rebase can reuse its trees and pointer blobs instead of fetching those objects again. That can avoid Git-side lazy fetches for this tree. It does not make LFS clean, smudge, or filter processing faster, and it does not cover other trees.
Git-lfs treats the tree as the unit of work. If its pointer map is not cached, it fetches the tree with the Git filter blob:limit=1024. Git returns the tree objects and small blobs, including LFS pointers, but leaves large ordinary blobs on the server.
Git-lfs walks those objects directly, deduplicates their LFS object IDs, asks the LFS batch API only for missing objects, and downloads up to 40 at once. Each download must match its declared size and SHA-256 before it enters .git/lfs/objects.
The Git server must support protocol v2, shallow fetches, and object filters when a filtered fetch is needed.
Cache ¶
A Git tree is immutable, so its hash is a complete cache key for a whole-tree pointer map. A sparse pull also keys the map by its sorted sparse-checkout paths. Git-lfs stores the map as a Git blob referenced by a private ref.
A later pull of the same tree reads one cached map. A changed tree has a different key and is discovered independently. A cache hit avoids another pointer walk, but a cold pull still fetches and parses the pointer blobs, and every missing LFS object still crosses the network.
The cache uses refs below refs/git-lfs/pull/. To remove cache refs, run:
git lfs pull --prune-cache
Normal Git maintenance can reclaim the now-unreachable cache objects.
Authentication ¶
Git does not pass resolved HTTP credentials to external commands.
For github.com, git-lfs uses GH_TOKEN when it is set. For other named hosts, it asks git credential fill with terminal prompting disabled. Loopback and IP-address remotes are used without credentials.
Source Files
Directories