Reference — /ops

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

See the overview for OpsHooks/ResultCache and the Repo shape shared by every function here.

Branches & commits

listBranches, createBranchFrom, deleteBranchByName, assertBranchExists, authorNow, commitFilesToBare, deleteFileFromBare, writeCommitToBare — see Branches & commits for full signatures.

Reading objects directly

functionresolveCommit

resolveCommit(repo: Repo, ref: string): Promise<{ oid: string; commit: CommitObject }>

Returns: Promise<{ oid; commit }>

Resolves a branch name / full ref / sha to its commit object. The primitive getFileContent and getTreeFromRef build on.

functiongetBlob

getBlob(repo: Repo, sha: string): Promise<Uint8Array>

Returns: Promise<Uint8Array>

A blob’s raw bytes by oid. Throws GitObjectNotFoundError (not a raw isomorphic-git NotFoundError) if the object is missing from storage — distinct from “the file doesn’t exist at this path,” which is what getFileContent throws GitPathNotFoundError for.

functiongetFileContent

getFileContent(repo: Repo, filePath: string, ref?: string): Promise<Uint8Array>

Parameter	Type	Description
ref?	string	Defaults to "main".

Returns: Promise<Uint8Array>

A file’s raw bytes at a ref. Throws GitPathNotFoundError when the path doesn’t exist.

functiongetFileFromRef

getFileFromRef(repo: Repo, filePath: string, ref: string): Promise<{ content, size, isBinary }>

Returns: Promise<{ content: string; size: number; isBinary: boolean }>

getFileContent, decoded for display — utf8 text, or base64 when the content is detected as binary (a null-byte heuristic).

functiongetCommit

getCommit(repo: Repo, sha: string): Promise<CommitInfo>

Returns: Promise<CommitInfo>

One commit by sha. CommitInfo is { oid, commit: { message, tree, parent, author, committer }, payload }.

Trees, history & diff

Tree primitives (upsertTree, deleteFromTree, findTreeEntry, listTreeEntries), getTreeFromRef, getCommitLog, getCommitHistory, getFileHistory, getLastCommitsForTree, getCommitDiff, getDiffBetweenRefs — see Trees, history & diff for full signatures, and don’t miss the note on getCommitLog’s result-cache pattern.

functiongetTreeFromRef

getTreeFromRef(repo: Repo, options?: { ref?, treePath? }, hooks?: OpsHooks): Promise<TreeEntry[]>

Returns: Promise<TreeEntry[]>

List a directory at the tip of a ref. [] for an empty repo/unborn branch; throws GitPathNotFoundError when treePath doesn’t exist. Results are memoized per head sha.

Merge

analyzeMerge, fastForwardMerge — see Merge.

Cache key management

functionresultKeyPrefixes

resultKeyPrefixes(gitdir: string): string[]

Returns: string[]

The ResultCache key prefixes holding entries for gitdir — evict these from your cache when a repo’s storage was rewritten outside a normal push (a bulk sync, a rename, a repack cleanup).

Danger

Always derive invalidation prefixes from this function — never hand-roll your own prefix scheme. See the warning on the overview page.

Types

Export	Shape
Repo	{ fs: IsoGitFs; gitdir: string; cache?: object }
IsoGitFs	The fs shape isomorphic-git itself accepts.
OpsHooks	{ resultCache?, step?, onNote?, prefetch?, prefetchMinDepth? }
ResultCache	{ get<T>(key): T | null | undefined; set(key, value): void }
Branch	{ name: string; commit: string; isDefault: boolean }
CommitAuthor	{ name, email, timestamp, timezoneOffset }
CommitInfo	{ oid, commit: { message, tree, parent, author, committer }, payload }
CommitLogOptions	{ ref?, depth?, knownHeadSha? }
TreeEntry	{ path, mode, type: "blob" | "tree", oid, size? }
DiffFile	{ path, status, additions, deletions, patch, isBinary?, oldContent?, newContent?, ... }
DiffResult	{ files: DiffFile[]; totalAdditions; totalDeletions; totalFiles }
FileHistoryEntry	{ sha, message, authorName, authorEmail, createdAt }
FileHistoryResult	{ entries: FileHistoryEntry[]; truncated: boolean }
LastCommitInfo	{ sha, message, authorName, authorEmail, createdAt }
MergeAnalysis	{ canMerge, hasConflicts, conflictingFiles, fastForward }

HISTORY_WALK_DEPTH (= 400) and BANNER_WALK_DEPTH (= 60) are the default/shallow walk-depth constants used by getFileHistory and getLastCommitsForTree — see Trees, history & diff.