IF Commons GitHub

versions/git

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));

Source: commons/mizan/src/versions/git.ts

0 of 24 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

Rawtypeno test imports it
type Raw = { readonly code: number; readonly stdout: string; readonly stderr: string };

What git said: its exit status and both streams as text.

rawfunctionno test imports it
function 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 it
function 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 it
function 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 it
function 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 it
function 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 it
function treePaths(repo: string, rev: string): Promise<Result<readonly string[], GitError>>

The paths of the tree of a commit.

fileAtfunctionno test imports it
function 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 it
function 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 it
function 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 it
type 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 it
type 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 it
function 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 it
function 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 it
function 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 it
function 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 it
function 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 it
function 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 it
function 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 it
function 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 it
function commitSeconds(repo: string, rev: string): Promise<Result<number, GitError>>

The time of a commit, in seconds since the epoch.

isDirtyfunctionno test imports it
function 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 it
function 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 it
function 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.

Titles, headings, exports, tables, columns and requirements. Esc closes.