@tertium/gith 0.4.0 → 0.5.0

package/README.md

@@ -1,22 +1,31 @@
 # @tertium/gith
 
+<img src="assets/gith-icon.svg" alt="gith mascot with three commit sprouts" width="128" />
+
 gith: git-only branch flow CLI (goal branches, release/hotfix containers, synced merges).
 
 ```
-          o
-         /
-   o----o----o
+        o
+   o    |    o
     \   |   /
      \  |  /
-      (o_o)     gith v0.1.0
-      /|_|\     git happens.
-       d b
+      \ | /
+       \|/
+        |
+      .---.
+     ( o o )    gith
+      '---'     git happens.
+        |
+       /|\
+       / \
 ```
 
 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, push, pull, 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).
 
 See [Command design rules](docs/RULES.md) before changing or adding commands and flags.
 
+See [CHANGELOG.md](CHANGELOG.md) for user-facing release notes and the changes included in each version. GitHub Releases are also published for tagged versions.
+
 > **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.
 
 ## Usage
@@ -28,6 +37,8 @@ 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               # next release version from the latest tag
 gith create --hotfix                # next hotfix version from the latest tag
+gith create -r 1.2.0 --update-version --npm # also set npm version to 1.2.0 on the new release branch
+gith create --hotfix --update-version --npm # same for an automatically selected hotfix version
 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
@@ -44,9 +55,9 @@ gith merge --release                # this branch into the only release, or pick
 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)
-gith release --patch                # npm version patch, published through main
-gith release --minor                # npm version minor, from develop into main
-gith release --major                # npm version major, from develop into main
+gith release --patch                # sync main into develop without changing package versions
+gith release --minor                # merge develop into main and sync back
+gith release --major --update-version --npm # bump npm major version and release through main
 
 # Fix history
 gith undo                           # undo the last commit, keep its changes staged (not if pushed)
@@ -75,14 +86,14 @@ gith remove --detached              # pick local branches that have no origin co
 gith remove --detached --all        # remove all of them: lists them, then asks Y/n
 
 # Look at the repo
-gith status                         # branch vs origin, and staged, unstaged and untracked counts
+gith status                         # working-tree summary, all local and remote-tracking branches
 gith list --commits                 # the last 5 commits on this branch
 gith list --commits --graph         # the same, as a branch graph
 gith list --commits -l 10           # the last 10 (-limit 10 works too)
 gith list --tags                    # the newest 5 tags with a LOCAL and ORIGIN column
 gith list --tags -l 20              # the newest 20
 gith list --stashes                 # the newest 5 stashes (-l for more)
-gith show --pockets                 # the same, with Gorlum: my precious pockets!
+gith show --pockets                 # the same, with the gith mascot: my precious pockets!
 gith find -commit "login" -limit 10  # commits whose message mentions login (search is the same; default 5)
 gith search -file "*api.ts" -limit 3 # commits that changed a matching file, with the files listed
 gith find -change "TODO"           # commits that added or removed the text in their diff
@@ -138,6 +149,7 @@ One rule applies to every command: **a single dash always takes a value, and a d
 | `-file <pattern>`, `-change <text>` | value | `find` |
 | `-l <n>`, `-limit <n>` | value, positive whole number | every listing: `list`, `tree`, the picker |
 | `--patch`, `--minor`, `--major` | switch | `release` |
+| `--update-version`, `--npm` | switches, required together for npm version updates | `release`, `create` with `-r`/`-h`/`--release`/`--hotfix` |
 | `--overall`, `--current-year`, `--current-month`, `--current-week`, `--last-year`, `--last-month`, `--last-week` | switch, one at a time | `stat` |
 | `--local`, `--remote` | switch | `remove` (both sides when neither is given) |
 | `--obsolete`, `--detached` | switch | `remove` |
@@ -160,7 +172,7 @@ Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `
 - **`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.
