@tertium/gith 0.2.0 → 0.3.1

package/README.md

@@ -11,7 +11,7 @@
        d b
 ```
 
-Git helper: the branch flow from [git-convention](https://github.com/Tertiumnon/git-convention) (goal-named work branches, `release/*` and `hotfix/*` containers, merges that sync both sides with origin), plus everyday git commands: status, switch, update, undo, save, squash, stash, remove, list, tree, sync, clean, reset, open, doctor and stat. Any command takes `--dry-run` to show the git commands it would run. No dependencies beyond git and [Bun](https://bun.com).
+Git helper: the branch flow from [git-convention](https://github.com/Tertiumnon/git-convention) (work branches named develop--<goal>, `release/*` and `hotfix/*` containers, merges that sync both sides with origin), plus everyday git commands: status, switch, update, undo, save, squash, stash, remove, list, tree, sync, clean, reset, open, doctor and stat. Any command takes `--dry-run` to show the git commands it would run. No dependencies beyond git and [Bun](https://bun.com).
 
 > **Very early state (0.1.0).** Commands and flags may change without notice, and the tool has only been run against throwaway test repositories. Check the result with `git log` and `git status` before you push.
 
@@ -26,20 +26,29 @@ gith --version
 
 From a clone of this repository, build the CLI and link it: `bun install`, `bun run build`, `npm link`.
 
+`bun install` also points git at `.githooks/`, so each commit runs `bun run typecheck`, `bun run format:check` and `bun run lint` first, and a failing check stops it. `bun run format` rewrites files to the formatter's style.
+
 ## Usage
 
 ```bash
 # Start and finish work
-gith create -b login-redirect       # work branch from develop, named by its goal; stays on the current branch
+gith create -b login-redirect       # work branch develop--login-redirect from develop; stays on the current branch
 gith create -r 1.2.0                # release/1.2.0 from develop
 gith create -h 1.2.1                # hotfix/1.2.1 from main
 gith create --release               # release, version = minor after the latest tag
 gith create --hotfix                # hotfix, version = patch after the latest tag
-gith switch -b login-redirect       # switch to the branch, creating it from develop if it is missing
+gith switch                         # list local and origin branches, and switch to the one you pick
+gith switch -b login-redirect       # switch to develop--login-redirect, creating it from develop if it is missing
 gith switch -commit 3f2a1b9         # detach HEAD at that commit, to look at old code
+gith switch --release               # switch to the newest release/* (local or origin); -r 1.9.0 for one version
+gith switch --hotfix                # switch to the newest hotfix/* (local or origin); -h 1.2.1 for one version
 gith update                         # merge origin/develop into this work branch
 gith merge                          # this branch into develop
-gith merge -r 1.2.0                 # this branch into release/1.2.0
+gith finish --current-release    # release the newest release/*: version, changelog, merge to main, tag, merge main to develop, then ask before deleting the branch
+gith finish --current-hotfix      # the same for the newest hotfix/*
+gith merge                          # pick the branch to merge, then the target from the list
+gith merge --main                   # this branch into main
+gith merge -r 1.2.0                 # this branch into release/1.2.0 (-r alone: the only release, or pick from the list)
 gith merge -h 1.2.1                 # this branch into hotfix/1.2.1
 gith merge --current-release        # this branch into the newest release/* (local or origin)
 gith merge --current-hotfix         # this branch into the newest hotfix/* (local or origin)
@@ -49,7 +58,7 @@ gith release --major                # npm version major, from develop into main
 
 # Fix history
 gith undo                           # undo the last commit, keep its changes staged (not if pushed)
-gith save [-m "msg"]                # fold staged changes into the last commit, or make a new commit with them if the branch has none yet (asks for a message); pushes if origin differs
+gith save [-m "msg"] [--all]         # --all stages every change first; fold staged changes into the last commit, or make a new commit with them if the branch has none yet (asks for a message); pushes if origin differs
 gith squash -limit 3 [-m "msg"]     # combine the last 3 commits into one (keeps the oldest message)
 
 # Save and reset work
@@ -59,6 +68,7 @@ gith reset                          # discard uncommitted changes, then clean
 gith clean                          # remove untracked files and directories
 
 # Clean up branches (every removal shows what it will remove first)
+gith remove                         # pick branches to delete from the list (here and on origin)
 gith remove -b login-redirect       # delete the branch here and on origin (rm is an alias)
 gith remove -b login-redirect --local    # delete only the local branch
 gith remove -b login-redirect --remote   # delete only the origin branch
@@ -113,9 +123,12 @@ One rule applies to every command: **a single dash always takes a value, and a d
 | `-b <name>`, `-branch <name>` | value | `create`, `switch`, `remove` |
 | `--branch` | alone: open the picker | `remove` |
 | `-r <version>`, `-release <version>` | value | `create`, `merge` |
+| `-r` alone | the only release, or a pick from the list | `merge` |
 | `--release` | alone: version from the latest tag | `create` |
+| `--main` | alone: merge into main | `merge` |
 | `--current-release`, `--current-hotfix` | switch: merge into the newest release or hotfix | `merge` |
 | `-h <version>`, `-hotfix <version>` | value | `create`, `merge` |
+| `-h` alone | the only hotfix, or a pick from the list | `merge` |
 | `--hotfix` | alone: version from the latest tag | `create` |
 | `-limit <n>` | value | `squash`: how many commits to combine |
 | `-m <msg>`, `-message <msg>` | value | `squash` |
@@ -138,10 +151,10 @@ Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `
 
 ## Git commands
 
-- **`switch -b`** switches to a branch. If the branch exists neither locally nor on origin, it is created first, the same way as `create -b`, and then checked out.
+- **`switch -b`** switches to a branch. If a branch with that name exists (locally or on origin), it is checked out. Otherwise, if `develop--<name>` exists, that one is checked out. If neither exists, `develop--<name>` is created from `origin/develop`, the same way as `create -b`, and checked out.
 - **`switch -commit <sha>`** detaches HEAD at that commit so you can look at old code. It refuses a commit that does not exist, and it refuses while tracked files have changes (untracked files do not block it). It lists the files that block it, and points to `gith stash`. On a detached HEAD, `gith switch -b <name>` creates the branch at the current commit, so commits made there stay on it. It does not create or switch branches for other commits, so commits made on a detached HEAD are easy to lose: name a branch before you leave.
 - **`remove -b <branch>`** removes the branch on both sides: the local branch first (with `git branch -d`, so git refuses to delete an unmerged branch), then the origin branch. A side that does not exist is skipped, so a branch that lives only here is still removed. A name that exists in neither place is an error. `--local` touches only this clone; `--remote` touches only origin. Containers (`develop`, `main`, `release/*`, `hotfix/*`) are refused.
-- **`remove --branch`** with no name lists the branches and asks which to remove. By default it lists branch pairs, meaning branches that exist both here and on origin. `--local` lists local branches and `--remote` lists origin branches. Each choice is removed on the same sides as above. `-limit <n>` shows only the first `n` (all by default), and the picker numbers only those. Answer with numbers or ranges, such as `1,3-4`; an empty answer cancels. The list needs a terminal, and that is checked before anything is listed. The checked-out branch and containers are never listed. Choosing items is the confirmation, so nothing else is asked. If a delete fails (for example, an unmerged branch), the removal stops there and earlier picks stay deleted.
+- **`remove`** with no name opens the list of branches and asks which to remove, the same as `remove --branch`. By default it lists branch pairs, meaning branches that exist both here and on origin. `--local` lists local branches and `--remote` lists origin branches. Each choice is removed on the same sides as above. `-limit <n>` shows only the first `n` (all by default), and the picker numbers only those. Pick with the arrow keys: up and down move, space checks an item, enter confirms the checked items, and esc cancels. `switch` takes one item with enter. The list needs a terminal, and that is checked before anything is listed. The checked-out branch and containers are never listed. Choosing items is the confirmation, so nothing else is asked. If a delete fails (for example, an unmerged branch), the removal stops there and earlier picks stay deleted.
 - **`status`** prints the branch and how far it is ahead of or behind its origin branch, then counts staged, unstaged, untracked and conflicting files. It changes nothing.
 - **`update`** fetches `origin/develop` and merges it into the current work branch. It needs a clean working tree and refuses containers. If the merge conflicts, it aborts the merge and says so. It does not push.
 - **`undo`** runs `git reset --soft HEAD~1`: the last commit is removed and its changes stay staged. It refuses when HEAD is already on origin, because undoing a pushed commit needs a force-push.
@@ -172,10 +185,12 @@ Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `
 
 ## What it does
 
-- **`create -b`** creates the branch from `origin/develop`, pushes it with upstream tracking, and leaves the current branch checked out. It does not touch the working tree, so it works with uncommitted changes.
+- **`create -b`** creates `develop--<name>` from `origin/develop`, pushes it with upstream tracking, and leaves the current branch checked out. The prefix shows the source branch; `create -b develop` and `create -b main` are refused. It does not touch the working tree, so it works with uncommitted changes.
 - **`create -r` / `create -h`** creates a container from its base (`develop` for release, `main` for hotfix), refusing names that already exist on origin. Like `create -b`, it does not switch.
 - **With `--release` or `--hotfix` (no value)**, the version is worked out from the highest `vX.Y.Z` tag across local tags and origin: `-r` takes the next minor (`1.2.1` → `1.3.0`), `-h` takes the next patch (`1.2.1` → `1.2.2`). With no tags yet, the first release is `0.1.0` and the first hotfix `0.0.1`. The version is printed before the branch is created.
 - **`merge --current-release`** and **`--current-hotfix`** pick the newest `release/*` or `hotfix/*` branch by version (numbers compare as numbers, so `1.10.0` beats `1.9.0`), checking both local branches and origin, and merge into it. The target must exist on origin, because the merge pushes it; a newest branch that only exists here stops the command with a message.
+- **`finish --current-release`** (and `--current-hotfix`) releases the newest `release/*` (or `hotfix/*`), named by its version X.Y.Z. It makes `package.json`'s version match the name (committed as `X.Y.Z`, only when they differ), adds the changelog entry as its own commit (when it is missing), merges the branch into `main` with `--no-ff`, tags `vX.Y.Z` and pushes, merges `main` into `develop` when `develop` exists on origin, and then asks before deleting the branch. A conflict aborts the merge and stops. Projects without a `package.json` keep their version by hand.
+- **`merge`** with no flags asks which branch to merge and which target to merge it into (develop, release/*, hotfix/*), with the arrow keys. After a merge into a target, the work branch is deleted here and on origin, after a Y/n question. Without a terminal, or on a no, it is kept. Release and hotfix branches are never deleted this way.
 - **`merge`** pushes the work branch, merges the target into it first (so conflicts happen on the work branch and are aborted cleanly), then merges it into the target with `--no-ff`, pushes, and checks that both branches match origin.
 
 Containers (`develop`, `main`, `release/*`, `hotfix/*`) can't be merged from, and only `develop`, `release/*` and `hotfix/*` can be merged into.

package/bin/gith.js

@@ -6,8 +6,8 @@ import { exit } from "node:process";
 // src/components/args/args.constants.ts
 var SPECS = new Map([
   ["branch", "auto"],
-  ["release", "auto"],
-  ["hotfix", "auto"],
+  ["release", "optional"],
+  ["hotfix", "optional"],
   ["limit", "value"],
   ["message", "value"],
   ["name", "value"],
@@ -28,6 +28,8 @@ var SPECS = new Map([
   ["stashes", "switch"],
   ["current-release", "switch"],
   ["current-hotfix", "switch"],
+  ["develop", "switch"],
+  ["main", "switch"],
   ["pockets", "switch"],
   ["detached", "switch"],
   ["all", "switch"],
@@ -88,10 +90,14 @@ function parseFlags(argv) {
     if (style === "single") {
       if (kind === "switch")
         throw new Error(`${token} is a switch; write --${name}.`);
-      if (!hasNext)
+      if (hasNext) {
+        flags.set(name, next);
+        i++;
+      } else if (kind === "optional") {
+        flags.set(name, "");
+      } else {
         throw new Error(`${token} needs a value.`);
-      flags.set(name, next);
-      i++;
+      }
     } else if (kind === "switch") {
       flags.set(name, "true");
     } else if (kind === "value") {
@@ -427,9 +433,127 @@ function find(flags) {
 `));
 }
 
+// src/components/flow/flow.ts
+import { execSync } from "node:child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+
+// src/components/prompt/prompt.ts
+import { emitKeypressEvents } from "node:readline";
+import { createInterface } from "node:readline/promises";
+
+// src/components/prompt/prompt.utils.ts
+function moveIndex(index, delta, length) {
+  if (length <= 0)
+    return 0;
+  return ((index + delta) % length + length) % length;
+}
+function toggled(checked, index) {
+  const next = new Set(checked);
+  if (next.has(index))
+    next.delete(index);
+  else
+    next.add(index);
+  return next;
+}
+
+// src/components/prompt/prompt.ts
+var assumeYes = false;
+function setAssumeYes(on) {
+  assumeYes = on;
+}
+async function confirm(question) {
+  if (isDryRun()) {
+    console.log(`dry run: would ask: ${question}`);
+    return true;
+  }
+  if (assumeYes)
+    return true;
+  if (!process.stdin.isTTY)
+    throw new Error("this needs a terminal to confirm; pass --yes to skip the question.");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(question)).trim().toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+async function ask(question) {
+  if (isDryRun()) {
+    console.log(`dry run: would ask: ${question}`);
+    return "<message>";
+  }
+  if (!process.stdin.isTTY)
+    throw new Error("needs a terminal to ask; pass -m <message>.");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+async function select(question, options, multi) {
+  if (!process.stdin.isTTY)
+    throw new Error("this needs a terminal to pick.");
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    let index = 0;
+    let checked = new Set;
+    let drawnLines = 0;
+    const draw = () => {
+      if (drawnLines > 0)
+        process.stdout.write(`\x1B[${drawnLines}A\x1B[0J`);
+      const hint = multi ? "space checks, enter confirms, esc cancels" : "enter selects, esc cancels";
+      const lines = [`${question} (${hint})`];
+      options.forEach((option, i) => {
+        const cursor = i === index ? ">" : " ";
+        const mark = multi ? checked.has(i) ? "[x]" : "[ ]" : "";
+        lines.push(`${cursor} ${mark} ${option.label}`.replace(/ +$/, ""));
+      });
+      process.stdout.write(`${lines.join(`
+`)}
+`);
+      drawnLines = lines.length;
+    };
+    const finish = (picked) => {
+      stdin.off("keypress", onKey);
+      stdin.setRawMode(false);
+      stdin.pause();
+      process.stdout.write(`
+`);
+      resolve(picked);
+    };
+    const onKey = (_text, key) => {
+      if (!key)
+        return;
+      if (key.ctrl && key.name === "c" || key.name === "escape") {
+        finish([]);
+        return;
+      }
+      if (key.name === "return") {
+        const picked = multi ? [...checked].sort((a, b) => a - b).map((i) => options[i]?.name ?? "") : [options[index]?.name ?? ""];
+        finish(picked.filter(Boolean));
+        return;
+      }
+      if (key.name === "up")
+        index = moveIndex(index, -1, options.length);
+      else if (key.name === "down")
+        index = moveIndex(index, 1, options.length);
+      else if (key.name === "space" && multi)
+        checked = toggled(checked, index);
+      draw();
+    };
+    emitKeypressEvents(stdin);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("keypress", onKey);
+    draw();
+  });
+}
+
 // src/components/rules/rules.constants.ts
 var CONTAINER = /^(develop|main|release\/.+|hotfix\/.+)$/;
-var TARGET = /^(develop|release\/.+|hotfix\/.+)$/;
+var TARGET = /^(main|develop|release\/.+|hotfix\/.+)$/;
 
 // src/components/rules/rules.ts
 function isContainer(name) {
@@ -478,7 +602,7 @@ function nextVersion(tags, bump) {
 }
 
 // src/components/flow/flow.utils.ts
-function newestContainer(kind) {
+function containers(kind) {
   const prefix = `${kind}/`;
   const local = captureArgs([
     "for-each-ref",
@@ -489,15 +613,19 @@ function newestContainer(kind) {
   const origin = captureArgs(["ls-remote", "--heads", "origin"]).split(`
 `).map((line) => (line.split("\t")[1] ?? "").replace(/^refs\/heads\//, ""));
   const candidates = new Set([...local, ...origin].filter((name) => name.startsWith(prefix)));
-  let newest;
+  const versioned = [];
   for (const name of candidates) {
     const version = parseSemver(name.slice(prefix.length));
-    if (version && (!newest || compare(version, newest.version) > 0))
-      newest = { name, version };
+    if (version)
+      versioned.push({ name, version });
   }
+  return versioned.sort((a, b) => compare(b.version, a.version)).map((item) => item.name);
+}
+function newestContainer(kind) {
+  const [newest] = containers(kind);
   if (!newest)
     throw new Error(`no ${kind} branch exists, locally or on origin.`);
-  return newest.name;
+  return newest;
 }
 function nextContainerVersion(kind) {
   const bump = kind === "release" ? "minor" : "patch";
@@ -534,44 +662,70 @@ function create(flags) {
   }
   open(kind, value || nextContainerVersion(kind));
 }
-function merge(flags) {
+async function merge(flags) {
+  if (flags.size === 0)
+    return mergePick();
   const kind = onlyOne(flags, [
+    "develop",
+    "main",
     "release",
     "hotfix",
     "current-release",
     "current-hotfix"
   ]);
   let target = "develop";
-  if (kind === "current-release")
+  if (kind === "develop")
+    target = "develop";
+  else if (kind === "main")
+    target = "main";
+  else if (kind === "current-release")
     target = newestContainer("release");
   else if (kind === "current-hotfix")
     target = newestContainer("hotfix");
   else if (kind) {
     const version = flags.get(kind) ?? "";
-    if (!version) {
-      throw new Error(`usage: gith merge -${kind === "release" ? "r" : "h"} <version>`);
-    }
-    target = containerName(kind, version);
+    const picked = version === "" ? await pickContainer(kind) : containerName(kind, version);
+    if (picked === undefined)
+      return;
+    target = picked;
   }
-  mergeInto(target);
+  await mergeInto(target);
+}
+async function pickContainer(kind) {
+  const names = containers(kind);
+  if (names.length === 0)
+    throw new Error(`no ${kind} branch exists, locally or on origin.`);
+  if (names.length === 1)
+    return names[0];
+  if (!process.stdin.isTTY) {
+    throw new Error(`several ${kind} branches exist; pass -${kind === "release" ? "r" : "h"} <version> instead; the list needs a terminal`);
+  }
+  const [picked] = await select(`Merge into which ${kind}?`, names.map((name) => ({ name, label: name })), false);
+  return picked;
+}
+function workBranchName(goal, from) {
+  return from === undefined ? `develop--${goal}` : goal;
 }
 function createBranch(goal, from) {
   if (isContainer(goal))
     throw new Error(`'${goal}' is a container name; pick a goal.`);
-  if (hasOnOrigin(goal))
-    throw new Error(`'${goal}' already exists on origin.`);
+  const name = workBranchName(goal, from);
+  if (hasOnOrigin(name))
+    throw new Error(`'${name}' already exists on origin.`);
   if (from === undefined) {
     gitArgs(["fetch", "origin", "develop"]);
-    gitArgs(["branch", goal, "origin/develop"]);
+    gitArgs(["branch", name, "origin/develop"]);
   } else {
-    gitArgs(["branch", goal, from]);
+    gitArgs(["branch", name, from]);
   }
-  gitArgs(["push", "-u", "origin", goal]);
+  gitArgs(["push", "-u", "origin", name]);
+  return name;
 }
-function mergeInto(target) {
+async function mergeInto(target, from) {
   if (!isTarget(target))
     throw new Error(`'${target}' is not a valid target.`);
-  const source = capture("rev-parse --abbrev-ref HEAD");
+  const current = capture("rev-parse --abbrev-ref HEAD");
+  const source = from ?? current;
   if (isContainer(source))
     throw new Error(`'${source}' is a container and cannot be merged from.`);
   if (source === target)
@@ -579,6 +733,8 @@ function mergeInto(target) {
   if (!hasOnOrigin(target))
     throw new Error(`'${target}' does not exist on origin.`);
   assertCleanTree();
+  if (source !== current)
+    gitArgs(["switch", "--", source]);
   if (hasOnOrigin(source))
     git(`pull origin ${source}`);
   git(`push -u origin ${source}`);
@@ -598,44 +754,116 @@ function mergeInto(target) {
   assertSynced([target, source]);
   console.log(`
 ✅ '${source}' merged into '${target}', both in sync with origin.`);
+  await deleteMergedBranch(source);
 }
-
-// src/components/prompt/prompt.ts
-import { createInterface } from "node:readline/promises";
-var assumeYes = false;
-function setAssumeYes(on) {
-  assumeYes = on;
-}
-async function confirm(question) {
-  if (isDryRun()) {
-    console.log(`dry run: would ask: ${question}`);
-    return true;
-  }
-  if (assumeYes)
-    return true;
-  if (!process.stdin.isTTY)
-    throw new Error("this needs a terminal to confirm; pass --yes to skip the question.");
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
+async function deleteMergedBranch(source) {
+  const local = hasLocal(source);
+  const origin = hasOnOrigin(source);
+  let yes;
   try {
-    const answer = (await rl.question(question)).trim().toLowerCase();
-    return answer === "" || answer === "y" || answer === "yes";
-  } finally {
-    rl.close();
+    yes = await confirm(`Delete '${source}' here and on origin, it is merged? [Y/n] `);
+  } catch {
+    yes = false;
+  }
+  if (!yes) {
+    console.log(`'${source}' kept.`);
+    return;
   }
+  if (local)
+    gitArgs(["branch", "-d", "--", source]);
+  if (origin)
+    gitArgs(["push", "origin", "--delete", source]);
 }
-async function ask(question) {
+async function mergePick() {
+  if (!process.stdin.isTTY) {
+    throw new Error("pass -r <version> or -h <version> instead; the pickers need a terminal");
+  }
+  const current = capture("rev-parse --abbrev-ref HEAD");
+  const local = captureArgs([
+    "for-each-ref",
+    "--format=%(refname:short)",
+    "refs/heads"
+  ]).split(`
+`).filter(Boolean);
+  const sources = local.filter((name) => !isContainer(name)).sort((a, b) => a.localeCompare(b)).map((name) => ({
+    name,
+    label: name === current ? `${name}  (current)` : name
+  }));
+  if (sources.length === 0)
+    throw new Error("no work branch to merge.");
+  const [source] = await select("Which branch to merge?", sources, false);
+  if (source === undefined)
+    return;
+  const origin = captureArgs(["ls-remote", "--heads", "origin"]).split(`
+`).map((line) => (line.split("\t")[1] ?? "").replace(/^refs\/heads\//, "")).filter(Boolean);
+  const targets = [...new Set([...local, ...origin])].filter((name) => isTarget(name) && name !== source).sort((a, b) => a.localeCompare(b)).map((name) => ({
+    name,
+    label: local.includes(name) ? name : `${name}  (origin)`
+  }));
+  if (targets.length === 0)
+    throw new Error("no develop, release or hotfix branch to merge into.");
+  const [target] = await select(`Merge '${source}' into which?`, targets, false);
+  if (target === undefined)
+    return;
+  await mergeInto(target, source);
+}
+function alignVersion(version) {
+  if (!existsSync2("package.json"))
+    return;
+  const current = parsePackageVersion(readFileSync2("package.json", "utf8"));
+  if (current === version)
+    return;
   if (isDryRun()) {
-    console.log(`dry run: would ask: ${question}`);
-    return "<message>";
+    console.log(`> npm version ${version} --no-git-tag-version --ignore-scripts`);
+  } else {
+    execSync(`npm version ${version} --no-git-tag-version --ignore-scripts`, {
+      stdio: "inherit"
+    });
   }
-  if (!process.stdin.isTTY)
-    throw new Error("needs a terminal to ask; pass -m <message>.");
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  gitArgs(["add", "--", "package.json"]);
+  gitArgs(["commit", "-m", version, "--", "package.json"]);
+}
+function addChangelogEntry(version) {
+  if (!existsSync2("package.json"))
+    return;
+  const file = "CHANGELOG.md";
+  if (existsSync2(file) && readFileSync2(file, "utf8").includes(`## ${version} - `))
+    return;
+  changelog(new Map);
+}
+async function finish(flags) {
+  const kind = onlyOne(flags, ["current-release", "current-hotfix"]);
+  if (!kind || flags.size > 1)
+    throw new Error("usage: gith finish --current-release | --current-hotfix");
+  const containerKind = kind === "current-release" ? "release" : "hotfix";
+  const branch = newestContainer(containerKind);
+  const version = branch.slice(containerKind.length + 1);
+  if (parseSemver(version) === undefined)
+    throw new Error(`'${branch}' is not named with a version (X.Y.Z).`);
+  assertCleanTree();
+  gitArgs(["switch", "--", branch]);
+  gitArgs(["pull", "--ff-only", "origin", branch]);
+  alignVersion(version);
+  addChangelogEntry(version);
+  gitArgs(["switch", "--", "main"]);
+  gitArgs(["pull", "--ff-only", "origin", "main"]);
   try {
-    return (await rl.question(question)).trim();
-  } finally {
-    rl.close();
+    gitArgs(["merge", "--no-ff", branch, "-m", `Merge '${branch}' into main`]);
+  } catch {
+    gitArgs(["merge", "--abort"]);
+    throw new Error(`merging '${branch}' into main conflicts; resolve it by hand, then retry.`);
+  }
+  gitArgs(["tag", "-a", `v${version}`, "-m", `v${version}`]);
+  gitArgs(["push", "origin", "main"]);
+  gitArgs(["push", "origin", `v${version}`]);
+  if (hasOnOrigin("develop")) {
+    gitArgs(["switch", "--", "develop"]);
+    gitArgs(["pull", "--ff-only", "origin", "develop"]);
+    gitArgs(["merge", "--no-edit", "main"]);
+    gitArgs(["push", "origin", "develop"]);
   }
+  gitArgs(["switch", "--", "main"]);
+  await deleteMergedBranch(branch);
 }
 
 // src/components/history/history.utils.ts
@@ -690,10 +918,12 @@ function undo(flags) {
 }
 async function save(flags) {
   const message = flags.get("message");
-  const extra = [...flags.keys()].filter((key) => key !== "message");
+  const extra = [...flags.keys()].filter((key) => key !== "message" && key !== "all");
   if (extra.length > 0)
-    throw new Error("usage: gith save [-m <message>]");
+    throw new Error("usage: gith save [-m <message>] [--all]");
   const branch = currentBranch();
+  if (flags.has("all"))
+    gitArgs(["add", "-A"]);
   if (captureArgs(["diff", "--cached", "--name-only"]) === "") {
     throw new Error("nothing staged; stage the changes to add to the last commit.");
   }
@@ -862,7 +1092,7 @@ function stashes(limit, withGorlum) {
   ]).split(`
 `).filter(Boolean);
   if (rows.length === 0) {
-    console.log("No stashes.");
+    console.log(withGorlum ? "There is nothing in my pockets!" : "No stashes.");
     return;
   }
   const shown = rows.slice(0, limit);
@@ -893,9 +1123,6 @@ function originTags() {
 `).filter(Boolean).map((line) => (line.split("\t")[1] ?? "").replace(/^refs\/tags\//, "")).filter((ref) => ref && !ref.endsWith("^{}"));
 }
 
-// src/components/maintenance/maintenance.ts
-import { createInterface as createInterface2 } from "node:readline/promises";
-
 // src/components/maintenance/maintenance.constants.ts
 var DEFAULT_DAYS = 90;
 
@@ -944,7 +1171,21 @@ function parsePositive(flags, name) {
 }
 
 // src/components/maintenance/maintenance.ts
-function switchBranch(flags) {
+async function switchBranch(flags) {
+  if (flags.size === 0)
+    return switchPick();
+  const kind = onlyOne(flags, ["release", "hotfix"]);
+  if (kind !== undefined) {
+    if (flags.size > 1)
+      throw new Error(`usage: gith switch --${kind} | -${kind === "release" ? "r" : "h"} <version>`);
+    const version = flags.get(kind) ?? "";
+    const name = version === "" ? newestContainer(kind) : containerName(kind, version);
+    if (!hasLocal(name) && !hasOnOrigin(name)) {
+      throw new Error(`'${name}' does not exist, locally or on origin.`);
+    }
+    gitArgs(["switch", "--", name]);
+    return;
+  }
   const commit = flags.get("commit");
   if (commit !== undefined) {
     if (flags.has("branch") || flags.size > 1)
@@ -953,10 +1194,14 @@ function switchBranch(flags) {
     return;
   }
   const branch = requireBranch(flags, "switch");
-  if (!hasLocal(branch) && !hasOnOrigin(branch)) {
-    createBranch(branch, isDetached() ? "HEAD" : undefined);
+  const from = isDetached() ? "HEAD" : undefined;
+  const exists = (name) => hasLocal(name) || hasOnOrigin(name);
+  let name = branch;
+  if (!exists(branch)) {
+    const made = workBranchName(branch, from);
+    name = exists(made) ? made : createBranch(branch, from);
   }
-  gitArgs(["switch", "--", branch]);
+  gitArgs(["switch", "--", name]);
 }
 function candidates(scope, local, remote, current) {
   const notContainer = (name) => !isContainer(name);
@@ -969,20 +1214,6 @@ function candidates(scope, local, remote, current) {
   }
   return local.filter((name) => notContainer(name) && notCurrent(name) && remote.includes(name)).map((name) => ({ name, label: `${name}  (local + origin)` }));
 }
-function parseSelection(answer, count) {
-  const indexes = new Set;
-  for (const part of answer.split(",").map((s) => s.trim()).filter(Boolean)) {
-    const range = /^(\d+)-(\d+)$/.exec(part);
-    const from = Number(range ? range[1] : part);
-    const to = Number(range ? range[2] : part);
-    if (!Number.isInteger(from) || !Number.isInteger(to) || from < 1 || to > count || from > to) {
-      throw new Error(`'${part}' is not a choice from 1 to ${count}.`);
-    }
-    for (let n = from;n <= to; n++)
-      indexes.add(n - 1);
-  }
-  return [...indexes];
-}
 function branchTimes(output) {
   const times = new Map;
   for (const line of output.split(`
@@ -1028,7 +1259,7 @@ function detachedOptions(times, current) {
   return options.sort((x, y) => x.name.localeCompare(y.name));
 }
 async function remove(flags) {
-  const name = flags.get("branch");
+  const name = flags.get("branch") ?? "";
   const side = onlyOne(flags, ["local", "remote"]);
   const scope = side ?? "pair";
   const obsoleteOn = flags.has("obsolete");
@@ -1041,14 +1272,12 @@ async function remove(flags) {
     throw new Error("--all only applies to --detached.");
   if (obsoleteOn || detachedOn) {
     const usage = detachedOn ? "usage: gith remove --detached [--all | -l <n>]" : "usage: gith remove --obsolete [--local] [-days <n>] [-l <n>]";
-    if (name !== undefined || obsoleteOn && side === "remote" || detachedOn && side)
+    if (flags.has("branch") || obsoleteOn && side === "remote" || detachedOn && side)
       throw new Error(usage);
     if (detachedOn)
       return detached(flags);
     return obsolete(flags, side === "local" ? "local" : "pair");
   }
-  if (name === undefined)
-    throw new Error("usage: gith remove -b <branch> [--local | --remote], or gith remove --branch to pick");
   if (name) {
     if (flags.has("limit"))
       throw new Error("-limit only applies to listings: gith remove --branch.");
@@ -1103,25 +1332,49 @@ async function clean(flags) {
   }
   gitArgs(["clean", "-fd"]);
 }
-async function choose(options, limit) {
+var REMOVE_ACTION = {
+  empty: "No branches to remove.",
+  prompt: "Remove which?",
+  multi: true
+};
+async function choose(options, limit, action = REMOVE_ACTION) {
   if (options.length === 0) {
-    console.log("No branches to remove.");
+    console.log(action.empty);
     return [];
   }
   const shown = limit === undefined ? options : options.slice(0, limit);
-  for (const [i, option] of shown.entries()) {
-    console.log(`  ${i + 1}. ${option.label}`);
-  }
   if (shown.length < options.length) {
     console.log(`showing ${shown.length} of ${options.length}; -limit <n> shows more`);
   }
-  const rl = createInterface2({ input: process.stdin, output: process.stdout });
-  try {
-    const answer = await rl.question("Remove which? Numbers or ranges, e.g. 1,3-4 (empty cancels): ");
-    return parseSelection(answer, shown.length).map((i) => shown[i]?.name ?? "");
-  } finally {
-    rl.close();
+  return select(action.prompt, shown, action.multi);
+}
+function switchOptions() {
+  const local = localBranches();
+  const origin = remoteBranches();
+  const current = currentBranch2();
+  const names = [...new Set([...local, ...origin])].sort((a, b) => a.localeCompare(b));
+  return names.map((name) => {
+    const where = local.includes(name) && origin.includes(name) ? "local + origin" : local.includes(name) ? "local" : "origin";
+    return {
+      name,
+      label: `${name}  (${where}${name === current ? ", current" : ""})`
+    };
+  });
+}
+async function switchPick() {
+  if (!process.stdin.isTTY) {
+    throw new Error("pass a branch name with -b, e.g. gith switch -b <branch>; the list needs a terminal");
   }
+  const picked = await choose(switchOptions(), undefined, {
+    empty: "No branches.",
+    prompt: "Switch to which?",
+    multi: false
+  });
+  if (picked.length === 0)
+    return;
+  if (picked.length > 1)
+    throw new Error("pick exactly one branch to switch to.");
+  gitArgs(["switch", "--", picked[0] ?? ""]);
 }
 function requireTerminal() {
   if (!process.stdin.isTTY) {
@@ -1147,14 +1400,14 @@ async function removeBranches(scope, names, ask = true) {
   });
   if (plan.length > 0)
     console.log("Will remove:");
-  if (ask && plan.length > 0 && !await confirm(plan.length === 1 ? "Remove this branch? [Y/n] " : `Remove these ${plan.length} branches? [Y/n] `)) {
-    console.log("Nothing removed.");
-    return;
-  }
   for (const { name, local, origin } of plan) {
     const sides = [local && "local", origin && "origin"].filter(Boolean).join(" + ");
     console.log(`  ${name}  (${sides})`);
   }
+  if (ask && plan.length > 0 && !await confirm(plan.length === 1 ? "Remove this branch? [Y/n] " : `Remove these ${plan.length} branches? [Y/n] `)) {
+    console.log("Nothing removed.");
+    return;
+  }
   for (const { name, local, origin } of plan) {
     if (local)
       gitArgs(["branch", "-d", "--", name]);
@@ -1264,12 +1517,12 @@ function openerFor(platform, url) {
 var KINDS = ["patch", "minor", "major"];
 
 // src/components/release/release.utils.ts
-import { execSync } from "node:child_process";
+import { execSync as execSync2 } from "node:child_process";
 function npmVersion(kind) {
   console.log(`> npm version ${kind}`);
   if (isDryRun())
     return;
-  execSync(`npm version ${kind}`, { stdio: "inherit" });
+  execSync2(`npm version ${kind}`, { stdio: "inherit" });
 }
 
 // src/components/release/release.ts
@@ -1660,7 +1913,7 @@ function tree(flags) {
 }
 
 // src/components/version/version.ts
-import { readFileSync as readFileSync3 } from "node:fs";
+import { readFileSync as readFileSync4 } from "node:fs";
 
 // src/components/version/version.constants.ts
 var MASCOT = [
@@ -1675,15 +1928,15 @@ var MASCOT = [
 ];
 
 // src/components/version/version.utils.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
 import path2 from "node:path";
 import { fileURLToPath } from "node:url";
 function packageJsonPath() {
   let dir = path2.dirname(fileURLToPath(import.meta.url));
   for (;; ) {
     const candidate = path2.join(dir, "package.json");
-    if (existsSync2(candidate)) {
-      const pkg = JSON.parse(readFileSync2(candidate, "utf8"));
+    if (existsSync3(candidate)) {
+      const pkg = JSON.parse(readFileSync3(candidate, "utf8"));
       if (pkg.name === "@tertium/gith")
         return candidate;
     }
@@ -1696,7 +1949,7 @@ function packageJsonPath() {
 
 // src/components/version/version.ts
 function readVersion() {
-  const pkg = JSON.parse(readFileSync3(packageJsonPath(), "utf8"));
+  const pkg = JSON.parse(readFileSync4(packageJsonPath(), "utf8"));
   return pkg.version ?? "unknown";
 }
 function versionText() {
@@ -1710,21 +1963,27 @@ function versionText() {
 var USAGE = `gith - git helper: branch flow and everyday git commands
 
 Start and finish work
-  gith create -b <branch>            work branch from develop, named by its goal (no switch)
+  gith create -b <branch>            work branch develop--<branch> from develop (no switch)
   gith create -r <version>           release/<version> from develop
   gith create -h <version>           hotfix/<version> from main
   gith create --release | --hotfix   version from the latest tag: minor for release, patch for hotfix
-  gith switch -b <branch>            switch to a branch, creating it from develop if missing (on a detached HEAD: from that commit)
+  gith switch                        list local and origin branches, and switch to the one picked
+  gith switch -b <branch>            switch to a branch, creating develop--<branch> from develop if missing (on a detached HEAD: <branch> from that commit)
   gith switch -commit <sha>          detach HEAD at a commit, to look at it (tracked files must be clean)
+  gith switch --release | --hotfix   switch to the newest release/* or hotfix/* (local or origin); -r / -h do the same; -r <v> / -h <v> for one version
   gith update                        merge origin/develop into this work branch
-  gith merge [-r <v> | -h <v>]       merge this branch into develop, release/<v> or hotfix/<v>
+  gith finish --current-release | --current-hotfix  release the newest release/* or hotfix/*: version, changelog, merge to main, tag, back to develop
+  gith merge --develop               merge this branch into develop
+  gith merge --main                  merge this branch into main
+  gith merge                         pick the branch to merge, then the target (main, develop, release/*, hotfix/*)
+  gith merge [-r <v> | -h <v>]       merge this branch into release/<v> or hotfix/<v>; without a version, the only one or a pick from the list
   gith merge --current-release       merge this branch into the newest release (local or origin)
   gith merge --current-hotfix        merge this branch into the newest hotfix (local or origin)
   gith release --patch | --minor | --major   bump the version and publish
 
 Fix history
   gith undo                          undo the last commit, keep its changes staged (not if pushed)
-  gith save [-m <msg>]               fold staged changes into the last commit, or commit them if the branch has none yet (asks for a message); pushes if origin differs (asks before a force-push)
+  gith save [-m <msg>] [--all]       fold staged changes (--all stages every change first) into the last commit, or commit them if the branch has none yet (asks for a message); pushes if origin differs (asks before a force-push)
   gith squash -limit <n> [-m <msg>]  combine the last n commits into one (keeps the oldest message)
 
 Save and reset work
@@ -1737,7 +1996,8 @@ Clean up branches (every removal shows what it will remove first)
   gith remove -b <branch>            delete the branch here and on origin (either side may be missing)
   gith remove -b <branch> --local    delete only the local branch
   gith remove -b <branch> --remote   delete only the origin branch
-  gith remove --branch [-l <n>]      pick from branch pairs (here and on origin)
+  gith remove                        pick branches to delete from a list (here and on origin)
+  gith remove --branch [-l <n>]      same list, for branch pairs (here and on origin)
   gith remove --branch --local       pick from local branches
   gith remove --branch --remote      pick from origin branches
   gith remove --obsolete [--local] [-days <n>]   remove branches untouched for 90 days, after Y/n
@@ -1794,11 +2054,14 @@ try {
     case "create":
       create(parseFlags(rest));
       break;
+    case "finish":
+      await finish(parseFlags(rest));
+      break;
     case "merge":
-      merge(parseFlags(rest));
+      await merge(parseFlags(rest));
       break;
     case "switch":
-      switchBranch(parseFlags(rest));
+      await switchBranch(parseFlags(rest));
       break;
     case "remove":
     case "rm":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tertium/gith",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Git helper: branch flow with goal branches, release and hotfix containers, and everyday git commands.",
   "type": "module",
   "bin": {
@@ -15,7 +15,10 @@
     "test": "bun test --no-coverage",
     "lint": "biome check src",
     "lint:fix": "biome check --write src",
+    "format": "biome format --write src",
+    "format:check": "biome format src",
     "typecheck": "tsc --noEmit",
+    "prepare": "git config core.hooksPath .githooks || true",
     "release:patch": "node bin/gith.js release --patch",
     "release:minor": "node bin/gith.js release --minor",
     "release:major": "node bin/gith.js release --major",