@procedures/git 0.2.3 → 0.4.0

package/src/procedures/git/show.ts

@@ -0,0 +1,57 @@
+/**
+ * git.show procedure
+ *
+ * Show a commit, or a file at a commit (roadmap R40).
+ *
+ * The procedure first resolves the ref to its commit, so a tag gives its commit and not the text
+ * of the tag object. A merge commit gives its changes against its first parent.
+ */
+
+import { parseNumstat } from "./diff.js";
+import { git, type GitContext } from "./run.js";
+import { commitOf } from "./refs.js";
+import type { GitShowInput, GitShowOutput } from "../../types.js";
+
+// Control characters that do not occur in a name, an email, a date or a subject
+const FIELD = "\x1f";
+
+/**
+ * Show a commit, or a file at a commit
+ */
+export async function gitShow(input: GitShowInput, ctx: GitContext = {}): Promise<GitShowOutput> {
+  const ref = input.ref ?? "HEAD";
+  const run = { cwd: input.cwd, signal: ctx.signal };
+  const hash = await commitOf(ref, run);
+
+  // A file at the commit: `<hash>:<path>` starts with the hash, so a path that starts with "-"
+  // stays a path
+  if (input.path !== undefined) {
+    const content = await git(["show", `${hash}:${input.path}`], run);
+    return { ref, hash, path: input.path, content };
+  }
+
+  const format = `--format=${["%H", "%h", "%an", "%ae", "%ci", "%s", "%b"].join("%x1f")}`;
+  const [, shortHash = "", author = "", email = "", date = "", message = "", body = ""] = (
+    await git(["show", "-s", format, hash], run)
+  ).split(FIELD);
+
+  const changes = ["show", "--format=", "--diff-merges=first-parent"];
+  const files = parseNumstat(await git([...changes, "--numstat", "-z", hash], run));
+  const result: GitShowOutput = {
+    ref,
+    hash,
+    shortHash,
+    author,
+    email,
+    date,
+    message,
+    body: body.replace(/\n+$/, ""),
+    files,
+    additions: files.reduce((sum, file) => sum + file.additions, 0),
+    deletions: files.reduce((sum, file) => sum + file.deletions, 0),
+  };
+  if (!input.stat) {
+    result.diff = (await git([...changes, "--patch", hash], run)).replace(/^\n/, "");
+  }
+  return result;
+}

package/src/procedures/git/status.ts

@@ -10,23 +10,9 @@
  */
 
 import { git, zFields, type GitContext } from "./run.js";
+import { classifyStatus as classify } from "./porcelain.js";
 import type { GitStatusInput, GitStatusOutput, GitStatusFile } from "../../types.js";
 
