Module lfs 

Git LFS support: pre-push planning, pointer scanning and bounded uploads. What: Git LFS support: pre-push planning, pointer scanning and bounded uploads. Why: LFS is an optional feature with its own vocabulary.

In TS you’d write (pseudocode):

// lfs/index.ts: one `export * from './file'` per module below.

Modules

lfs_bounded_push

The auto-push’s bounded git push, preceded by the upload, its pre-check and its explanation. What: Run one bounded git push of the auto-push, preceded by the Git LFS upload when the repository has one. Why: The auto-push and its reconcile pushes publish refs, so they upload the LFS objects the pushed commits point to exactly as a typed git push does. The wrapper is the parent of both children and captures their output, so it owns the explanation: a missing git-lfs is refused before anything starts, a failed upload ends the attempt with the full explanation after the program’s own output, and the push is not started. The push carries no hook, and no process other than Git and git-lfs is started for this, none of them the wrapper.

lfs_interactive

The Git LFS step before a push the caller typed: pre-check, plan and upload with the caller’s streams. What: The Git LFS step before a push the caller typed: the pre-check, the plan and the upload, with the caller’s streams. Why: The parent owns the whole step, so a refusal, a plan that cannot be worked out and a failed upload are all explained by the process that saw them, and the push is not started after any of them. The configuration the plan reads comes from the snapshot the wrapper already took when it planned the invocation, so a push whose repository is known costs no Git start for it; without a snapshot one config --get-regexp start reads it.

lfs_object_plan

The upload plan narrowed to the objects the push introduces, or to nothing. What: Narrow an upload plan from “scan these refs with git-lfs” to the exact objects the push introduces, decided in process, or to nothing. Why: Most pushes add no LFS object, and then no git-lfs process and no request to the LFS server is needed. The tips come from the plan’s refs; the commits already known to the destination are the remote’s tracking refs when the plan trusts them, else none (the whole history of the pushed refs is scanned, which keeps the case where the tracking refs may not describe the destination correct). When the readers decline, or an object the scan found is missing from .git/lfs (where git-lfs push words the failure and honours lfs.allowincompletepush), the plan stays as it was and git-lfs scans.

lfs_output_mask

Hides the credentials inside URLs in the text relayed from git-lfs. What: Hide the credentials inside URLs in the text the wrapper relays from git-lfs. Why: git-lfs names the LFS server in its errors, and an lfs.url written as https://user:token@host/... carries the token into every one of them. The wrapper relays that text to the caller’s terminal and, for the auto-push, records it in files, so the userinfo of every URL is replaced at the one place where the text leaves the wrapper. The authority of a URL ends at the first /, ?, #, \, quote, angle bracket, backtick or white space, and its userinfo ends at the last @ before that, so an @ in a path, a query or a bracketed IPv6 host is left alone.

lfs_pointer

Whether a blob is a Git LFS pointer, decided as git-lfs decides it. What: Whether a blob is a Git LFS pointer, decided the way git-lfs 3.8.1 decides it when it scans a push. Why: The upload step finds the LFS objects the pushed commits introduce without starting git-lfs. A blob counts when the scanner would hand it to the transfer queue: smaller than the cutoff (lfs/scanner.go, BlobSizeCutoff), a header that names git-media, hawser or git-lfs (lfs/pointer.go, matcherRE), lines in the order version, oid, size with a known version, an sha256: object name of 64 lower-case hexadecimal digits and a non-negative decimal size; a pointer of size zero is skipped by prepareUpload (commands/uploader.go). The path of the blob and .gitattributes play no part. A spelling the port is not sure about (extension lines, non-ASCII edges) is a decline, so the caller falls back to git-lfs itself.

lfs_pointer_scan

