Git and Pull Request Workflows

// The new pairing flow is merged and deployed, but only shown where the flag is on.
export function pairingScreen(user, flags) {
  if (flags.isEnabled("new-pairing-flow", { userId: user.id, tenant: user.tenant })) {
    return renderNewPairingFlow(user);
  }
  return renderLegacyPairing(user);
}

// Two people on one pushed branch. Asha rebases and force-pushes; --force-with-lease refuses
// to overwrite Ravi's commit that she hasn't seen. Real git with a local bare "origin", Git 2.54.
import { execFileSync } from "node:child_process";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const root = mkdtempSync(join(tmpdir(), "git-demo-"));
let minute = 0;
const as = (who, cwd) => (...args) => {
  const date = `${1767603600 + 60 * minute++} +0000`;
  const email = `${who.toLowerCase()}@example.com`;
  return execFileSync("git", args, {
    cwd: join(root, cwd), encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
    env: { ...process.env, LC_ALL: "C", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1",
      GIT_AUTHOR_NAME: who, GIT_AUTHOR_EMAIL: email, GIT_AUTHOR_DATE: date,
      GIT_COMMITTER_NAME: who, GIT_COMMITTER_EMAIL: email, GIT_COMMITTER_DATE: date },
  }).trimEnd();
};
const commit = (git, cwd, file, msg) => { writeFileSync(join(root, cwd, file), msg); git("add", file); git("commit", "-q", "-m", msg); };
const lastLine = (err) => err.stderr.trim().split("\n").filter((l) => l.includes("rejected"))[0].trim();

try {
  as("Asha", ".")("-c", "init.defaultBranch=main", "init", "-q", "--bare", "origin.git");
  as("Asha", ".")("clone", "-q", "origin.git", "asha");
  const asha = as("Asha", "asha");
  commit(asha, "asha", "app.js", "chore: initial commit");
  asha("push", "-q", "origin", "HEAD:main");
  asha("switch", "-q", "-c", "feature/pairing");
  commit(asha, "asha", "pair.js", "feat: pairing screen");
  asha("push", "-q", "-u", "origin", "feature/pairing");

  as("Ravi", ".")("clone", "-q", "origin.git", "ravi");
  const ravi = as("Ravi", "ravi");
  ravi("switch", "-q", "feature/pairing");
  commit(ravi, "ravi", "pair-test.js", "test: pairing screen");
  ravi("push", "-q", "origin", "feature/pairing"); // Asha hasn't fetched this

  asha("switch", "-q", "main"); // meanwhile main moves on
  commit(asha, "asha", "README.md", "docs: readme");
  asha("push", "-q", "origin", "main");
  asha("switch", "-q", "feature/pairing");
  asha("rebase", "-q", "main");

  try { asha("push", "-q", "origin", "feature/pairing"); } catch (e) { console.log(`plain push:          ${lastLine(e)}`); }
  try { asha("push", "-q", "--force-with-lease", "origin", "feature/pairing"); } catch (e) { console.log(`--force-with-lease:  ${lastLine(e)}`); }
  asha("fetch", "-q"); // now her lease is fresh, but she still hasn't looked at Ravi's commit
  try { asha("push", "-q", "--force-with-lease", "--force-if-includes", "origin", "feature/pairing"); }
  catch (e) { console.log(`after fetch, --force-with-lease --force-if-includes:  ${lastLine(e)}`); }

  // The right fix: start from what's really on origin, replay it onto main, then push with the lease.
  asha("reset", "-q", "--hard", "origin/feature/pairing");
  asha("rebase", "-q", "main");
  asha("push", "-q", "--force-with-lease", "--force-if-includes", "origin", "feature/pairing");
  console.log("\norigin/feature/pairing after the rebuilt push:\n" + asha("log", "--format=  %h %an: %s", "origin/feature/pairing"));
} finally {
  rmSync(root, { recursive: true, force: true });
}

plain push:          ! [rejected]        feature/pairing -> feature/pairing (fetch first)
--force-with-lease:  ! [rejected]        feature/pairing -> feature/pairing (stale info)
after fetch, --force-with-lease --force-if-includes:  ! [rejected]        feature/pairing -> feature/pairing (remote ref updated since checkout)

origin/feature/pairing after the rebuilt push:
  e749ef2 Ravi: test: pairing screen
  7e91f57 Asha: feat: pairing screen
  3a22314 Asha: docs: readme
  f7a05c6 Asha: chore: initial commit