-/** The status of one entry, from its two status letters (index, then work tree). */
-function classify(xy: string): Pick<GitStatusFile, "status" | "staged"> {
-  const index = xy[0];
-  const worktree = xy[1];
-  if (index === "A") return { status: "added", staged: true };
-  if (index === "D") return { status: "deleted", staged: true };
-  if (index === "R") return { status: "renamed", staged: true };
-  if (index === "C") return { status: "copied", staged: true };
-  if (index === "M" || index === "T") return { status: "modified", staged: true };
-  if (worktree === "D") return { status: "deleted", staged: false };
-  if (worktree === "A") return { status: "added", staged: false };
-  if (worktree === "R") return { status: "renamed", staged: false };
-  return { status: "modified", staged: false };
-}
-
 /** The text after the first `count` space-separated fields of a line. */
 function afterFields(line: string, count: number): string {
   let at = 0;
@@ -35,10 +21,16 @@ function afterFields(line: string, count: number): string {
 }
 
 /**
- * Get git status
+ * This function gives the git status. With `paths`, it gives only the files of those pathspecs.
+ * With `untrackedFiles`, git lists the untracked files in that mode: "all" lists each file of a
+ * new folder.
  */
 export async function gitStatus(input: GitStatusInput, ctx: GitContext = {}): Promise<GitStatusOutput> {
-  const output = await git(["status", "--porcelain=v2", "--branch", "-z"], { cwd: input.cwd, signal: ctx.signal });
+  const args = ["status", "--porcelain=v2", "--branch", "-z"];
+  if (input.untrackedFiles !== undefined) args.push(`--untracked-files=${input.untrackedFiles}`);
+  // After "--", git reads each value as a pathspec, also a value that starts with "-"
+  if (input.paths !== undefined && input.paths.length > 0) args.push("--", ...input.paths);
+  const output = await git(args, { cwd: input.cwd, signal: ctx.signal });
 
   let branch = "HEAD";
   let ahead = 0;

package/src/procedures/git/tag/add.ts

@@ -0,0 +1,27 @@
+/**
+ * git.tag.add procedure
+ *
+ * Make a tag (roadmap R40). An existing tag is an error: the procedure never moves a tag.
+ */
+
+import { gitArg } from "../args.js";
+import { git, type GitContext } from "../run.js";
+import { commitOf } from "../refs.js";
+import type { GitTagAddInput, GitTagAddOutput } from "../../../types.js";
+
+/**
+ * Make a tag
+ */
+export async function gitTagAdd(input: GitTagAddInput, ctx: GitContext = {}): Promise<GitTagAddOutput> {
+  const { name, ref, message, cwd } = input;
+  const run = { cwd, signal: ctx.signal };
+
+  const args = ["tag"];
+  // With -m, git makes an annotated tag and does not start an editor
+  if (message !== undefined) args.push("-a", "-m", message);
+  args.push(gitArg("name", name));
+  if (ref) args.push(gitArg("ref", ref));
+  await git(args, run);
+
+  return { name, hash: await commitOf(`refs/tags/${name}`, run), annotated: message !== undefined };
+}

package/src/procedures/git/tag/delete.ts

@@ -0,0 +1,22 @@
+/**
+ * git.tag.delete procedure
+ *
+ * Delete a tag (roadmap R40).
+ */
+
+import { gitArg } from "../args.js";
+import { git, type GitContext } from "../run.js";
+import type { GitTagDeleteInput, GitTagDeleteOutput } from "../../../types.js";
+
+/**
+ * Delete a tag
+ */
+export async function gitTagDelete(input: GitTagDeleteInput, ctx: GitContext = {}): Promise<GitTagDeleteOutput> {
+  const name = gitArg("name", input.name);
+  const run = { cwd: input.cwd, signal: ctx.signal };
+
+  // The object of the tag before the deletion: a tag object or a commit
+  const hash = (await git(["rev-parse", "--verify", `refs/tags/${name}`], run)).trim();
+  await git(["tag", "-d", name], run);
+  return { name, hash };
+}

package/src/procedures/git/tag/list.ts

@@ -0,0 +1,36 @@
+/**
+ * git.tag.list procedure
+ *
+ * List the tags (roadmap R40).
+ */
+
+import { gitArg } from "../args.js";
+import { git, type GitContext } from "../run.js";
+import type { GitTagInfo, GitTagListInput, GitTagListOutput } from "../../../types.js";
+
+/**
+ * The fields of each tag, separated by NUL: the name, the type of the object, the commit of an
+ * annotated tag, the object, and the subject of the message.
+ */
+const FORMAT = "--format=%(refname:strip=2)%00%(objecttype)%00%(*objectname)%00%(objectname)%00%(contents:subject)";
+
+/**
+ * List the tags
+ */
+export async function gitTagList(input: GitTagListInput, ctx: GitContext = {}): Promise<GitTagListOutput> {
+  const args = ["tag", "--list", FORMAT];
+  if (input.pattern) args.push(gitArg("pattern", input.pattern));
+
+  const output = await git(args, { cwd: input.cwd, signal: ctx.signal });
+  const tags: GitTagInfo[] = output
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .map((line) => {
+      const [name = "", type = "", peeled = "", object = "", subject = ""] = line.split("\0");
+      const annotated = type === "tag";
+      const tag: GitTagInfo = { name, hash: annotated && peeled ? peeled : object, annotated };
+      if (annotated) tag.message = subject;
+      return tag;
+    });
+  return { tags };
+}

package/src/procedures/git/worktree/add.ts

@@ -0,0 +1,35 @@
+/**
+ * git.worktree.add procedure
+ *
+ * Add a working tree (roadmap R40). Git refuses a folder that exists and is not empty. Without
+ * `ref`, `branch` and `detach`, git makes a branch with the name of the folder.
+ */
+
+import { resolve } from "node:path";
+import { gitArg } from "../args.js";
+import { git, type GitContext } from "../run.js";
+import { currentBranch, headHash } from "../refs.js";
+import type { GitWorktreeAddInput, GitWorktreeAddOutput } from "../../../types.js";
+
+/**
+ * Add a working tree
+ */
+export async function gitWorktreeAdd(input: GitWorktreeAddInput, ctx: GitContext = {}): Promise<GitWorktreeAddOutput> {
+  const { ref, branch, detach, cwd } = input;
+  const path = resolve(cwd ?? process.cwd(), input.path);
+
+  const args = ["worktree", "add"];
+  if (branch) args.push("-b", gitArg("branch", branch));
+  if (detach) args.push("--detach");
+  // After "--", a path that starts with "-" stays a path
+  args.push("--", path);
+  if (ref) args.push(gitArg("ref", ref));
+  await git(args, { cwd, signal: ctx.signal });
+
+  // The new working tree gives its own HEAD
+  const inTree = { cwd: path, signal: ctx.signal };
+  const result: GitWorktreeAddOutput = { path, head: await headHash(inTree) };
+  const checkedOut = await currentBranch(inTree);
+  if (checkedOut !== "HEAD") result.branch = checkedOut;
+  return result;
+}

package/src/procedures/git/worktree/list.ts

@@ -0,0 +1,48 @@
+/**
+ * git.worktree.list procedure
+ *
+ * List the working trees of the repository (roadmap R40). The main working tree is first.
+ */
+
+import { resolve } from "node:path";
+import { git, zFields, type GitContext } from "../run.js";
+import type { GitWorktreeInfo, GitWorktreeListInput, GitWorktreeListOutput } from "../../../types.js";
+
+/**
+ * This function reads the output of `git worktree list --porcelain -z`: the fields of one working
+ * tree, then an empty field.
+ */
+export function parseWorktrees(output: string): GitWorktreeInfo[] {
+  const worktrees: GitWorktreeInfo[] = [];
+  let current: GitWorktreeInfo | undefined;
+  for (const field of zFields(output)) {
+    if (field === "") {
+      current = undefined;
+      continue;
+    }
+    const space = field.indexOf(" ");
+    const key = space < 0 ? field : field.slice(0, space);
+    const value = space < 0 ? "" : field.slice(space + 1);
+    if (key === "worktree") {
+      // Git gives "/" on Windows too: resolve gives the path of the platform
+      current = { path: resolve(value), detached: false, bare: false, locked: false, prunable: false };
+      worktrees.push(current);
+    } else if (current) {
+      if (key === "HEAD") current.head = value;
+      else if (key === "branch") current.branch = value.replace(/^refs\/heads\//, "");
+      else if (key === "detached") current.detached = true;
+      else if (key === "bare") current.bare = true;
+      else if (key === "locked") current.locked = true;
+      else if (key === "prunable") current.prunable = true;
+    }
+  }
+  return worktrees;
+}
+
+/**
+ * List the working trees of the repository
+ */
+export async function gitWorktreeList(input: GitWorktreeListInput, ctx: GitContext = {}): Promise<GitWorktreeListOutput> {
+  const output = await git(["worktree", "list", "--porcelain", "-z"], { cwd: input.cwd, signal: ctx.signal });
+  return { worktrees: parseWorktrees(output) };
+}

package/src/procedures/git/worktree/remove.ts

@@ -0,0 +1,21 @@
+/**
+ * git.worktree.remove procedure
+ *
+ * Remove a working tree and its folder (roadmap R40). Git refuses a working tree with changes
+ * that are not committed, unless `force` is true. Then the changes are lost.
+ */
+
+import { git, type GitContext } from "../run.js";
+import type { GitWorktreeRemoveInput, GitWorktreeRemoveOutput } from "../../../types.js";
+
+/**
+ * Remove a working tree
+ */
+export async function gitWorktreeRemove(input: GitWorktreeRemoveInput, ctx: GitContext = {}): Promise<GitWorktreeRemoveOutput> {
+  const args = ["worktree", "remove"];
+  if (input.force) args.push("--force");
+  // After "--", a path that starts with "-" stays a path
+  args.push("--", input.path);
+  await git(args, { cwd: input.cwd, signal: ctx.signal });
+  return { path: input.path };
+}