The LFS objects a push introduces, found in process from the commits to be pushed. What: The LFS objects a push introduces, found in process: the pointer blobs that the commits to be pushed add. Why: git-lfs push starts a scanner (git rev-list, git cat-file, git ls-remote) and, when it finds anything, asks the LFS server about it; most pushes add no pointer at all, so the wrapper reads the commits itself with the in-process readers and starts git-lfs only when a pointer is found. The commits are those reachable from the pushed tips and not reached before a known-good tip (the remote’s tracking refs, when they describe the destination). Every commit is compared with each of its parents, so a pointer added in one commit and removed in the next is still found. Anything the readers do not fully understand, and any walk that grows past its limits, returns None, so the caller asks git-lfs.

lfs_pre_push

When a push needs the Git LFS upload, and the texts the parent prints around it. What: When a push needs the Git LFS upload, and the texts the parent prints around it. Why: Traditional hook files are unsupported, so the pre-push shim git lfs install writes cannot be relied on. Without an upload step a push publishes pointer files whose objects the LFS server never received. The wrapper therefore runs git-lfs push <remote> <refs> itself, as a child it owns, before it starts the push (lfs_upload.rs), only when the Git configuration holds LFS keys; the push carries no hook and no injected configuration, the wrapper never starts itself and writes no shell text (doc/planning/cli-git-no-self-invocation.md).

lfs_push_precheck

The check that git-lfs can start, made before a push that is preceded by the upload. What: The check, before anything starts, that the Git LFS upload a push is about to run can start. Why: A push of a repository with LFS keys is preceded by git-lfs push, which the parent starts. When no directory of PATH holds git-lfs, one stat per PATH directory, with no process started, finds that first, and the parent says so with the full explanation. A push that bypasses the upload (--no-verify, GIT_LFS_SKIP_PUSH, or the switch -c hook.cli-git-lfs-pre-push.enabled=false) needs no program, so it is never refused here.

lfs_upload

The parent’s bounded or interactive run of the Git LFS upload. What: The parent’s run of the Git LFS upload before a push: git-lfs push <remote> <refs> as one child it owns. Why: Without an upload step a push publishes pointer files whose objects the LFS server never received. The wrapper runs git-lfs push itself, so a failure is explained by the process that saw it and the push, which then carries no hook, is never started. Nothing here starts the wrapper, writes shell text or injects Git configuration (doc/planning/cli-git-no-self-invocation.md). What to upload is decided in lfs_upload_plan. The child sees what the caller gave Git: the global -c options travel as GIT_CONFIG_COUNT pairs, --git-dir, --work-tree and --namespace as their variables, -C as the working directory, and the real Git’s directory leads its PATH so a git it starts is never the wrapper while git-lfs itself is the one the caller’s PATH finds first.

lfs_upload_plan

What the Git LFS upload sends: the remote and the refs, read from the push and the configuration Git would read. What: What the Git LFS upload before a push sends: the destinations git lfs push takes and the refs whose objects it uploads, with --all wherever a remote-tracking ref of this clone may not describe the destination, so that it cannot hide an object the destination lacks, and in git-lfs’s bounded form (no --all) everywhere else. Why: git lfs push takes refs and no ref-update lines, so the plan is read from the push’s own arguments with the same option table as the rest of the wrapper, and from the configuration Git itself would read for the parts the arguments leave out (the default remote, remote.<name>.push, remote.<name>.mirror, the push URLs, push.default). The configuration comes from the snapshot the caller already holds, or from one query. Refs that Git expands from a pattern are listed with git for-each-ref and matched here with a refspec’s own rule (* crosses /). The plan fails closed: a query that fails is an error the caller turns into a refusal, never into “nothing to upload”. Only a mirror push uploads every ref.

lfs_upload_settings

The configuration the Git LFS upload plan reads, and the default remote derived from it. What: The configuration the Git LFS upload plan reads, and the answers derived from it: the default remote, the branch HEAD names, and whether a value reads as true. Why: The plan and the manual-push probe must agree on the destination of a bare push, so both read it here. The entries come from a snapshot the caller already holds or from one config --get-regexp, never one start per key.