Read-side git plumbing for the git:read API. It hydrates a cache repo, resolves refs, and runs git children under per-request budgets to serve trees, blobs, logs, blame, diff, grep, archives, tags, and notes. The package is HTTP-agnostic and returns ErrNotFound-wrapped errors for missing data.
ErrNotFound,EmptyTreeSHA[gitread.go:ErrNotFound]Materialize— hydrates the cache bare repo throughgithttp.Hydrateand returns its path [gitread.go:Materialize]ResolveRef— resolves a branch, tag, full ref, or hex spec to a commit SHA. Withephemeraltrue it tries only the ephemeral-namespace nameauth.EphemeralRefName(spec)and the hex spec, and skips therefs/heads/,refs/tags/, and full-ref candidates [gitread.go:ResolveRef]- Budgets:
Budget,NewBudget,WithLimits,WithBudget,BudgetFrom,Close,Limits,DefaultLimits,Slots,NewSlots,Class(Light,Heavy),Cmd,Run,CheckBlobSize,IsBudgetError[budget.go:NewBudget] GitError—Run's error for git's own failure: it wraps the run's error and keeps git's stderr [budget.go:GitError]- Limit errors:
ErrBusy,ErrTimeBudget,ErrOutputLimit,ErrBlobTooLarge,ErrSymlinkTooLong,LimitPath,ErrMemoryLimit,ErrStop; capsHeavyHeapBytes,LightHeapBytes,DefaultOutputBytes,MaxBlobBytes[budget.go:ErrBusy] HeapLimitSupported[heaplimit.go:HeapLimitSupported]- Trees and blobs:
TreeEntry,EntryBlob,EntryTree,EntrySymlink,EntrySubmodule,LsTree,LsTreePage,ErrUnsortedTree,BlobInfo,StatBlob,CatBlobTo,ReadSymlinkTarget[tree.go:LsTree] - History:
Commit,LogOptions,Log,CommitsBySHA,CommitDetail,GetCommit,LastCommits,ErrTooManyLastCommits[log.go:Log] [lastcommits.go:LastCommits] BlameLine,Blame,ErrBadRange[blame.go:Blame]FileDiff,DiffStats,DiffOptions,Diff[diff.go:Diff]GrepLine,GrepFile,GrepOptions,GrepLineMatch,GrepLineContext,Grep,ErrBadPattern[grep.go:Grep]ArchiveOptions,PreparedArchive,PrepareArchive,(*PreparedArchive).Stream,Archive,ValidArchivePrefix,MatchGlob[archive.go:PrepareArchive]Tag,PeeledTags,Note[refs.go:PeeledTags] [notes.go:Note]
assertfpanics on programming errors such as an empty repo path or a non-SHA commit argument [gitread.go:assertf]ResolveRefreads each candidate name directly withrev-parse --verify --quietwithout a peel (so a ref's missing object still resolves), and its full id's type and peels withcat-file --batch-check. A hex abbreviation is read as<abbrev>^{commit}first, as on main: only the peel picks a commit that shares the abbreviation with a blob or a tree. On git's exit 1 it gets the plain lookup too. No command lists ref directories. git's DWIM rules stay in use, and revision operators and control bytes are refused before git starts: the hex fallback is the only object revision. Only git's exit 1 makes the name unknown: every other git failure (a budget error, a kill, a fatal exit) is returned as is. An empty spec, a spec with a NUL byte, and one longer thanmaxRefSpecBytes(4096 bytes) areErrNotFoundbefore git runs [gitread.go:ResolveRef]resolveCommitObjectreads three batch-check answers (the id's type, its^{commit}peel and its^{}peel). A full id that names no object and a tree, blob or tag of one are not found. A ref whose object is missing, a broken tag chain, and a commit git cannot read are errors [gitread.go:resolveCommitObject]IsBudgetErrorerrors must not be reported as not-found [budget.go:IsBudgetError](*Budget).startasserts the budget is open and returnsErrTimeBudgetpast the deadline;limitedBuffer.Writekills git once output is exhausted [budget.go:Budget.start]Runnever wrapsExitErrorfor limit outcomes [budget.go:Run]- A request whose context ends gets the context's error from
Run, also when git was killed for it: never aGitErrorfor the kill [budget.go:Run] Run's errors name the command withgitlimit.Nameand quote the last 64 KiB of git's stderr (gitlimit.TailBuffer) [budget.go:Run]Cmd.Stderr, when set, also receives git's stderr, for a caller that reads git's messages when git exits 0 [budget.go:Cmd]childEnvforcesLC_MESSAGES=Cand keepsLC_CTYPE/LC_COLLATE[budget.go:childEnv]LsTreepasses paths as:(literal)pathspecs;parseLsTreeRecordrejects malformed records;LsTreePagereturnsErrUnsortedTreeon out-of-order output [tree.go:LsTreePage]PrepareArchivefails before any byte is written when a kept blob exceeds the size limit [archive.go:PrepareArchive]ValidArchivePrefixrejects NUL, backslash, a leading slash, and./..segments [archive.go:ValidArchivePrefix]mergeNumstatandmergePatcheserror on any mismatch between the three diff passes [diff.go:mergeNumstat]- A type change (
T) is one--rawand one--numstatrecord, and two--patchsections (its deletion, then its addition): itsPatchholds both [diff.go:mergePatches] LastCommitsfails withErrTooManyLastCommitspastmaxDistinct; spool lines over 1 MiB or spool over 256 MiB fail withErrOutputLimit[lastcommits.go:spoolWriter]Notemaps git exit 1 toErrNotFound;PeeledTagsskips non-commit tags [notes.go:Note]- A failed
Blamereads only the exit status and fixed parts of git's stderr, never the path, which git rewrites in its messages. With ranges, exit 129, or exit 128 with stderr that startsfatal: -L, or that startsfatal: fileand endshas only N line(s), read from the first line that startsfatal:, isErrBadRange: git prints no other fatal line before that message, and a path in it comes after the fixed head. Otherwisels-treedecides: a path that names no file (not one blob or symlink, or entries under<path>/) isErrNotFound, and any other failure is returned [blame.go:Blame] BlameandGreprun git withGIT_ATTR_SOURCEset to the empty tree, so that git reads no.gitattributesof the repository's own (git 2.41 and later honor it); those files make git print warnings that quote their paths unescaped. So the repository's attributes do not steer grep's-Ibinary detection or blame's textconv either: where git read them (a work tree,attr.treeorGIT_ATTR_SOURCE=HEADin the server's environment, a bare repository on git 2.43.0 to 2.45.2), a text file markedbinaryor-diffis searched, and a file with a NUL byte and thediffattribute is skipped. A bare repository on git before 2.43.0, or from 2.45.3 on, read none before either [gitread.go:noTreeAttrsEnv]Grepanswers exit 0 or 1 with a stderr line that ends': unable to read <oid>(git could not read a blob, and went on) as a read error, wherever that line is in stderr, exit 1 with no output as no match, and exit 128 with a last line that startsfatal: -e option, 'asErrBadPattern; every other failure is returned [grep.go:runGrep]
Materializewrites the cache repo undercacheDir, reading packs from the blob store and refs from the ref store [gitread.go:Materialize]- Runs git subprocesses through
gitlimit.Run: rev-parse, check-ref-format, ls-tree, cat-file, log, rev-list, diff-tree, diff, blame, grep, for-each-ref, notes [budget.go:Run] (*Budget).starttakes an admission slot thatClosereleases [budget.go:Close]StreamandLastCommitscreate and remove temp spool files;LastCommitsruns a diff-tree goroutine over a pipe [lastcommits.go:LastCommits]Streamwrites tar.gz output to the caller's writer [archive.go:Stream]
- Run:
go test ./internal/gitread/... -tags=openstorage_viewcheck -count=1 -race -timeout=30m