-- **`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.
+- **`status`** prints the current branch and how far it is ahead of or behind its upstream, then counts staged, unstaged, untracked and conflicting files. It also lists all local branches (`*` marks the current branch; `+` marks branches in other worktrees) and remote-tracking branches from every configured remote. Remote branches reflect the last fetch; run `git fetch --all --prune` to refresh them. Empty lists are shown explicitly. Status changes nothing and does not contact remotes.
 - **`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.
 - **`push` / `pull`** work with the current branch and its same-named branch on origin. They report fresh ahead/behind counts and stop with instructions when histories diverge. Push sets upstream tracking and publishes missing branches; it never force-pushes. Pull requires clean tracked files, fast-forwards only, and points to `gith push` when local commits remain. `--all-branches` applies to every local branch, preflighting all before updating any. Push sends them atomically (origin must support atomic pushes); pull requires each to exist on origin and updates branches without switching. Branches checked out in other worktrees cannot be updated by pull. Remote-only branches are not created. Pull may leave earlier branches updated if a later Git operation fails; it never rolls back successful fast-forwards. Dry runs print actions without fetching or changing refs.
@@ -171,7 +183,7 @@ Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `
   - `-file <pattern>` matches the paths changed by the commit, using git's pattern rules (`*api.ts` matches `src/api.ts`). Each commit lists the matching files it changed.
   - `-change <text>` matches commits whose diff adds or removes the text (`git log -S`). With `--regex`, it matches a regular expression against the diff (`git log -G`).
   - `-limit <n>` sets how many to show (default 5). The filters combine with AND.
-- **`show`** is a synonym for `list`: `gith show --tags` and `gith list --tags` do the same. `--pockets` is a fun name for `--stashes`, and it prints a Gorlum figure above the list.
+- **`show`** is a synonym for `list`: `gith show --tags` and `gith list --tags` do the same. `--pockets` is a fun name for `--stashes`, and it prints the gith mascot above the list, matching `gith --version` and the SVG/PNG logo in `assets/`.
 - **`list --stashes`** shows the stashes, newest first, with their date and description. Like the other listings, it shows 5 by default, and `-limit` changes that.
 - **`squash -limit <n>`** combines the last `n` commits on the current work branch into one, using `reset --soft` and a single commit. Without `-m` the result keeps the oldest of the combined commits, its message and author. It refuses when `n` is below 2, when `n` would reach the first commit, when a merge is among them, when any of them is already on origin, on a container, or with a dirty working tree.
 - **`stat`** reads the history of the current branch and prints a table of facts: commit count, top author, the biggest commit (lines added and removed), average size, the most changed file, the busiest day, weekday and hour, the longest streak of days with a commit, night owl and weekend commits, and the conventional commit types. The period is one switch: `--overall` (the default), `--current-year`, `--current-month`, `--current-week` (weeks start on Monday), or the matching `--last-` switch for the previous year, month or week. `-limit <n>` looks only at the last `n` commits. Stat changes nothing.
@@ -195,6 +207,7 @@ Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `
 
 - **`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.
+- **`create -r/-h/--release/--hotfix --update-version --npm`** also sets npm's version to the branch version and commits `package.json` and any npm lockfiles on that new branch before pushing. Both flags are required together and are rejected for work branches. This uses a temporary worktree, leaves your checked-out branch and local changes intact, and creates no version tag. npm lifecycle scripts are skipped; changelog preparation remains part of finishing the release. An already matching package version needs no commit. Without both flags, creation does not run npm or change package versions. The selected base must contain a `package.json` with a version. If npm or the commit fails, the new branch and temporary worktree remain available for inspection and are not pushed.
 - **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.
@@ -207,10 +220,14 @@ Containers (`develop`, `main`, `release/*`, `hotfix/*`) can't be merged from, an
 
 Run as `gith release --patch`, `--minor` or `--major`.
 
-- **`patch`** runs from `main`: bumps the version, pushes with tags, then rebases `develop` onto `main`. The push back to `develop` uses `--force-with-lease`, so it refuses to overwrite a `develop` that moved on origin.
-- **`minor` and `major`** run from `develop`: bump the version with its changelog entry, push with tags, merge `develop` into `main`, then bring `main` back to `develop`.
+- **`patch`** runs from `main`: pushes with tags, then rebases `develop` onto `main`. The push back to `develop` uses `--force-with-lease`, so it refuses to overwrite a `develop` that moved on origin.
+- **`minor` and `major`** run from `develop`: push with tags, merge `develop` into `main`, then bring `main` back to `develop`.
+
+Both need a clean working tree. By default, they perform only the Git flow: no package manager runs, no package files change, and no new version tag is created. Existing annotated tags reachable from pushed commits can still be pushed.
+
+Add **both `--update-version --npm`** to run `npm version` with the selected patch, minor, or major bump before pushing. This requires npm and a `package.json` with a version; npm lifecycle scripts run as usual. Either flag alone is an error. npm is currently the only supported versioning tool. This repository's `release:patch`, `release:minor`, and `release:major` scripts pass both flags explicitly.
 
-Both need a clean working tree and a `package.json` with a version, because they call `npm version`.
+Pushing a `v*` tag publishes the package and creates a GitHub Release with generated notes.
 
 ## Errors
 

package/bin/gith.js

@@ -19,6 +19,8 @@ var SPECS = new Map([
   ["patch", "switch"],
   ["minor", "switch"],
   ["major", "switch"],
+  ["update-version", "switch"],
+  ["npm", "switch"],
   ["remote", "switch"],
   ["local", "switch"],
   ["tags", "switch"],
@@ -449,7 +451,7 @@ function find(flags) {
 
 // src/components/flow/flow.ts
 import { execSync } from "node:child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "node:fs";
 
 // src/components/prompt/prompt.ts
 import { emitKeypressEvents } from "node:readline";
@@ -604,6 +606,16 @@ function nextVersion(tags, bump) {
 }
 
 // src/components/flow/flow.utils.ts
+import { spawnSync } from "node:child_process";
+import {
+  existsSync as existsSync2,
+  mkdtempSync,
+  realpathSync,
+  symlinkSync,
+  unlinkSync
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path2 from "node:path";
 function containers(kind) {
   const prefix = `${kind}/`;
   const local = captureArgs([
@@ -640,31 +652,77 @@ function nextContainerVersion(kind) {
   console.log(`Next ${kind} version from existing tags: ${version}`);
   return version;
 }
-function open(kind, version) {
+var open = (kind, version, shouldUpdateVersion) => {
+  if (shouldUpdateVersion && !/^\d+\.\d+\.\d+$/.test(version))
+    throw new Error("npm version updates require a version in X.Y.Z format; use -r or -h with that version.");
   const name = containerName(kind, version);
+  assertBranchName(name);
+  if (hasLocal(name))
+    throw new Error(`'${name}' already exists locally.`);
   if (hasOnOrigin(name))
     throw new Error(`'${name}' already exists on origin.`);
   const base = containerBase(kind);
   gitArgs(["fetch", "origin", base]);
+  const needsVersionUpdate = shouldUpdateVersion && parsePackageVersion(captureArgs(["show", `origin/${base}:package.json`])) !== version;
   gitArgs(["branch", name, `origin/${base}`]);
+  if (needsVersionUpdate)
+    updateContainerVersion(name, version);
   gitArgs(["push", "-u", "origin", name]);
-}
+};
+var updateContainerVersion = (name, version) => {
+  if (isDryRun()) {
+    process.stdout.write(`> npm version ${version} --no-git-tag-version --ignore-scripts (temporary worktree for ${name})
+`);
+    return;
+  }
+  const cwd = mkdtempSync(path2.join(tmpdir(), "gith-version-"));
+  gitArgs(["worktree", "add", cwd, name]);
+  const hasDependencies = existsSync2("node_modules");
+  if (hasDependencies)
+    symlinkSync(realpathSync("node_modules"), path2.join(cwd, "node_modules"), "junction");
+  try {
+    commitContainerVersion(cwd, version);
+  } finally {
+    if (hasDependencies)
+      unlinkSync(path2.join(cwd, "node_modules"));
+  }
+  gitArgs(["worktree", "remove", cwd]);
+};
+var commitContainerVersion = (cwd, version) => {
+  const result = spawnSync("npm", ["version", version, "--no-git-tag-version", "--ignore-scripts"], {
+    cwd,
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  if (result.error || result.status !== 0)
+    throw new Error(`npm version failed; inspect the preserved worktree at ${cwd} and retry.`, { cause: result.error });
+  gitArgs([
+    "add",
+    "--",
+    ...["package.json", "package-lock.json", "npm-shrinkwrap.json"].filter((file) => existsSync2(path2.join(cwd, file)))
+  ], { cwd });
+  gitArgs(["commit", "-m", version], { cwd });
+};
 
 // src/components/flow/flow.ts
-function create(flags) {
-  assertAllowedFlags(flags, ["branch", "release", "hotfix"], "create");
+var create = (flags) => {
+  assertAllowedFlags(flags, ["branch", "release", "hotfix", "update-version", "npm"], "create");
+  if (flags.has("update-version") !== flags.has("npm"))
+    throw new Error("Version updates require both --update-version and --npm; pass both flags or omit both.");
   const kind = onlyOne(flags, ["branch", "release", "hotfix"]);
   if (!kind)
-    throw new Error("usage: gith create -b <branch> | -r <version> | -h <version> | --release | --hotfix");
+    throw new Error("usage: gith create -b <branch> | (-r <version> | -h <version> | --release | --hotfix) [--update-version --npm]");
   const value = flags.get(kind) ?? "";
   if (kind === "branch") {
+    if (flags.has("update-version"))
+      throw new Error("--update-version --npm only applies to release or hotfix branch creation.");
     if (!value)
       throw new Error("usage: gith create -b <branch>");
     createBranch(value);
     return;
   }
-  open(kind, value || nextContainerVersion(kind));
-}
+  open(kind, value || nextContainerVersion(kind), flags.has("update-version"));
+};
 async function merge(flags) {
   assertAllowedFlags(flags, [
     "develop",
@@ -819,7 +877,7 @@ async function mergePick() {
   await mergeInto(target, source);
 }
 function alignVersion(version) {
-  if (!existsSync2("package.json"))
+  if (!existsSync3("package.json"))
     return;
   const current = parsePackageVersion(readFileSync2("package.json", "utf8"));
   if (current === version)
@@ -835,10 +893,10 @@ function alignVersion(version) {
   gitArgs(["commit", "-m", version, "--", "package.json"]);
 }
 function addChangelogEntry(version) {
-  if (!existsSync2("package.json"))
+  if (!existsSync3("package.json"))
     return;
   const file = "CHANGELOG.md";
-  if (existsSync2(file) && readFileSync2(file, "utf8").includes(`## ${version} - `))
+  if (existsSync3(file) && readFileSync2(file, "utf8").includes(`## ${version} - `))
     return;
   changelog(new Map);
 }
@@ -1090,6 +1148,23 @@ async function squash(flags) {
     gitArgs(["commit", "-C", oldest]);
 }
 
+// src/components/version/version.constants.ts
+var MASCOT = [
+  "        o",
+  "   o    |    o",
+  "    \\   |   /",
+  "     \\  |  /",
+  "      \\ | /",
+  "       \\|/",
+  "        |",
+  "      .---.",
+  "     ( o o )",
+  "      '---'",
+  "        |",
+  "       /|\\",
+  "       / \\"
+];
+
 // src/components/list/list.constants.ts
 var DEFAULT_LIMIT2 = 5;
 var GRAPH_ARGS = [
@@ -1102,13 +1177,6 @@ var GRAPH_ARGS = [
   "--date=format:%Y-%m-%d %H:%M",
   "--format=%C(bold yellow)%h%C(reset)  %C(bold)%s%C(reset) %C(auto)%d%C(reset)%n%C(dim)   └─ %an · %ad%C(reset)%n"
 ];
-var GORLUM = [
-  '      .-"""-.',
-  "     /  o o  \\",
-  "    |   ___   |   my precious pockets!",
-  "     \\ (___) /",
-  "      '-._.-'"
-];
 
 // src/components/list/list.utils.ts
 function yesNo(value) {
@@ -1192,10 +1260,12 @@ function localTags() {
   return captureArgs(["tag", "--list"]).split(`
 `).filter(Boolean);
 }
-function stashes(limit, withGorlum) {
-  if (withGorlum)
-    console.log(GORLUM.join(`
-`));
+var stashes = (limit, withMascot) => {
+  if (withMascot)
+    process.stdout.write(`${MASCOT.join(`
+`)}
+my precious pockets!
+`);
   const rows = captureArgs([
     "stash",
     "list",
@@ -1204,7 +1274,9 @@ function stashes(limit, withGorlum) {
   ]).split(`
 `).filter(Boolean);
   if (rows.length === 0) {
-    console.log(withGorlum ? "There is nothing in my pockets!" : "No stashes.");
+    process.stdout.write(withMascot ? `There is nothing in my pockets!
+` : `No stashes.
+`);
     return;
   }
   const shown = rows.slice(0, limit);
@@ -1213,7 +1285,7 @@ function stashes(limit, withGorlum) {
   if (shown.length < rows.length) {
     console.log(`showing ${shown.length} of ${rows.length}; -limit <n> shows more`);
   }
-}
+};
 function tags(limit) {
   const pairs = tagPairs(localTags(), originTags());
   if (pairs.length === 0) {
@@ -1691,23 +1763,26 @@ function npmVersion(kind) {
 }
 
 // src/components/release/release.ts
-function release(kind) {
+var release = (kind, flags) => {
   if (!kind || !KINDS.includes(kind))
-    throw new Error("usage: gith release <patch|minor|major>");
+    throw new Error("usage: gith release --patch | --minor | --major [--update-version --npm]");
+  if (flags.has("update-version") !== flags.has("npm"))
+    throw new Error("Version updates require both --update-version and --npm; pass both flags or omit both.");
   assertCleanTree();
   if (kind === "patch") {
-    releasePatch();
+    releasePatch(flags.has("update-version"));
   } else {
-    releaseFromDevelop(kind);
+    releaseFromDevelop(kind, flags.has("update-version"));
   }
-}
-function releasePatch() {
+};
+var releasePatch = (shouldUpdateVersion) => {
   console.log(`
 \uD83D\uDCCB Starting patch release from main...
 `);
   git("checkout main");
   git("pull");
-  npmVersion("patch");
+  if (shouldUpdateVersion)
+    npmVersion("patch");
   git("push --follow-tags");
   git("checkout develop");
   git("pull");
@@ -1718,8 +1793,8 @@ function releasePatch() {
   console.log(`
 ✅ Patch release complete!
 `);
-}
-function releaseFromDevelop(kind) {
+};
+var releaseFromDevelop = (kind, shouldUpdateVersion) => {
   console.log(`
 \uD83D\uDCCB Starting ${kind} release from develop...
 `);
@@ -1727,7 +1802,8 @@ function releaseFromDevelop(kind) {
   if (current !== "develop")
     throw new Error(`must be on 'develop', currently on '${current}'.`);
   git("pull");
-  npmVersion(kind);
+  if (shouldUpdateVersion)
+    npmVersion(kind);
   git("push --follow-tags");
   git("checkout main");
   git("pull");
@@ -1735,21 +1811,22 @@ function releaseFromDevelop(kind) {
   git("push");
   git("checkout develop");
   git("pull origin main");
+  git("push");
   assertSynced(["main", "develop"]);
   console.log(`
 ✅ ${kind} release complete!
 `);
-}
+};
 
 // src/components/setup/setup.ts
 import {
   chmodSync,
-  existsSync as existsSync4,
+  existsSync as existsSync5,
   mkdirSync,
   readFileSync as readFileSync3,
   writeFileSync as writeFileSync2
 } from "node:fs";
-import path3 from "node:path";
+import path4 from "node:path";
 
 // src/components/setup/setup.constants.ts
 var HOOKS_DIR = ".githooks";
@@ -1770,8 +1847,8 @@ var RUN_PREFIX = {
 };
 
 // src/components/setup/setup.utils.ts
-import { existsSync as existsSync3 } from "node:fs";
-import path2 from "node:path";
+import { existsSync as existsSync4 } from "node:fs";
+import path3 from "node:path";
 function checkBlock(manager, script, label) {
   return `echo "▶ ${label}"
 ${RUN_PREFIX[manager]} ${script}
@@ -1791,11 +1868,11 @@ set -e
 ${checks}`;
 }
 function detectPackageManager(projectPath) {
-  const lockfile = LOCKFILES.find(([file]) => existsSync3(path2.join(projectPath, file)));
+  const lockfile = LOCKFILES.find(([file]) => existsSync4(path3.join(projectPath, file)));
   return lockfile?.[1] ?? "npm";
 }
 function isTypeScriptProject(projectPath, pkg) {
-  if (existsSync3(path2.join(projectPath, "tsconfig.json")))
+  if (existsSync4(path3.join(projectPath, "tsconfig.json")))
     return true;
   return Boolean(pkg.dependencies?.typescript || pkg.devDependencies?.typescript);
 }
@@ -1818,14 +1895,14 @@ function setup(flags) {
 }
 function setupNpmHook({ force }) {
   const root = process.cwd();
-  if (!existsSync4(path3.join(root, ".git"))) {
+  if (!existsSync5(path4.join(root, ".git"))) {
     throw new Error("not a git repository root: run it in the folder that holds .git");
   }
-  const packagePath = path3.join(root, "package.json");
-  if (!existsSync4(packagePath))
+  const packagePath = path4.join(root, "package.json");
+  if (!existsSync5(packagePath))
     throw new Error("no package.json in this folder");
-  const hookPath = path3.join(root, HOOK_FILE);
-  if (existsSync4(hookPath) && !force) {
+  const hookPath = path4.join(root, HOOK_FILE);
+  if (existsSync5(hookPath) && !force) {
     throw new Error(`${HOOK_FILE} already exists. Pass --force to overwrite it.`);
   }
   const pkg = JSON.parse(readFileSync3(packagePath, "utf8"));
@@ -1836,7 +1913,7 @@ function setupNpmHook({ force }) {
     console.log(`dry run: would write ${HOOK_FILE} (package manager: ${manager})`);
     return;
   }
-  mkdirSync(path3.join(root, HOOKS_DIR), { recursive: true });
+  mkdirSync(path4.join(root, HOOKS_DIR), { recursive: true });
   writeFileSync2(hookPath, hook);
   try {
     chmodSync(hookPath, 493);
@@ -2108,19 +2185,32 @@ function parseStatus(output) {
   }
   return status;
 }
-function status(flags) {
+var status = (flags) => {
   if (flags.size > 0)
     throw new Error("usage: gith status");
   const info = parseStatus(captureArgs(["status", "--porcelain=v2", "--branch"]));
   const against = info.upstream ? `${info.branch}  ->  ${info.upstream}  ahead ${info.ahead}, behind ${info.behind}` : `${info.branch}  (no upstream)`;
-  console.log(against);
+  process.stdout.write(`${against}
+`);
   const changed = info.staged + info.unstaged + info.untracked + info.conflicts;
-  if (changed === 0) {
-    console.log("working tree clean");
-    return;
+  process.stdout.write(changed === 0 ? `working tree clean
+` : `staged ${info.staged}, unstaged ${info.unstaged}, untracked ${info.untracked}, conflicts ${info.conflicts}
+`);
+  for (const [heading, scope] of [
+    ["Local branches (* current, + other worktree)", "--list"],
+    ["Remote branches (last fetched)", "--remotes"]
+  ]) {
+    const branches = captureArgs(["branch", "--no-color", scope]);
+    process.stdout.write(`
+${heading}:
+`);
+    process.stdout.write(branches.length === 0 ? `  (none)
+` : `${branches.split(`
+`).map((branch) => `  ${branch.trim()}`).join(`
+`)}
+`);
   }
-  console.log(`staged ${info.staged}, unstaged ${info.unstaged}, untracked ${info.untracked}, conflicts ${info.conflicts}`);
-}
+};
 
 // src/components/tree/tree.utils.ts
 function flagsOf(worktree) {
@@ -2190,32 +2280,20 @@ function tree(flags) {
 // src/components/version/version.ts
 import { readFileSync as readFileSync5 } from "node:fs";
 
-// src/components/version/version.constants.ts
-var MASCOT = [
-  "          o",
-  "         /",
-  "   o----o----o",
-  "    \\   |   /",
-  "     \\  |  /",
-  "      (o_o)",
-  "      /|_|\\",
-  "       d b"
-];
-
 // src/components/version/version.utils.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4 } from "node:fs";
-import path4 from "node:path";
+import { existsSync as existsSync6, readFileSync as readFileSync4 } from "node:fs";
+import path5 from "node:path";
 import { fileURLToPath } from "node:url";
 function packageJsonPath() {
-  let dir = path4.dirname(fileURLToPath(import.meta.url));
+  let dir = path5.dirname(fileURLToPath(import.meta.url));
   for (;; ) {
-    const candidate = path4.join(dir, "package.json");
-    if (existsSync5(candidate)) {
+    const candidate = path5.join(dir, "package.json");
+    if (existsSync6(candidate)) {
       const pkg = JSON.parse(readFileSync4(candidate, "utf8"));
       if (pkg.name === "@tertium/gith")
         return candidate;
     }
-    const parent = path4.dirname(dir);
+    const parent = path5.dirname(dir);
     if (parent === dir)
       throw new Error("gith package.json not found");
     dir = parent;
@@ -2229,7 +2307,18 @@ function readVersion() {
 }
 function versionText() {
   const version = readVersion();
-  const side = ["", "", "", "", "", `gith v${version}`, "git happens.", ""];
+  const side = [
+    "",
+    "",
+    "",
+    "",
+    "",
+    "",
+    "",
+    "",
+    `gith v${version}`,
+    "git happens."
+  ];
   return MASCOT.map((line, i) => `${line.padEnd(16)}${side[i] ?? ""}`.trimEnd()).join(`
 `);
 }
@@ -2242,6 +2331,7 @@ Start and finish work
   gith create -r <version>           release/<version> from develop
   gith create -h <version>           hotfix/<version> from main
   gith create --release | --hotfix   next version from the latest tag
+  gith create -r <version> --update-version --npm   also commit npm version on the new branch; works with -h, --release, --hotfix
   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)
@@ -2255,7 +2345,7 @@ Start and finish work
   gith merge -r <v> | -h <v>         merge into release/<v> or hotfix/<v>
   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
+  gith release --patch | --minor | --major   sync release branches; add --update-version --npm to bump npm version
 
 Fix history
   gith undo                          undo the last commit, keep its changes staged (not if pushed)
@@ -2282,10 +2372,10 @@ Clean up branches (every removal shows what it will remove first)
   gith rm                            alias of remove
 
 Look at the repo
-  gith status                        branch vs origin, and staged, unstaged and untracked counts
+  gith status                        working-tree summary, all local and remote-tracking branches
   gith list --commits [--graph] [-l <n>]   newest commits on this branch; --graph adds colored lanes, refs, author/date (default 5)
   gith list --tags [-l <n>]          tags with a local and origin column (newest 5 by default)
-  gith list --stashes [-l <n>]       stashes, newest first (default 5); --pockets shows them with Gorlum
+  gith list --stashes [-l <n>]       stashes, newest first (default 5); --pockets shows them with the gith mascot
   gith show ...                      same as gith list
   gith tree [-l <n>]                 working trees: path, branch, HEAD (current marked *)
   gith find|search [-commit <text>] [-file <pattern>] [-change <text>] [--regex] [-limit <n>]
@@ -2315,6 +2405,7 @@ Flags: every single-dash flag requires a value; double-dash flags never take one
   -b -r -h -l -m -n -limit -message -name -branch -release -hotfix -commit -file -change -days   take values
   --patch --minor --major --local --remote --obsolete --detached --tags --commits --graph --stashes --pockets --branch --regex
   --develop --main --current-release --current-hotfix --all --&push --all-branches --no-commit --force
+  --update-version --npm             release or create release/hotfix: opt in to npm version updates (both required)
   --overall --current-year --current-month --current-week --last-year --last-month --last-week   switches
   --branch lists removable branches; --release / --hotfix choose a version or branch by command context
   -limit caps listings and stat (or -l); -days sets the age for remove --obsolete`;
@@ -2418,11 +2509,11 @@ try {
       break;
     case "release": {
       const flags = parseFlags(rest);
-      assertAllowedFlags(flags, ["patch", "minor", "major"], "release");
+      assertAllowedFlags(flags, ["patch", "minor", "major", "update-version", "npm"], "release");
       const kind = onlyOne(flags, ["patch", "minor", "major"]);
       if (!kind)
-        throw new Error("usage: gith release --patch | --minor | --major");
-      release(kind);
+        throw new Error("usage: gith release --patch | --minor | --major [--update-version --npm]");
+      release(kind, flags);
       break;
     }
     case "--version":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tertium/gith",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Git helper: branch flow with goal branches, release and hotfix containers, and everyday git commands.",
   "type": "module",
   "bin": {
@@ -19,9 +19,9 @@
     "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",
+    "release:patch": "node bin/gith.js release --patch --update-version --npm",
+    "release:minor": "node bin/gith.js release --minor --update-version --npm",
+    "release:major": "node bin/gith.js release --major --update-version --npm",
     "version": "bun run build && node bin/gith.js changelog --no-commit && git add -- CHANGELOG.md"
   },
   "license": "MIT",