Reference — /ops
Every export from git-fs-s3/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
resolveCommitresolveCommit(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.
getBlobgetBlob(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.
getFileContentgetFileContent(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.
getCommitgetCommit(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.
getTreeFromRefgetTreeFromRef(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
resultKeyPrefixesresultKeyPrefixes(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).
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.