Reference — root export

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

The fs backend

functioncreateGitFs

createGitFs(store: ObjectStore, options?: GitFsOptions): GitFs

Parameter	Type	Description
store	ObjectStore	Any store — see the ObjectStore guide.
options?	GitFsOptions	prefix, looseObjectHints, isStructurallyAbsent, hintTtlMs, onNote.

Returns: GitFs

Returns a promise-based fs client for isomorphic-git’s fs option, plus the git-aware maintenance methods below. See Getting started and the production stack guide.

GitFs (the returned object) additionally exposes:

Method	Signature	What it does
detectLooseObjects	(gitdir: string) => Promise<void>	One bounded LIST that registers the loose-object hint for a gitdir.
prefetchPacks	(gitdir: string, opts?: { maxPacks? }) => Promise<void>	Warms all pack files in parallel before a sequential walk.
invalidate	(pathPrefix: string) => void	Drops hints under the prefix and forwards to the store’s own invalidate if it has one.

Stores

classMemoryObjectStore

new MemoryObjectStore()

In-memory ObjectStore — the reference implementation of list/delimiter semantics, and what this package’s own test suite runs on. See the ObjectStore guide.

functioncreateCachedStore

createCachedStore(store: ObjectStore, options?: CacheOptions): CachedObjectStore

Returns: CachedObjectStore

See the caching guide.

functioncreateRetryStore

createRetryStore(store: ObjectStore, options?: RetryOptions): ObjectStore

See the retry & circuit breaker guide. Throws CircuitOpenError (code: "EUNAVAILABLE") while the breaker is open.

S3ObjectStore lives at the /s3 subpath, not the root export — it’s only loaded when you actually import it, so @aws-sdk/client-s3 stays an optional dependency.

Ref & path validation

Shared by /http internally and safe to reuse in your own request-handling code:

Export	Signature	What it validates
isSafeBranchName	(name: string) => boolean	A bare branch name (no refs/ prefix); rejects SHA-shaped values.
isSafeFullRefName	(ref: string) => boolean	A fully-qualified ref (refs/heads/…/refs/tags/…).
isFullSha	(value: string) => boolean	A full 40-hex-char commit sha.
isSafeRefName	(value: string) => boolean	Branch name or full sha — for read paths that accept a pinned commit.
isSafeRepoPath	(p: string) => boolean	A repo-relative file path: relative, no .., no .git/ prefix, no null bytes.
qualifyBranchRef	(ref: string) => string	Qualifies a bare name to refs/heads/<name>, left untouched if already qualified/HEAD/a sha.

Danger

These mirror isomorphic-git’s own internal isValidRef character-class rules — several isomorphic-git primitives (git.commit, git.merge, git.deleteBranch, top-level git.resolveRef/git.deleteRef) do not validate ref names internally the way git.branch/git.writeRef do. Any ref/branch name that originates from request input must be validated against one of these before it reaches those primitives, or a "../"-laden name is a path traversal on shared storage.

Errors

GitError (base class, carrying statusCode/retryable) and its subclasses map internal failures to HTTP-shaped responses:

Class	Status	Notes
GitPathNotFoundError	404	A path within a tree doesn’t exist.
GitObjectNotFoundError	404	A git object is missing from storage.
GitRefNotFoundError	404	A ref (branch/tag) doesn’t exist.
GitRepositoryNotFoundError	404	The repository itself doesn’t exist.
GitConflictError	409	Carries conflicts: MergeConflictDetail[].
GitAuthenticationError	401
GitAuthorizationError	403
GitRateLimitError	429
GitInvalidRequestError	400
GitProtocolError	400	A git wire-protocol violation.
FsError	—	Filesystem-shaped errors (ENOENT, EINVAL, …) the fs client itself throws.

functionformatErrorResponse

formatErrorResponse(error: unknown): { status: number; body: Record<string, unknown>; headers?: Record<string, string> }

Maps any error to an HTTP response shape. 401s carry the WWW-Authenticate header git clients need before they’ll prompt for credentials. Non-GitError failures are masked as opaque 500s so internal messages don’t leak.

Edge-compatible utilities

The primitives /http and /ops are built on — Web APIs only, no node:crypto/node:zlib/Buffer:

Export	Purpose
encodeUtf8 / decodeUtf8 / decodeAscii	Text ↔ bytes.
concat	Join Uint8Arrays.
toHex / fromHex / toBase64	Encoding conversions.
sha1	SHA-1 via Web Crypto, returns a hex string.
deflate	Deflate compression via CompressionStream.
hasNullByte	Binary-content heuristic.
readBlobContent	{ isBinary, text, bytes } from a blob’s raw bytes.