@procedures/git 0.2.2 → 0.3.0

package/src/procedures/git/branch.ts

@@ -1,61 +1,40 @@
 /**
- * git.branch procedure
+ * git.branch procedure (deprecated)
  *
- * Branch operations
+ * Branch operations. Since roadmap R40, git.branch.list, git.branch.add and git.branch.delete do
+ * this, one procedure for each operation. This procedure stays for one release, and calls them.
+ * Its inputs and outputs do not change. The current branch comes from `git symbolic-ref`, so a
+ * repository without commits works now too (before, `git rev-parse --abbrev-ref HEAD` failed).
  */
 
-import { gitArg } from "./args.js";
-import { git, type GitContext } from "./run.js";
-import type { GitBranchInput, GitBranchOutput, GitBranchInfo } from "../../types.js";
+import { type GitContext } from "./run.js";
+import { currentBranch } from "./refs.js";
+import { gitBranchList } from "./branch/list.js";
+import { gitBranchAdd } from "./branch/add.js";
+import { gitBranchDelete } from "./branch/delete.js";
+import type { GitBranchInput, GitBranchOutput } from "../../types.js";
 
 /**
  * Branch operations
+ *
+ * @deprecated Use `gitBranchList`, `gitBranchAdd` or `gitBranchDelete` (git.branch.list,
+ * git.branch.add, git.branch.delete).
  */
 export async function gitBranch(input: GitBranchInput, ctx: GitContext = {}): Promise<GitBranchOutput> {
   const { name, delete: del, list, remote, cwd } = input;
-  const run = { cwd, signal: ctx.signal };
-
-  // Get current branch
-  const current = (await git(["rev-parse", "--abbrev-ref", "HEAD"], run)).trim();
 
   // Delete branch
   if (del && name) {
-    await git(["branch", "-d", gitArg("name", name)], run);
-    return { deleted: name, current };
+    await gitBranchDelete({ name, cwd }, ctx);
+    return { deleted: name, current: await currentBranch({ cwd, signal: ctx.signal }) };
   }
 
   // Create branch
   if (name && !list) {
-    await git(["branch", gitArg("name", name)], run);
-    return { created: name, current };
+    await gitBranchAdd({ name, cwd }, ctx);
+    return { created: name, current: await currentBranch({ cwd, signal: ctx.signal }) };
   }
 
   // List branches
-  const args = ["branch"];
-  if (remote) args.push("-a");
-  // The full ref name tells local from remote branches: a local "feature/x" also contains "/"
-  args.push("--format=%(refname)|%(refname:short)|%(HEAD)|%(upstream:short)");
-
-  const output = await git(args, run);
-  const branches: GitBranchInfo[] = output
-    .split("\n")
-    .filter(Boolean)
-    .map(line => {
-      const parts = line.split("|");
-      const fullName = parts[0] ?? "";
-      const branchName = parts[1] ?? "";
-      const head = parts[2] ?? "";
-      const trackingVal = parts[3];
-      const result: GitBranchInfo = {
-        name: branchName.replace(/^remotes\//, ""),
-        current: head === "*",
-        remote: fullName.startsWith("refs/remotes/"),
-      };
-      if (trackingVal) {
-        result.tracking = trackingVal;
-      }
-      return result;
-    });
-
-  return { branches, current };
+  return gitBranchList({ remote, cwd }, ctx);
 }

package/src/procedures/git/commit.ts

@@ -14,20 +14,18 @@ export async function gitCommit(input: GitCommitInput, ctx: GitContext = {}): Pr
   const { message, all, amend, cwd } = input;
   const run = { cwd, signal: ctx.signal };
 
-  // Check if there's anything to commit (unless amending)
+  // Check if there's anything to commit (unless amending). Each line of `git status --porcelain`
+  // is "XY path": X is the index, Y the work tree, "??" an untracked file. Without -a, only a
+  // staged change counts. With -a, a change of a tracked file counts too. An untracked file is
+  // never a change to commit. (Before, any line counted, so an untracked file or an unstaged
+  // change made git commit fail with "nothing added to commit": roadmap R33.)
   if (!amend) {
-    const status = (await git(["status", "--porcelain"], run)).trim();
-    if (!status && !all) {
-      // Nothing staged and not using -a, skip commit
+    const lines = (await git(["status", "--porcelain"], run)).split("\n").filter((line) => line.length > 0);
+    const tracked = lines.filter((line) => !line.startsWith("??") && !line.startsWith("!!"));
+    const staged = tracked.filter((line) => line[0] !== " ");
+    if ((all ? tracked : staged).length === 0) {
       return { hash: "", message: "", author: "", date: "", skipped: true };
     }
-    // If using -a, check if there are any modified files
-    if (all) {
-      const hasChanges = status.length > 0;
-      if (!hasChanges) {
-        return { hash: "", message: "", author: "", date: "", skipped: true };
-      }
-    }
   }
 
   const args: string[] = ["commit"];

package/src/procedures/git/index.ts

@@ -20,3 +20,22 @@ export {
   gitStashExport,
   gitStashImport,
 } from "./stash.js";
+export { gitShow } from "./show.js";
+export { gitBlame } from "./blame.js";
+export { gitTagList } from "./tag/list.js";
+export { gitTagAdd } from "./tag/add.js";
+export { gitTagDelete } from "./tag/delete.js";
+export { gitRevParse } from "./revParse.js";
+export { gitReset } from "./reset.js";
+export { gitRestore } from "./restore.js";
+export { gitMerge } from "./merge.js";
+export { gitMergeAbort } from "./merge/abort.js";
+export { gitRebase } from "./rebase.js";
+export { gitRebaseContinue } from "./rebase/continue.js";
+export { gitRebaseAbort } from "./rebase/abort.js";
+export { gitWorktreeList } from "./worktree/list.js";
+export { gitWorktreeAdd } from "./worktree/add.js";
+export { gitWorktreeRemove } from "./worktree/remove.js";
+export { gitBranchList } from "./branch/list.js";
+export { gitBranchAdd } from "./branch/add.js";
+export { gitBranchDelete } from "./branch/delete.js";

package/src/procedures/git/init.ts

@@ -2,28 +2,29 @@
  * git.init procedure
  *
  * Initialize a git repository
+ *
+ * The procedure looks for `.git` in the folder itself. Before, it called `fs.exists` through
+ * `ctx.client`, so a registry of `gitModule` alone (`createRegistry(gitModule)`) did not have the
+ * procedure that it called, and `git.init` always failed there (roadmap R33).
  */
 
+import { access } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import type { ProcedureContext } from "@procedures/client";
-import { git } from "./run.js";
+import { git, type GitContext } from "./run.js";
 import type { GitInitInput, GitInitOutput } from "../../types.js";
 
-interface FsExistsOutput { exists: boolean; path: string; }
-
 /**
  * Initialize a git repository
  */
-export async function gitInit(input: GitInitInput, ctx: ProcedureContext): Promise<GitInitOutput> {
+export async function gitInit(input: GitInitInput, ctx: GitContext = {}): Promise<GitInitOutput> {
   const cwd = input.cwd ? resolve(input.cwd) : process.cwd();
 
-  // Check if already a git repo
+  // Check if already a git repo (as fs.exists did: an error of the check means "no")
   const gitDir = join(cwd, ".git");
-  const existsResult = await ctx.client.call<{ path: string }, FsExistsOutput>(
-    ["fs", "exists"],
-    { path: gitDir }
+  const alreadyExists = await access(gitDir).then(
+    () => true,
+    () => false,
   );
-  const alreadyExists = existsResult.exists;
 
   if (!alreadyExists) {
     const args: string[] = ["init"];

package/src/procedures/git/merge/abort.ts

@@ -0,0 +1,20 @@
+/**
+ * git.merge.abort procedure
+ *
+ * Stop a merge that has conflicts (roadmap R40). Git puts back the branch and the files as they
+ * were before the merge. The resolutions of the conflicts are lost. Without a merge, the call
+ * fails.
+ */
+
+import { git, type GitContext } from "../run.js";
+import { headHash } from "../refs.js";
+import type { GitMergeAbortInput, GitMergeAbortOutput } from "../../../types.js";
+
+/**
+ * Stop a merge that has conflicts
+ */
+export async function gitMergeAbort(input: GitMergeAbortInput, ctx: GitContext = {}): Promise<GitMergeAbortOutput> {
+  const run = { cwd: input.cwd, signal: ctx.signal };
+  await git(["merge", "--abort"], run);
+  return { aborted: true, hash: await headHash(run) };
+}

package/src/procedures/git/merge.ts

@@ -0,0 +1,42 @@
+/**
+ * git.merge procedure
+ *
+ * Merge a branch or a commit into the current branch (roadmap R40).
+ *
+ * A merge that stops on conflicts is a result, not an error: `conflict` is true, and `conflicts`
+ * names the files. Then resolve them and call git.commit, or call git.merge.abort. Git does not
+ * start an editor for the message of the merge commit.
+ */
+
+import { gitArg } from "./args.js";
+import { git, type GitContext } from "./run.js";
+import { commitOf, conflictedFiles, headHash, NO_EDITOR, stoppedOnConflict } from "./refs.js";
+import type { GitMergeInput, GitMergeOutput } from "../../types.js";
+
+/**
+ * Merge a branch or a commit into the current branch
+ */
+export async function gitMerge(input: GitMergeInput, ctx: GitContext = {}): Promise<GitMergeOutput> {
+  const { ref, message, cwd } = input;
+  const fastForward = input.fastForward ?? "auto";
+  const run = { cwd, signal: ctx.signal };
+
+  const target = await commitOf(ref, run);
+  const before = await headHash(run);
+
+  const args = ["merge", "--no-edit"];
+  if (fastForward === "only") args.push("--ff-only");
+  if (fastForward === "never") args.push("--no-ff");
+  if (message !== undefined) args.push("-m", message);
+  args.push(gitArg("ref", ref));
+
+  try {
+    await git(args, { ...run, env: NO_EDITOR });
+  } catch (error) {
+    if (!stoppedOnConflict(error)) throw error;
+    return { ref, hash: before, fastForward: false, upToDate: false, conflict: true, conflicts: await conflictedFiles(run) };
+  }
+
+  const after = await headHash(run);
+  return { ref, hash: after, fastForward: after !== before && after === target, upToDate: after === before, conflict: false };
+}

package/src/procedures/git/push.ts

@@ -6,6 +6,7 @@
 
 import { gitArg } from "./args.js";
 import { git, GitError, type GitContext } from "./run.js";
+import { currentBranch } from "./refs.js";
 import type { GitPushInput, GitPushOutput } from "../../types.js";
 
 /**
@@ -16,8 +17,9 @@ export async function gitPush(input: GitPushInput, ctx: GitContext = {}): Promis
   const remoteName = input.remote ?? "origin";
   const run = { cwd, signal: ctx.signal };
 
-  // Get current branch if not specified
-  const branchName = branch || (await git(["rev-parse", "--abbrev-ref", "HEAD"], run)).trim();
+  // The current branch if not specified. `git symbolic-ref` reads it in a repository without
+  // commits too, so git gives its own error there (roadmap R40).
+  const branchName = branch || (await currentBranch(run));
 
   // Count commits to push
   let commits = 0;

package/src/procedures/git/rebase/abort.ts

@@ -0,0 +1,19 @@
+/**
+ * git.rebase.abort procedure
+ *
+ * Stop a rebase, and go back to the branch as it was before the rebase (roadmap R40). The
+ * resolutions of the conflicts are lost. Without a rebase, the call fails.
+ */
+
+import { git, type GitContext } from "../run.js";
+import { headHash } from "../refs.js";
+import type { GitRebaseAbortInput, GitRebaseAbortOutput } from "../../../types.js";
+
+/**
+ * Stop a rebase, and go back to the branch before it
+ */
+export async function gitRebaseAbort(input: GitRebaseAbortInput, ctx: GitContext = {}): Promise<GitRebaseAbortOutput> {
+  const run = { cwd: input.cwd, signal: ctx.signal };
+  await git(["rebase", "--abort"], run);
+  return { aborted: true, hash: await headHash(run) };
+}

package/src/procedures/git/rebase/continue.ts

@@ -0,0 +1,25 @@
+/**
+ * git.rebase.continue procedure
+ *
+ * Continue a rebase after the conflicts are resolved and staged (roadmap R40). Git keeps the
+ * message of each commit: it does not start an editor. A next commit can stop on conflicts again.
+ */
+
+import { type GitContext } from "../run.js";
+import { conflictedFiles, headHash } from "../refs.js";
+import { rebaseStep } from "../rebase.js";
+import type { GitRebaseContinueInput, GitRebaseContinueOutput } from "../../../types.js";
+
+/**
+ * Continue a rebase after the conflicts are resolved
+ */
+export async function gitRebaseContinue(input: GitRebaseContinueInput, ctx: GitContext = {}): Promise<GitRebaseContinueOutput> {
+  const run = { cwd: input.cwd, signal: ctx.signal };
+  // Files that still have conflicts: git refuses to continue, so the call gives them
+  const unresolved = await conflictedFiles(run);
+  if (unresolved.length > 0) {
+    return { hash: await headHash(run), completed: false, upToDate: false, conflict: true, conflicts: unresolved };
+  }
+  // A continued rebase changed the branch: upToDate is false
+  return rebaseStep(["rebase", "--continue"], "", run);
+}

package/src/procedures/git/rebase.ts

@@ -0,0 +1,48 @@
+/**
+ * git.rebase procedure
+ *
+ * Rebase the current branch on another branch (roadmap R40). The rebase is never interactive,
+ * and git does not start an editor.
+ *
+ * A rebase that stops on conflicts is a result, not an error: `conflict` is true, and
+ * `conflicts` names the files. Then resolve them, stage them with git.add and call
+ * git.rebase.continue, or call git.rebase.abort.
+ */
+
+import { gitArg } from "./args.js";
+import { git, type GitContext, type GitRunOptions } from "./run.js";
+import { commitOf, conflictedFiles, headHash, NO_EDITOR, stoppedOnConflict } from "./refs.js";
+import type { GitRebaseInput, GitRebaseOutput } from "../../types.js";
+
+/**
+ * This function runs a step of a rebase (the start or `--continue`), and gives its result. A
+ * stop on conflicts gives `conflict: true`. Any other failure throws.
+ */
+export async function rebaseStep(args: string[], before: string, run: GitRunOptions): Promise<GitRebaseOutput> {
+  try {
+    await git(args, { ...run, env: NO_EDITOR });
+  } catch (error) {
+    if (!stoppedOnConflict(error)) throw error;
+    return { hash: await headHash(run), completed: false, upToDate: false, conflict: true, conflicts: await conflictedFiles(run) };
+  }
+  const hash = await headHash(run);
+  return { hash, completed: true, upToDate: hash === before, conflict: false };
+}
+
+/**
+ * Rebase the current branch on another branch
+ */
+export async function gitRebase(input: GitRebaseInput, ctx: GitContext = {}): Promise<GitRebaseOutput> {
+  const { upstream, onto, branch, cwd } = input;
+  const run = { cwd, signal: ctx.signal };
+
+  // With a branch, git checks it out first: compare with that branch
+  const before = branch ? await commitOf(branch, run) : await headHash(run);
+
+  const args = ["rebase"];
+  if (onto) args.push("--onto", gitArg("onto", onto));
+  args.push(gitArg("upstream", upstream));
+  if (branch) args.push(gitArg("branch", branch));
+
+  return rebaseStep(args, before, run);
+}

package/src/procedures/git/refs.ts

@@ -0,0 +1,55 @@
+/**
+ * Helpers of the git procedures of roadmap R40: the current branch, the hash of a ref, the
+ * files with conflicts, and the stop of a merge or a rebase on conflicts.
+ */
+
+import { gitArg } from "./args.js";
+import { git, GitError, zFields, type GitRunOptions } from "./run.js";
+
+/**
+ * The current branch, or "HEAD" when HEAD is detached.
+ *
+ * `git rev-parse --abbrev-ref HEAD` fails in a repository without commits (roadmap R33), because
+ * HEAD names a branch that does not exist yet. `git symbolic-ref` reads the name that HEAD
+ * holds, so it works there too. It fails only for a detached HEAD.
+ */
+export async function currentBranch(run: GitRunOptions): Promise<string> {
+  try {
+    return (await git(["symbolic-ref", "--quiet", "--short", "HEAD"], run)).trim();
+  } catch (error) {
+    if (!(error instanceof GitError)) throw error;
+    // A detached HEAD: exit 1 and no message. Outside a repository: exit 128, and that is an error.
+    if (error.exitCode === 1) return "HEAD";
+    throw error;
+  }
+}
+
+/** The hash of the commit of a ref (a tag gives its commit). It throws a `GitError` for an unknown ref. */
+export async function commitOf(ref: string, run: GitRunOptions): Promise<string> {
+  return (await git(["rev-parse", "--verify", `${gitArg("ref", ref)}^{commit}`], run)).trim();
+}
+
+/** The hash of HEAD. */
+export async function headHash(run: GitRunOptions): Promise<string> {
+  return (await git(["rev-parse", "--verify", "HEAD"], run)).trim();
+}
+
+/** The files that have conflicts, as `git diff --diff-filter=U` gives them. */
+export async function conflictedFiles(run: GitRunOptions): Promise<string[]> {
+  return zFields(await git(["diff", "--name-only", "--diff-filter=U", "-z"], run));
+}
+
+/**
+ * True when a failed merge or rebase stopped on conflicts. Git writes "CONFLICT (content): ..."
+ * to stdout, and "could not apply" to stderr. Any other failure (a working tree with changes, an
+ * unknown ref) is an error of the call.
+ */
+export function stoppedOnConflict(error: unknown): boolean {
+  return error instanceof GitError && /^CONFLICT \(|could not apply/im.test(`${error.stdout}\n${error.stderr}`);
+}
+
+/**
+ * The environment of a merge or a rebase. Git does not start an editor for a message: it keeps
+ * the message that it made. `GIT_EDITOR` overrides `core.editor` and `EDITOR` of the machine.
+ */
+export const NO_EDITOR: Record<string, string> = { GIT_EDITOR: "true" };

package/src/procedures/git/reset.ts

@@ -0,0 +1,34 @@
+/**
+ * git.reset procedure
+ *
+ * Move HEAD to a commit, and reset the index or the working tree (roadmap R40). The mode hard
+ * deletes the changes of the working tree that are not committed.
+ */
+
+import { gitArg } from "./args.js";
+import { git, type GitContext } from "./run.js";
+import { headHash } from "./refs.js";
+import type { GitResetInput, GitResetOutput } from "../../types.js";
+
+/**
+ * Move HEAD to a commit, and reset the index or the working tree
+ */
+export async function gitReset(input: GitResetInput, ctx: GitContext = {}): Promise<GitResetOutput> {
+  const ref = input.ref ?? "HEAD";
+  const mode = input.mode ?? "mixed";
+  const run = { cwd: input.cwd, signal: ctx.signal };
+
+  const args = ["reset", "--quiet"];
+  if (input.paths && input.paths.length > 0) {
+    // Git resets paths only in the index: HEAD and the working tree stay
+    if (mode !== "mixed") {
+      throw new Error(`git.reset: paths need the mode mixed, not ${mode}`);
+    }
+    args.push(gitArg("ref", ref), "--", ...input.paths);
+  } else {
+    args.push(`--${mode}`, gitArg("ref", ref));
+  }
+  await git(args, run);
+
+  return { ref, mode, hash: await headHash(run) };
+}

package/src/procedures/git/restore.ts

@@ -0,0 +1,27 @@
+/**
+ * git.restore procedure
+ *
+ * Restore files of the working tree or the index (roadmap R40). A restore of the working tree
+ * deletes the changes of the files that are not committed.
+ */
+
+import { gitArg } from "./args.js";
+import { git, type GitContext } from "./run.js";
+import type { GitRestoreInput, GitRestoreOutput } from "../../types.js";
+
+/**
+ * Restore files of the working tree or the index
+ */
+export async function gitRestore(input: GitRestoreInput, ctx: GitContext = {}): Promise<GitRestoreOutput> {
+  const { paths, source, staged, worktree, cwd } = input;
+
+  const args = ["restore"];
+  if (source) args.push(`--source=${gitArg("source", source)}`);
+  if (staged) args.push("--staged");
+  if (worktree) args.push("--worktree");
+  // After "--", a path that starts with "-" stays a path
+  args.push("--", ...paths);
+  await git(args, { cwd, signal: ctx.signal });
+
+  return { restored: paths };
+}

package/src/procedures/git/revParse.ts

@@ -0,0 +1,24 @@
+/**
+ * git.revParse procedure
+ *
+ * Give the hash or the name of a ref (roadmap R40). With `--verify`, git gives exactly one value,
+ * or fails for an unknown ref.
+ */
+
+import { gitArg } from "./args.js";
+import { git, type GitContext } from "./run.js";
+import type { GitRevParseInput, GitRevParseOutput } from "../../types.js";
+
+/**
+ * Give the hash or the name of a ref
+ */
+export async function gitRevParse(input: GitRevParseInput, ctx: GitContext = {}): Promise<GitRevParseOutput> {
+  const ref = input.ref ?? "HEAD";
+  const args = ["rev-parse", "--verify"];
+  if (input.abbrevRef) args.push("--abbrev-ref");
+  else if (input.short) args.push("--short");
+  args.push(gitArg("ref", ref));
+
+  const value = (await git(args, { cwd: input.cwd, signal: ctx.signal })).trim();
+  return { ref, value };
+}

package/src/procedures/git/run.ts

@@ -18,6 +18,8 @@ export interface GitRunOptions extends GitContext {
   cwd?: string | undefined;
   /** Text to write to the stdin of git (for example a patch for `git apply`). */
   input?: string | undefined;
+  /** Environment variables to add for git (for example `GIT_EDITOR`). */
+  env?: Record<string, string> | undefined;
 }
 
 /** A git command that ended with an exit code other than 0. */
@@ -43,6 +45,7 @@ export async function git(args: string[], options: GitRunOptions = {}): Promise<
     cwd: options.cwd,
     signal: options.signal,
     input: options.input,
+    env: options.env,
     maxOutputBytes: GIT_MAX_BUFFER,
   });
   if (result.aborted) {

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/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 };
+}