IF Commons GitHub

physical/ref/mod

Written to: 8 requirements: 8 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-git-ref FR-001, 0003-git-ref FR-008, 0003-git-ref FR-002, 0003-git-ref FR-003, 0003-git-ref FR-004, 0003-git-ref FR-006 and 2 more

A branch of a Git repository as a store. It is written with Git's plumbing, so the working tree, the index and the branch a person has checked out are never touched, and it refuses a branch that is checked out in a working tree (a commit made under a person's feet would show there as the opposite change). A file is an object, its revision is sha256: and the digest of its bytes (so a revision means the same as in every other store, and Git's own names for the blob and the commit are given beside it), a write is guarded by the revision it expects and by the tip it was made on, a batch is one commit, a history is the commits that changed the file, and a branch that has no commit yet is made by the first write with no parent. It holds regular files: a link or another repository in the tree is refused when it is named and left out of a list; large files are refused at a limit and large file storage is not part of it.

import { gitRefStore, parseIdentity } from "@intellectual-frontiers/anyfs-git";
const who = parseIdentity("collector", "collector@localhost");
// const opened = who.kind === "ok" && await gitRefStore({ repo: "/srv/fleet.git", branch: "fleet", commit: { author: who.value } });
// opened.kind === "ok" && await opened.value.store.write(path, bytes, expectAny);

Source: commons/anyfs-git/src/physical/ref/mod.ts

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

CommitOptionstypeno test imports it
type CommitOptions = {
  readonly author: Identity;
  /** Where it differs from the author. */
  readonly committer?: Identity;
  /** The first line of the message, from what the commit changes. */
  readonly subject?: Subject;
  /** Lines after the message. */
  readonly trailers?: readonly Trailer[];
  /** The clock that dates a commit, in milliseconds. */
  readonly clock?: () => number;
};

Who a commit is by and what it says: set by the program, never read from the configuration of a computer.

GIT_REF_CAPABILITIESconstno test imports it
const GIT_REF_CAPABILITIES: readonly ["read", "write", "list", "stat", "delete", "cas", "batch", "rename", "history"]

The capabilities of the store of a branch.

GitReftypeno test imports it
type GitRef = { readonly store: GitRefStore; readonly repo: string; readonly branch: string; /** The commit at t… (879 characters)
type GitRef = {
  readonly store: GitRefStore;
  readonly repo: string;
  readonly branch: string;
  /** The commit at the tip of the branch, or nothing where there is none yet. */
  tip(): Promise<Result<string | undefined, Problem>>;
  /** The blob, mode and newest commit of a file. */
  info(path: Path): Promise<Result<ObjectInfo, Problem>>;
  /** The commits that changed a file, newest first, with who made them. */
  log(path: Path, limit?: number): Promise<Result<readonly LogEntry[], Problem>>;
  /** Pushes this branch and nothing else to a remote; never forced, so a remote that has moved is refused. */
  push(remote: string): Promise<Result<Pushed, RemoteProblem>>;
  /** Brings the branch up to a remote's where that is a fast-forward; a branch that has diverged is left as it is and said so. */
  fetch(remote: string): Promise<Result<Fetched, RemoteProblem>>;
};

A store of a branch, with what Git adds.

GitRefOptionstypeno test imports it
type GitRefOptions = { /** The repository: its working tree, its Git folder, or a bare repository; an absolute path. *… (875 characters)
type GitRefOptions = {
  /** The repository: its working tree, its Git folder, or a bare repository; an absolute path. */
  readonly repo: string;
  readonly branch: string;
  /** The folder of the branch the store is of (the top of the branch where none). */
  readonly prefix?: Prefix;
  readonly commit: CommitOptions;
  /** The largest object, in bytes (50 MiB where none). */
  readonly maxObjectBytes?: number;
  /** Refuse a path another file system could not hold (the default). */
  readonly portable?: boolean;
  /** How many times to read a branch that moved and try again (8 where none). */
  readonly attempts?: number;
  /** Make a store of a branch that is checked out in a working tree: what a person sees there changes under them. */
  readonly allowCheckedOut?: boolean;
  /** The program that runs Git (`git` where none). */
  readonly program?: string;
};

What the store of a branch is made with.

GitRefStoretypeno test imports it
type GitRefStore = Store<(typeof GIT_REF_CAPABILITIES)[number]>;

The type of the store of a branch.

gitRefStorefunctionno test imports it
function gitRefStore(options: GitRefOptions): Promise<Result<GitRef, string>>

The branch of a repository as a store, or why there is none.

LogEntrytypeno test imports it
type LogEntry = {
  readonly commit: string;
  readonly author: { readonly name: string; readonly email: string };
  /** When it was made (ISO 8601, UTC). */
  readonly at: string;
  readonly subject: string;
  /** The revision the file had after it, or nothing where it removed the file. */
  readonly rev: Revision | undefined;
};

One commit that changed a file.

ObjectInfotypeno test imports it
type ObjectInfo = {
  readonly path: Path;
  /** The name of the blob in Git. */
  readonly blob: string;
  /** The mode of the file in Git: `100644` or `100755`. */
  readonly mode: string;
  readonly size: number;
  readonly rev: Revision;
  /** The newest commit that changed the file. */
  readonly commit: string;
};

What Git knows of a file beyond what a store says.

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