@tertium/gith 0.3.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,17 +26,19 @@ 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                         # list local and origin branches, and switch to the one you pick
-gith switch -b login-redirect       # switch to the branch, creating it from develop if it is missing
+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
@@ -45,7 +47,8 @@ gith merge                          # this branch into develop
 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 -r 1.2.0                 # this branch into release/1.2.0
+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)
@@ -55,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
@@ -120,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` |
@@ -145,7 +151,7 @@ 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`** 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.
@@ -179,7 +185,7 @@ 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.

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"],
@@ -29,6 +29,7 @@ var SPECS = new Map([
   ["current-release", "switch"],
   ["current-hotfix", "switch"],
   ["develop", "switch"],
+  ["main", "switch"],
   ["pockets", "switch"],
   ["detached", "switch"],
   ["all", "switch"],
@@ -89,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") {
@@ -548,7 +553,7 @@ async function select(question, options, multi) {
 
 // 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) {
@@ -597,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",
@@ -608,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";
@@ -658,6 +667,7 @@ async function merge(flags) {
     return mergePick();
   const kind = onlyOne(flags, [
     "develop",
+    "main",
     "release",
     "hotfix",
     "current-release",
@@ -666,31 +676,50 @@ async function merge(flags) {
   let target = "develop";
   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;
   }
   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;
 }
 async function mergeInto(target, from) {
   if (!isTarget(target))
@@ -889,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.");
   }
@@ -1163,10 +1194,14 @@ async 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);
@@ -1928,26 +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                        list local and origin branches, and switch to the one picked
-  gith switch -b <branch>            switch to a branch, creating it from develop if missing (on a detached HEAD: from that commit)
+  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 <v> / -h <v> for one version
+  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 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                         pick the branch to merge, then the target (develop, release/*, hotfix/*)
-  gith merge [-r <v> | -h <v>]       merge this branch into develop, release/<v> or hotfix/<v>
+  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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tertium/gith",
-  "version": "0.3.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",