// A commit-msg hook that enforces Conventional Commits, installed in a throwaway repository and
// exercised with real `git commit` calls (fixed names and dates, Git 2.54).
import { execFileSync } from "node:child_process";
import { mkdtempSync, rmSync, writeFileSync, chmodSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const dir = mkdtempSync(join(tmpdir(), "git-demo-"));
let minute = 0;
const git = (...args) => {
  const date = `${1767603600 + 60 * minute++} +0000`;
  return execFileSync("git", args, {
    cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
    env: { ...process.env, LC_ALL: "C", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1",
      GIT_AUTHOR_NAME: "Asha", GIT_AUTHOR_EMAIL: "asha@example.com", GIT_AUTHOR_DATE: date,
      GIT_COMMITTER_NAME: "Asha", GIT_COMMITTER_EMAIL: "asha@example.com", GIT_COMMITTER_DATE: date },
  }).trimEnd();
};

// The hook: git runs .git/hooks/commit-msg with the path of the message file; non-zero exit aborts.
const hook = `#!/bin/sh
header=$(head -n 1 "$1")
pattern='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\\([a-z0-9-]+\\))?!?: [a-z].*[^.]$'
if ! printf '%s' "$header" | grep -Eq "$pattern"; then
  echo "commit-msg: header must look like 'type(scope): summary' (got: $header)" >&2
  exit 1
fi
if [ \${#header} -gt 72 ]; then
  echo "commit-msg: header is \${#header} characters; keep it to 72" >&2
  exit 1
fi
`;

try {
  git("-c", "init.defaultBranch=main", "init", "-q");
  writeFileSync(join(dir, ".git/hooks/commit-msg"), hook);
  chmodSync(join(dir, ".git/hooks/commit-msg"), 0o755);

  const tries = [
    "fixed stuff",
    "feat(api): Add device reboot endpoint.",
    "feat(api): add device reboot endpoint",
    "fix(ui)!: rename the volume slider event to volume-change",
    "chore: " + "x".repeat(70),
  ];
  for (const [i, msg] of tries.entries()) {
    writeFileSync(join(dir, "change.txt"), `change ${i}\n`);
    git("add", "change.txt");
    try {
      git("commit", "-q", "-m", msg);
      console.log(`accepted  ${msg}`);
    } catch (err) {
      console.log(`rejected  ${err.stderr.trim()}`);
    }
  }
  console.log("\ngit log --oneline\n" + git("log", "--oneline"));
} finally {
  rmSync(dir, { recursive: true, force: true });
}

rejected  commit-msg: header must look like 'type(scope): summary' (got: fixed stuff)
rejected  commit-msg: header must look like 'type(scope): summary' (got: feat(api): Add device reboot endpoint.)
accepted  feat(api): add device reboot endpoint
accepted  fix(ui)!: rename the volume slider event to volume-change
rejected  commit-msg: header is 77 characters; keep it to 72

git log --oneline
4e31e83 fix(ui)!: rename the volume slider event to volume-change
7581236 feat(api): add device reboot endpoint

// Reads Conventional Commit messages since the last tag from a real repository and works out the
// next Semantic Version and a changelog, the way release tools do (fixed names and dates, Git 2.54).
import { execFileSync } from "node:child_process";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const dir = mkdtempSync(join(tmpdir(), "git-demo-"));
let minute = 0;
const git = (...args) => {
  const date = `${1767603600 + 60 * minute++} +0000`;
  return execFileSync("git", args, {
    cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
    env: { ...process.env, LC_ALL: "C", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1",
      GIT_AUTHOR_NAME: "Asha", GIT_AUTHOR_EMAIL: "asha@example.com", GIT_AUTHOR_DATE: date,
      GIT_COMMITTER_NAME: "Asha", GIT_COMMITTER_EMAIL: "asha@example.com", GIT_COMMITTER_DATE: date },
  }).trimEnd();
};
let n = 0;
const commit = (msg) => { writeFileSync(join(dir, "log.txt"), `${n++}\n`); git("add", "."); git("commit", "-q", "-m", msg); };

function nextVersion(current, messages) {
  let [major, minor, patch] = current.replace(/^v/, "").split(".").map(Number);
  const breaking = messages.some((m) => /^\w+(\(.+\))?!:/.test(m) || /^BREAKING[ -]CHANGE: /m.test(m));
  if (breaking) return `v${major + 1}.0.0`;
  if (messages.some((m) => /^feat(\(.+\))?:/.test(m))) return `v${major}.${minor + 1}.0`;
  if (messages.some((m) => /^fix(\(.+\))?:/.test(m))) return `v${major}.${minor}.${patch + 1}`;
  return current; // docs, chore, test… alone don't need a release
}

try {
  git("-c", "init.defaultBranch=main", "init", "-q");
  commit("feat: first release");
  git("tag", "-a", "v1.4.2", "-m", "Release v1.4.2");
  const batches = [
    ["docs: explain the retry settings", "fix(api): return 404 for an unknown device id"],
    ["feat(ui): show the camera preview on the settings page", "test: cover the preview toggle"],
    ["refactor(api): split the device router\n\nBREAKING CHANGE: /v1/device is now /v1/devices"],
  ];
  for (const batch of batches) {
    for (const msg of batch) commit(msg);
    const last = git("describe", "--tags", "--abbrev=0");
    const messages = git("log", "--format=%B%x00", `${last}..HEAD`).split("\0").map((m) => m.trim()).filter(Boolean);
    const next = nextVersion(last, messages);
    console.log(`since ${last}: ${messages.map((m) => m.split(/[(:!]/)[0]).join(", ")} -> ${next}`);
    for (const m of messages) console.log(`  - ${m.split("\n")[0]}`);
    git("tag", "-a", next, "-m", `Release ${next}`);
  }
  console.log("\ngit tag -n\n" + git("tag", "-n"));
} finally {
  rmSync(dir, { recursive: true, force: true });
}

since v1.4.2: fix, docs -> v1.4.3
  - fix(api): return 404 for an unknown device id
  - docs: explain the retry settings
since v1.4.3: test, feat -> v1.5.0
  - test: cover the preview toggle
  - feat(ui): show the camera preview on the settings page
since v1.5.0: refactor -> v2.0.0
  - refactor(api): split the device router

git tag -n
v1.4.2          Release v1.4.2
v1.4.3          Release v1.4.3
v1.5.0          Release v1.5.0
v2.0.0          Release v2.0.0

// Review feedback as fixup commits, then folded into the commits they fix before merging:
// git commit --fixup + git rebase --autosquash (non-interactive), Git 2.54, fixed names and dates.
import { execFileSync } from "node:child_process";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const dir = mkdtempSync(join(tmpdir(), "git-demo-"));
let minute = 0;
const git = (...args) => {
  const date = `${1767603600 + 60 * minute++} +0000`;
  return execFileSync("git", args, {
    cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
    env: { ...process.env, LC_ALL: "C", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1",
      GIT_SEQUENCE_EDITOR: "true", // accept the todo list as git wrote it (no editor opens)
      GIT_AUTHOR_NAME: "Asha", GIT_AUTHOR_EMAIL: "asha@example.com", GIT_AUTHOR_DATE: date,
      GIT_COMMITTER_NAME: "Asha", GIT_COMMITTER_EMAIL: "asha@example.com", GIT_COMMITTER_DATE: date },
  }).trimEnd();
};
const write = (file, text) => { writeFileSync(join(dir, file), text); git("add", file); };

try {
  git("-c", "init.defaultBranch=main", "init", "-q");
  write("app.js", "app\n");
  git("commit", "-q", "-m", "chore: initial commit");
  git("switch", "-q", "-c", "feature/reboot");
  write("api.js", "router.post('/reboot', reboot)\n");
  git("commit", "-q", "-m", "feat(api): add device reboot endpoint");
  const apiCommit = git("rev-parse", "--short", "HEAD");
  write("ui.js", "button('Reboot')\n");
  git("commit", "-q", "-m", "feat(ui): add reboot button");

  // Review comments: "the endpoint needs auth", "confirm before rebooting".
  write("api.js", "router.post('/reboot', requireAdmin, reboot)\n");
  git("commit", "-q", "--fixup", apiCommit);
  write("ui.js", "button('Reboot', { confirm: true })\n");
  git("commit", "-q", "--fixup", "HEAD~1");
  console.log("Branch during review:\n" + git("log", "--oneline", "main..HEAD"));

  git("rebase", "-q", "-i", "--autosquash", "main");
  console.log("\nAfter git rebase -i --autosquash main:\n" + git("log", "--oneline", "main..HEAD"));
  console.log("\nThe API commit now contains the fix:\n" + git("show", "--format=%s", "HEAD~1", "--", "api.js").split("\n").filter((l) => /^[+-]r|^feat/.test(l)).join("\n"));
} finally {
  rmSync(dir, { recursive: true, force: true });
}

Branch during review:
14856d8 fixup! feat(ui): add reboot button
512237d fixup! feat(api): add device reboot endpoint
e0aa05d feat(ui): add reboot button
f90ead4 feat(api): add device reboot endpoint

After git rebase -i --autosquash main:
dd04a25 feat(ui): add reboot button
7f40585 feat(api): add device reboot endpoint

The API commit now contains the fix:
feat(api): add device reboot endpoint
+router.post('/reboot', requireAdmin, reboot)

// A bad commit reached main. Undo it two ways and compare: git revert (new commit, history kept)
// vs git reset --hard (history rewritten). Then recover the "lost" commits from the reflog.
// Real git, fixed names and dates, Git 2.54.
import { execFileSync } from "node:child_process";
import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const dir = mkdtempSync(join(tmpdir(), "git-demo-"));
let minute = 0;
const git = (...args) => {
  const date = `${1767603600 + 60 * minute++} +0000`;
  return execFileSync("git", args, {
    cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
    env: { ...process.env, LC_ALL: "C", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1",
      GIT_AUTHOR_NAME: "Asha", GIT_AUTHOR_EMAIL: "asha@example.com", GIT_AUTHOR_DATE: date,
      GIT_COMMITTER_NAME: "Asha", GIT_COMMITTER_EMAIL: "asha@example.com", GIT_COMMITTER_DATE: date },
  }).trimEnd();
};
const commit = (file, text, msg) => { writeFileSync(join(dir, file), text); git("add", file); git("commit", "-q", "-m", msg); };
const read = (file) => readFileSync(join(dir, file), "utf8").trim();

try {
  git("-c", "init.defaultBranch=main", "init", "-q");
  commit("limits.js", "maxUpload = 10", "feat: upload limit");
  commit("limits.js", "maxUpload = 0", "fix: tighten upload limit"); // the bad one: blocks every upload
  commit("README.md", "docs", "docs: document limits");
  git("branch", "before"); // remember this state so both experiments start from it

  git("switch", "-q", "-c", "with-revert", "before");
  git("revert", "--no-edit", "HEAD~1");
  console.log("git revert HEAD~1  (safe on a shared branch)\n" + git("log", "--oneline"));
  console.log(`limits.js: ${read("limits.js")}`);

  git("switch", "-q", "-c", "with-reset", "before");
  git("reset", "-q", "--hard", "HEAD~2");
  console.log("\ngit reset --hard HEAD~2  (rewrites history; also threw away the docs commit)\n" + git("log", "--oneline"));
  console.log(`limits.js: ${read("limits.js")}`);

  console.log("\ngit reflog -4  (where HEAD has been)\n" + git("reflog", "-4"));
  git("reset", "-q", "--hard", "with-reset@{1}"); // the branch's previous position, from its own reflog
  console.log("\nAfter git reset --hard with-reset@{1}\n" + git("log", "--oneline"));
} finally {
  rmSync(dir, { recursive: true, force: true });
}

git revert HEAD~1  (safe on a shared branch)
d3e9fcc Revert "fix: tighten upload limit"
bc22dca docs: document limits
2440ebc fix: tighten upload limit
bbb52f1 feat: upload limit
limits.js: maxUpload = 10

git reset --hard HEAD~2  (rewrites history; also threw away the docs commit)
bbb52f1 feat: upload limit
limits.js: maxUpload = 10

git reflog -4  (where HEAD has been)
bbb52f1 HEAD@{0}: reset: moving to HEAD~2
bc22dca HEAD@{1}: checkout: moving from with-revert to with-reset
d3e9fcc HEAD@{2}: revert: Revert "fix: tighten upload limit"
bc22dca HEAD@{3}: checkout: moving from main to with-revert

After git reset --hard with-reset@{1}
bc22dca docs: document limits
2440ebc fix: tighten upload limit
bbb52f1 feat: upload limit

// What git reset --soft, --mixed and --hard each do to the branch, the index and your files.
// Real git, fixed names and dates, Git 2.54.
import { execFileSync } from "node:child_process";
import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const dir = mkdtempSync(join(tmpdir(), "git-demo-"));
let minute = 0;
const git = (...args) => {
  const date = `${1767603600 + 60 * minute++} +0000`;
  return execFileSync("git", args, {
    cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
    env: { ...process.env, LC_ALL: "C", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1",
      GIT_AUTHOR_NAME: "Asha", GIT_AUTHOR_EMAIL: "asha@example.com", GIT_AUTHOR_DATE: date,
      GIT_COMMITTER_NAME: "Asha", GIT_COMMITTER_EMAIL: "asha@example.com", GIT_COMMITTER_DATE: date },
  }).trimEnd();
};
const commit = (text, msg) => { writeFileSync(join(dir, "notes.txt"), text); git("add", "."); git("commit", "-q", "-m", msg); };

try {
  git("-c", "init.defaultBranch=main", "init", "-q");
  commit("one\n", "first");
  commit("one\ntwo\n", "second");
  git("branch", "start");
  for (const mode of ["--soft", "--mixed", "--hard"]) {
    git("switch", "-q", "-f", "-C", "try", "start");
    git("reset", "-q", mode, "HEAD~1");
    const status = git("status", "--short") || "(clean)";
    const file = readFileSync(join(dir, "notes.txt"), "utf8").trim().replace("\n", " ");
    console.log(`${mode.padEnd(8)} HEAD -> ${git("log", "-1", "--format=%s")}   status: ${status.padEnd(12)} notes.txt: ${file}`);
  }
} finally {
  rmSync(dir, { recursive: true, force: true });
}

--soft   HEAD -> first   status: M  notes.txt notes.txt: one two
--mixed  HEAD -> first   status:  M notes.txt notes.txt: one two
--hard   HEAD -> first   status: (clean)      notes.txt: one

// Reverting a merged pull request, then trying to merge the fixed branch again: the classic trap.
// Real git, fixed names and dates, Git 2.54.
import { execFileSync } from "node:child_process";
import { mkdtempSync, rmSync, writeFileSync, existsSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

const dir = mkdtempSync(join(tmpdir(), "git-demo-"));
let minute = 0;
const git = (...args) => {
  const date = `${1767603600 + 60 * minute++} +0000`;
  return execFileSync("git", args, {
    cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
    env: { ...process.env, LC_ALL: "C", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1",
      GIT_AUTHOR_NAME: "Asha", GIT_AUTHOR_EMAIL: "asha@example.com", GIT_AUTHOR_DATE: date,
      GIT_COMMITTER_NAME: "Asha", GIT_COMMITTER_EMAIL: "asha@example.com", GIT_COMMITTER_DATE: date },
  }).trimEnd();
};
const commit = (file, text, msg) => { writeFileSync(join(dir, file), text); git("add", file); git("commit", "-q", "-m", msg); };
const has = (file) => (existsSync(join(dir, file)) ? "present" : "missing");

try {
  git("-c", "init.defaultBranch=main", "init", "-q");
  commit("app.js", "app\n", "chore: initial commit");
  git("switch", "-q", "-c", "feature/export");
  commit("export.js", "export v1\n", "feat: CSV export");
  git("switch", "-q", "main");
  commit("app.js", "app\nmenu\n", "feat: menu");
  git("merge", "-q", "--no-ff", "feature/export", "-m", "Merge pull request #7 from feature/export");

  // Production breaks. Revert the merge: -m 1 means "keep parent 1 (main), undo what parent 2 brought".
  git("revert", "--no-edit", "-m", "1", "HEAD");
  console.log(`after revert -m 1: export.js ${has("export.js")}, escape.js ${has("escape.js")}`);

  // The author fixes the bug on the same branch and asks for it to be merged again.
  git("switch", "-q", "feature/export");
  commit("escape.js", "escape commas\n", "fix: escape commas in CSV export");
  git("switch", "-q", "main");
  git("merge", "-q", "--no-ff", "feature/export", "-m", "Merge pull request #9 from feature/export");
  console.log(`merge again:       export.js ${has("export.js")}, escape.js ${has("escape.js")}  <- only the new commit came in`);

  // The fix: revert the revert, which brings the original changes back.
  git("revert", "--no-edit", "HEAD^1"); // HEAD^1 = the revert commit on main
  console.log(`revert the revert: export.js ${has("export.js")}, escape.js ${has("escape.js")}`);
  console.log("\n" + git("log", "--graph", "--oneline"));
} finally {
  rmSync(dir, { recursive: true, force: true });
}

after revert -m 1: export.js missing, escape.js missing
merge again:       export.js missing, escape.js present  <- only the new commit came in
revert the revert: export.js present, escape.js present

* f473f33 Reapply "Merge pull request #7 from feature/export"
*   ce6ed05 Merge pull request #9 from feature/export
|\  
| * 64e9c1c fix: escape commas in CSV export
* | 548f798 Revert "Merge pull request #7 from feature/export"
* | ea3438a Merge pull request #7 from feature/export
|\| 
| * 09947bf feat: CSV export
* | 3af1e20 feat: menu
|/  
* 513507a chore: initial commit

// When some commits can't be tested (the build was broken), the test exits 125 and bisect skips them.
// Real git in a throwaway repository, fixed names and dates, Git 2.54.
import { execFileSync } from "node:child_process";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, dirname } from "node:path";

const dir = mkdtempSync(join(tmpdir(), "git-demo-"));
let minute = 0;
const git = (...args) => {
  const date = `${1767603600 + 60 * minute++} +0000`;
  return execFileSync("git", args, {
    cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
    env: { ...process.env, LC_ALL: "C", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1",
      PATH: `${dirname(process.execPath)}:${process.env.PATH}`,
      GIT_AUTHOR_NAME: "Asha", GIT_AUTHOR_EMAIL: "asha@example.com", GIT_AUTHOR_DATE: date,
      GIT_COMMITTER_NAME: "Asha", GIT_COMMITTER_EMAIL: "asha@example.com", GIT_COMMITTER_DATE: date },
  }).trimEnd();
};
const write = (file, text) => writeFileSync(join(dir, file), text);

// exit 125 = "can't test this one" (here: the module doesn't even load); 0 = good; 1 = bad.
const test = `let clamp;
try { ({ clamp } = await import("./volume.mjs")); } catch { process.exit(125); }
process.exit(clamp(-5) === 0 ? 0 : 1);
`;

try {
  git("-c", "init.defaultBranch=main", "init", "-q");
  write("volume.mjs", "export const clamp = (v) => Math.min(100, Math.max(0, v));\n");
  write("test-volume.mjs", test);
  git("add", ".");
  git("commit", "-q", "-m", "feat: volume control");
  for (let i = 1; i <= 8; i++) {
    if (i === 3) write("volume.mjs", "export const clamp = (v) => Math.min(100, Math.max(0, v)) +;\n"); // syntax error
    if (i === 4) write("volume.mjs", "export const clamp = (v) => Math.min(100, v) +;\n"); // bug, still broken
    if (i === 5) write("volume.mjs", "export const clamp = (v) => Math.min(100, v);\n"); // builds again, bug remains
    write("n.txt", `${i}\n`);
    git("add", ".");
    git("commit", "-q", "-m", `change ${i}`);
  }
  console.log(git("bisect", "start", "HEAD", "HEAD~8"));
  try {
    git("bisect", "run", "node", "test-volume.mjs");
  } catch (err) { // bisect run exits non-zero when it can't name a single commit
    const name = (hash) => git("log", "-1", "--format=%h %s", hash);
    const lines = err.stdout.trim().split("\n").filter((l) => !l.startsWith("running "));
    console.log(lines.map((l) => (/^[0-9a-f]{40}$/.test(l) ? `  ${name(l)}` : l)).join("\n"));
    console.log(`exit status ${err.status}: ${err.stderr.trim()}`);
  }
  git("bisect", "reset");
} finally {
  rmSync(dir, { recursive: true, force: true });
}

Bisecting: 3 revisions left to test after this (roughly 2 steps)
[dd8b2d1e17ba43574027989de5d8ff04835f7137] change 4
Bisecting: 3 revisions left to test after this (roughly 2 steps)
[d09267ff79e6f51896301845774c0ea0e1fe041b] change 2
Bisecting: 2 revisions left to test after this (roughly 2 steps)
[c3954479db8818d61255f7236d1412c147abe4bd] change 5
Bisecting: 0 revisions left to test after this (roughly 1 step)
[ddea829ddc89364c221b414f9486b73a3cec725a] change 3
There are only 'skip'ped commits left to test.
The first bad commit could be any of:
  dd8b2d1 change 4
  ddea829 change 3
  c395447 change 5
We cannot bisect more!
exit status 2: error: bisect run cannot continue any more