Rawtypeno test imports ittype Raw = { readonly code: number; readonly stdout: string; readonly stderr: string };What git said: its exit status and both streams as text.
The host layer of the versions tool that reads and writes Git (commons 0026-works-versioning FR-017 to FR-024, FR-031): the tracked paths and the records of a tree, the base of a check, the paths that changed, the facts about the commits that editions name, the tags with their commits and trees and signatures, the commits since a tag with the paths each touched, and the creation of an annotated tag, signed where Git is set to sign. Each is the real git, run by its argument vector (never through a shell), with no pager and no terminal prompt.
Every failure is an Err that names what went wrong, and nothing throws. A shallow clone, a base that is not there and a directory that is no repository are errors of their own kind, so that the command says not_run with the reason (FR-031) and never a pass. The tool reads only Git: a repository on plain Git, with no host, is enough.
import { readTags } from "./git.ts";
const r = await readTags(".");
if (r.kind === "ok") console.log(r.value.map((t) => t.name));Rawtypeno test imports ittype Raw = { readonly code: number; readonly stdout: string; readonly stderr: string };What git said: its exit status and both streams as text.
rawfunctionno test imports itfunction raw(repo: string, args: readonly string[]): Promise<Result<Raw, GitError>>git --no-pager -C repo ...args, whatever its status, or why git could not run at all.
textfunctionno test imports itfunction text(repo: string, args: readonly string[]): Promise<Result<string, GitError>>git ...args as text where it succeeded, or why it did not.
isRepositoryfunctionno test imports itfunction isRepository(repo: string): Promise<Result<boolean, GitError>>Whether the folder is inside a Git repository (any failure to say so is the error).
resolveCommitfunctionno test imports itfunction resolveCommit(repo: string, rev: string): Promise<Result<string, GitError>>The full object name of a revision as a commit, or why there is none.
trackedPathsfunctionno test imports itfunction trackedPaths(repo: string): Promise<Result<readonly string[], GitError>>The paths tracked by Git now (the index), in the order Git lists them.
treePathsfunctionno test imports itfunction treePaths(repo: string, rev: string): Promise<Result<readonly string[], GitError>>The paths of the tree of a commit.
fileAtfunctionno test imports itfunction fileAt(repo: string, rev: string, path: string): Promise<Result<string | undefined, GitError>>A file as it was at a revision, or undefined where there was none.
readTreefunctionno test imports itfunction readTree(repo: string, rev: string): Promise<Result<TreeFacts, GitError>>The tree of a commit with the text of every record in it.
readWorkingTreefunctionno test imports itfunction readWorkingTree(repo: string): Promise<Result<TreeFacts, GitError>>The tracked paths now with the text of every record as it is on disk (what bump, tag, cite and ledger read).
Basetypeno test imports ittype Base = { readonly kind: "commit"; readonly commit: string } | { readonly kind: "none" };Where the check compares with: a commit, or nothing where the head is the first commit (every work is then new).
BaseErrortypeno test imports ittype BaseError = { readonly kind: "not-found"; readonly reason: string } | { readonly kind: "git"; readonly error: GitError };Why a base could not be found: said as not_run with this reason (FR-031).
findBasefunctionno test imports itfunction findBase(repo: string, rev: string): Promise<Result<Base, BaseError>>The base of a check (FR-022): the merge base of the head with rev (origin/main unless given), or the head's first parent where the head is rev (a push to the branch itself). A shallow clone that does not hold the base, a revision that is not there and a history that shares nothing are not-found with the reason.
changedBetweenfunctionno test imports itfunction changedBetween(repo: string, base: string, head: string): Promise<Result<readonly string[], GitError>>The paths that differ between two commits, a rename counted as a removal and an addition.
isAncestorfunctionno test imports itfunction isAncestor(repo: string, a: string, b: string): Promise<Result<boolean, GitError>>Whether a is an ancestor of b or the same commit.
editionFactsfunctionno test imports itfunction editionFacts(repo: string, commit8s: readonly string[], head: string): Promise<Result<EditionFacts, GitError>>What Git says of the commits the editions name (FR-011): the commit and its UTC day for each first eight characters that names one, and which is an ancestor of which.
readTagsfunctionno test imports itfunction readTags(repo: string): Promise<Result<readonly TagFact[], GitError>>The tags of the repository with their commits, trees, signatures and commit times; a tag of a tree or a blob is left out.
tagAncestryfunctionno test imports itfunction tagAncestry(repo: string, tags: readonly TagFact[]): Promise<Result<ReadonlySet<string>, GitError>>The ancestry of the commits of tags: the pairs <ancestor> <descendant> of commits of tags, ancestor and descendant different. One for-each-ref --merged for each distinct commit.
tagsMergedfunctionno test imports itfunction tagsMerged(repo: string, rev: string): Promise<Result<ReadonlySet<string>, GitError>>The names of the tags whose commit is an ancestor of rev or is it.
commitsSincefunctionno test imports itfunction commitsSince(repo: string, from: string | undefined): Promise<Result<readonly CommitFact[], GitError>>The commits after from up to HEAD (the whole history where from is undefined), each with its subject, its message and the paths it touched; oldest first.
commitSecondsfunctionno test imports itfunction commitSeconds(repo: string, rev: string): Promise<Result<number, GitError>>The time of a commit, in seconds since the epoch.
isDirtyfunctionno test imports itfunction isDirty(repo: string, path: string): Promise<Result<boolean, GitError>>Whether a path has a change not committed (a modified, staged or untracked file).
signingConfiguredfunctionno test imports itfunction signingConfigured(repo: string): Promise<Result<boolean, GitError>>Whether Git is set to sign tags: a signing key is configured, or tag.gpgSign is true.
createTagfunctionno test imports itfunction createTag(repo: string, name: string, message: string, sign: boolean): Promise<Result<void, GitError>>Creates an annotated tag at HEAD, signed (git tag -s) where sign is true; Git refuses a name that exists, and a signature that cannot be made is an error and no tag.