IF Commons GitHub

git

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-system FR-014

A Git repository read by running git (commons 0007-grc FR-021): the commit at HEAD, whether the working tree is clean, the paths changed between two revisions, and a file's bytes as it is at a revision. Each runs git -C REPO ... by its argument vector, never through a shell, with no pager, no terminal prompt, no optional locks and messages in English; paths are read NUL-separated (-z), so spaces, quotes and non-ASCII names come back as they are. Every failure is an Err naming what went wrong, a repository that is not there and a git that is not installed included; nothing here throws.

import { changedPaths, head } from "./git.ts";
const h = await head(".");
if (h.kind === "ok") console.log(h.value);
const changed = await changedPaths(".", "HEAD~1", "HEAD"); // { kind: "ok", value: ["src/a.ts", ...] }

Source: commons/system/src/git.ts

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

gitnamespace
namespace git
git.CommitIdtypeno test imports it
type CommitId = Brand<string, "CommitId">;

A commit's object id: 40 (SHA-1) or 64 (SHA-256) lower-case hexadecimal digits, made only by commitIdOf.

git.commitIdOffunctionno test imports it
function commitIdOf(text: string): CommitId | undefined

Text as a commit id, or undefined where it is not 40 or 64 lower-case hexadecimal digits.

git.GitErrortypeno test imports it
type GitError = | { readonly kind: "git-missing"; readonly program: string } | { readonly kind: "not-a-repository"; … (480 characters)
type GitError =
  | { readonly kind: "git-missing"; readonly program: string }
  | { readonly kind: "not-a-repository"; readonly repo: string; readonly message: string }
  | { readonly kind: "bad-revision"; readonly rev: string; readonly message: string }
  | { readonly kind: "no-such-path"; readonly rev: string; readonly path: string; readonly message: string }
  | { readonly kind: "failed"; readonly args: readonly string[]; readonly code: number; readonly message: string };

Why a repository could not be read.

git.formatGitErrorfunctionno test imports it
function formatGitError(e: GitError): string

A Git error as one sentence.

git.GitOptionstypeno test imports it
type GitOptions = { readonly program?: string };

How git is run: the program (git on PATH by default).

git.headfunctionno test imports it
function head(repo: string, options?: GitOptions): Promise<Result<CommitId, GitError>>

The commit HEAD points to; bad-revision in a repository with no commit yet.

git.isCleanfunctionno test imports it
function isClean(repo: string, options?: GitOptions): Promise<Result<boolean, GitError>>

Whether the working tree and the index match HEAD, with no untracked file that is not ignored.

git.changedPathsfunctionno test imports it
function changedPaths(repo: string, from: string, to: string, options?: GitOptions): Promise<Result<readonly string[], GitError>>

The paths (relative to the repository's top, /-separated) whose content differs between two revisions, in Git's order, each once; a rename gives both its old and its new path.

git.fileAtfunctionno test imports it
function fileAt(repo: string, rev: string, path: string, options?: GitOptions): Promise<Result<Uint8Array<ArrayBufferLike>, GitError>>

A file's bytes as it is at a revision, its path relative to the repository's top (/-separated); no-such-path where it is not there.

CommitIdtypeno test imports it
type CommitId = Brand<string, "CommitId">;

A commit's object id: 40 (SHA-1) or 64 (SHA-256) lower-case hexadecimal digits, made only by commitIdOf.

commitIdOffunction
function commitIdOf(text: string): CommitId | undefined

Text as a commit id, or undefined where it is not 40 or 64 lower-case hexadecimal digits.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

GitErrortypeno test imports it
type GitError = | { readonly kind: "git-missing"; readonly program: string } | { readonly kind: "not-a-repository"; … (480 characters)
type GitError =
  | { readonly kind: "git-missing"; readonly program: string }
  | { readonly kind: "not-a-repository"; readonly repo: string; readonly message: string }
  | { readonly kind: "bad-revision"; readonly rev: string; readonly message: string }
  | { readonly kind: "no-such-path"; readonly rev: string; readonly path: string; readonly message: string }
  | { readonly kind: "failed"; readonly args: readonly string[]; readonly code: number; readonly message: string };

Why a repository could not be read.

formatGitErrorfunction
function formatGitError(e: GitError): string

A Git error as one sentence.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

GitOptionstypeno test imports it
type GitOptions = { readonly program?: string };

How git is run: the program (git on PATH by default).

headfunction
function head(repo: string, options?: GitOptions): Promise<Result<CommitId, GitError>>

The commit HEAD points to; bad-revision in a repository with no commit yet.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

isCleanfunction
function isClean(repo: string, options?: GitOptions): Promise<Result<boolean, GitError>>

Whether the working tree and the index match HEAD, with no untracked file that is not ignored.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

changedPathsfunction
function changedPaths(repo: string, from: string, to: string, options?: GitOptions): Promise<Result<readonly string[], GitError>>

The paths (relative to the repository's top, /-separated) whose content differs between two revisions, in Git's order, each once; a rename gives both its old and its new path.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

fileAtfunction
function fileAt(repo: string, rev: string, path: string, options?: GitOptions): Promise<Result<Uint8Array<ArrayBufferLike>, GitError>>

A file's bytes as it is at a revision, its path relative to the repository's top (/-separated); no-such-path where it is not there.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

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