Reference — /http

import { /* ... */ } from 'git-fs-s3/http';

See the overview for HttpHooks and the overall shape, and Serving clones and pushes for a full worked example.

info/refs

functionhandleInfoRefs

handleInfoRefs(repo: Repo, options: InfoRefsOptions, hooks?: HttpHooks): Promise<GitHttpResult>

Parameter	Type	Description
options.service	"git-upload-pack" | "git-receive-pack"
options.defaultBranch?	string	Defaults to "main".
options.agent?	string	Advertised in the capability line. Default "git-fs-s3".

Returns: Promise<GitHttpResult>

The GET .../info/refs?service=… ref advertisement. Authentication and authorization are the caller’s job before invoking this.

functionlistAllRefs

listAllRefs(repo: Repo, defaultBranch?: string): Promise<{ refs, headSymref }>

Returns: Promise<{ refs: { name; oid }[]; headSymref: string }>

The lower-level primitive handleInfoRefs is built on, exposed in case you need the raw ref list without the pkt-line framing.

upload-pack

functionhandleUploadPack

handleUploadPack(repo: Repo, body: Uint8Array, options?: UploadPackOptions, hooks?: HttpHooks): Promise<GitHttpResult>

Parameter	Type	Description
body	Uint8Array	The raw POST body.
options.beforeWalk?	() => Promise<void>	Called once before the reachability walk — wire loose-object detection here.

Returns: Promise<GitHttpResult>

Serves a clone/fetch. Negotiation is client-driven (no multi_ack advertised): have batches without done get a bare NAK; the final batch gets the packfile, side-band-64k framed. A fresh clone of a repo already consolidated to a single pack serves that pack’s bytes directly, skipping the reachability walk entirely.

receive-pack

functionparseReceivePackBody

parseReceivePackBody(body: Uint8Array): { refUpdates: RefUpdateCommand[]; packData: Uint8Array }

Returns: { refUpdates: RefUpdateCommand[]; packData: Uint8Array }

Splits a receive-pack body into its pkt-line ref-update commands and the trailing raw pack bytes.

functionapplyReceivePack

applyReceivePack(repo: Repo, parsed: ReturnType<typeof parseReceivePackBody>, options?: ApplyReceivePackOptions, hooks?: HttpHooks): Promise<{ results, stalePackPaths }>

Parameter	Type	Description
options.defaultBranch?	string	Defaults to "main".
options.repack?	RepackOptions | false	Repack tuning, or false to skip repacking entirely.

Returns: Promise<{ results: RefUpdateResult[]; stalePackPaths: string[] }>

The storage half of a push: initializes the repo if needed, indexes the incoming pack, applies ref updates with compare-and-swap against each command’s claimed oldOid (a stale push is rejected, not force-applied), then repacks once enough packs have accumulated. Build the HTTP response afterwards with receivePackResponse. See Repacking for stalePackPaths.

functionapplyRefUpdates

applyRefUpdates(repo: Repo, refUpdates: RefUpdateCommand[], hooks?: HttpHooks): Promise<RefUpdateResult[]>

Returns: Promise<RefUpdateResult[]>

The ref-update half of applyReceivePack, exposed standalone. Every client-supplied refName is validated with isSafeFullRefName before it reaches any filesystem call — see the warning on the overview page.

functionensureRepoInitialized

ensureRepoInitialized(repo: Repo, defaultBranch?: string): Promise<void>

Initializes the repo when HEAD doesn’t exist yet (a first push).

functionindexIncomingPack

indexIncomingPack(repo: Repo, packData: Uint8Array, hooks?: HttpHooks): Promise<void>

Writes an incoming pack into objects/pack/ and indexes it.

functionreceivePackResponse

receivePackResponse(results: RefUpdateResult[]): GitHttpResult

Returns: GitHttpResult

Builds the report-status response body from a set of ref-update results.

Repacking

functionrepackRepository

repackRepository(repo: Repo, options?: RepackOptions, hooks?: HttpHooks): Promise<string[]>

Returns: Promise<string[]>

See the dedicated repacking page — the threshold, why every object is re-verified, and the deletion contract.

REPACK_PACK_COUNT_THRESHOLD (= 4) is the default RepackOptions.threshold.

Reachability

functioncollectReachableOids

collectReachableOids(repo: Repo, startOids: string[], hooks?: HttpHooks): Promise<ReachabilityResult>

Returns: Promise<ReachabilityResult>

Walks the full object graph from startOids. { oids, complete } — complete: false if any object in the graph couldn’t be read; a missing object is retried once (a read landing mid-repack-transition can transiently miss an object that isn’t actually lost) before being reported through hooks.onWarn.

pkt-line framing

Low-level helpers, exposed if you’re implementing protocol pieces this module doesn’t cover:

Export	Signature
FLUSH	Uint8Array — the flush-pkt ("0000").
pktLine	(data: string) => Uint8Array
pktLineBuffer	(body: Uint8Array) => Uint8Array
parsePktLines	(buf: Uint8Array) => Array<string | null> — null marks a flush-pkt.
sideBandPackfile	(packData: Uint8Array) => Uint8Array — chunks packfile bytes into side-band-64k framed pkt-lines.

Note

sideBandPackfile exists because clients that unconditionally expect side-band framing on the response (isomorphic-git’s own GitSideBand.demux is one) misparse a raw packfile stream as bogus pkt-line length headers and hang — this is required once side-band-64k is advertised, which handleInfoRefs always does.

Types

Export	Shape
GitHttpResult	{ status: number; headers: Record<string, string>; body: Uint8Array<ArrayBuffer> }
HttpHooks	{ step?, onWarn? } — see the overview.
RawFsPromises	The .promises surface applyReceivePack/repackRepository need beyond isomorphic-git’s own plumbing.
rawFs	(repo: Repo) => RawFsPromises — duck-types the .promises surface off a repo’s fs.