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>

Returns: Promise<Uint8Array>

A file’s raw bytes at a ref (branch name or commit sha). Throws GitRefNotFoundError when the ref doesn’t resolve and GitPathNotFoundError when the path doesn’t exist.

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. Throws GitRefNotFoundError when the ref doesn’t resolve (an empty repo’s unborn branch included) and GitPathNotFoundError when treePath doesn’t exist. getCommitLog, by contrast, returns [] for an unborn branch — an empty history is a real answer. 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? }
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: "added" | "modified" | "deleted", kind: "text" | "binary" | "too-large", additions, deletions, patch, oldSize?, newSize? } — a file over MAX_DIFF_TEXT_BYTES is too-large and is never read: its size comes from its pack entry (getObjectSize).
DiffResult	{ files: DiffFile[]; totalAdditions; totalDeletions; totalFiles }
CommitSummary	{ sha, message, authorName, authorEmail, createdAt } — summarizeCommit(commit) builds one
FileHistoryResult	{ entries: CommitSummary[]; truncated: boolean }
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.