@tertium/gith 0.3.3 → 0.5.0

package/README.md

@@ -1,19 +1,30 @@
 # @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, 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, 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.
 
@@ -24,30 +35,33 @@ Git helper: the branch flow from [git-convention](https://github.com/Tertiumnon/
 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 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
 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 --develop                # 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 --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 -r 1.2.0                 # this branch into release/1.2.0
+gith merge --release                # this branch into the only release, or pick one
 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)
-gith save [-m "msg"] [--all]         # stages unstaged changes first (--all without asking), commits locally, asks to amend the previous commit or to make a new one, then asks to push (force-push after an amend)
+gith save -m "msg" [--all] ["--&push"] # new commit without prompts; push only with "--&push"
 gith squash -limit 3 [-m "msg"]     # combine the last 3 commits into one (keeps the oldest message)
 
 # Save and reset work
@@ -72,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
@@ -89,6 +103,8 @@ gith stat                           # fun facts about this branch: biggest commi
 gith stat --last-week -limit 50     # the same for last week, looking at no more than 50 commits
 
 # Remote and health
+gith push [--all-branches]          # push to origin with tracking and ahead/behind counts; never force
+gith pull [--all-branches]          # fast-forward from origin; stop on divergence
 gith sync                           # fetch all remotes and tags, prune stale refs, then sync this branch with origin both ways
 gith sync --develop | --main         # the same for develop or main
 gith sync develop:develop           # two-way sync of one branch with origin
@@ -97,6 +113,10 @@ gith doctor                         # check the repo is ready for the branch flo
 gith changelog --dry-run            # preview the CHANGELOG.md entry for package.json's version
 gith changelog                      # write it as its own commit (docs(changelog): <version>); --no-commit only writes
 
+# Set up
+gith setup -n npm                   # write .githooks/pre-commit (lint, typecheck, test) and set core.hooksPath
+gith setup -n npm --force           # overwrite an existing hook
+
 # Help
 gith help                           # full usage
 gith --version                      # the version, with the mascot
@@ -107,34 +127,40 @@ gith list --tags --verbose
 
 ## Flags
 
-One rule applies to every command: **a single dash always takes a value, and a double dash never does.** So `-limit 10` is right, and `--limit 10` and `-remote` are errors that name the right spelling.
+One rule applies to every command: **a single dash always takes a value, and a double dash never does.** So `-limit 10` is right, while `--limit 10`, `-remote`, `-r` and `-h` without values are errors. Use `--release` or `--hotfix` for automatic selection.
 
 | Flag | Kind | Used by |
 | --- | --- | --- |
 | `-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` |
+| `-r <version>`, `-release <version>` | value | `create`, `switch`, `merge` |
+| `--release` | automatic version in `create`; newest container in `switch`; only container or picker in `merge` | `create`, `switch`, `merge` |
 | `--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` |
+| `-h <version>`, `-hotfix <version>` | value | `create`, `switch`, `merge` |
+| `--hotfix` | automatic version in `create`; newest container in `switch`; only container or picker in `merge` | `create`, `switch`, `merge` |
+| `-limit <n>` | value | `squash`: commits to combine; listings and `stat`: rows or commits to show |
+| `-m <msg>`, `-message <msg>` | value | `save` (required), `squash` |
+| `--all` | switch | `save`: stage all changes |
+| `"--&push"` | switch | `save`: push after committing |
+| `--all-branches` | switch | `push`, `pull`: all local branches |
 | `-n <name>`, `-name <name>` | value | `stash` |
+| `-commit <sha>` | value | `switch`: detach at a commit |
+| `-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` |
+| `--force` | switch | `setup`: replace an existing hook |
+| `--no-commit` | switch | `changelog`: update the file without committing |
 | `-days <n>` | value | `remove --obsolete` |
 | `--tags`, `--commits`, `--graph`, `--stashes`, `--pockets` | switch | `list` (also `show`) |
 | `--verbose` | switch | every command |
 | `--dry-run` | switch | every command |
 
-Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `list --tags` and `--commits`) accept only one of them. `-limit` caps listings and `stat`, and on `squash` it sets how many commits to combine. `-message` only applies to `squash`.
+Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `list --tags` and `--commits`) accept only one of them. `-limit` caps listings and `stat`, and on `squash` it sets how many commits to combine. `-message` applies to `save` and `squash`.
 
 `--verbose` and `--dry-run` can go anywhere on the line:
 - `--dry-run` prints each git command that would change something, and runs none of them. Read-only checks still run, so a refusal (for example, "HEAD is already on origin") appears in a dry run too. `clean` and `reset` also list the files they would remove or discard.
@@ -146,17 +172,18 @@ 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.
-- **`save`** commits the staged changes locally and never pushes without asking. When changes are not staged yet, it stages them first: a single file is staged silently, and with several it asks `Stage all N changes first? [Y/n]` (a no keeps only what is staged; `--all` stages without asking). If the branch has commits of its own (commits origin's `develop`, or `main`, lacks), it asks `Amend the previous commit? [Y/n]`. Yes folds the changes into the last commit with `git commit --amend --no-edit`, keeping its message; `-m` replaces it. No, or no own commits, creates a new commit, asking for its message (an empty answer is refused, and `-m` skips the question). It refuses with nothing staged. Then it asks `Push <branch> to origin? [Y/n]`, a plain `git push -u origin <branch>`. After an amend of a commit origin already has, it asks `Force-push <branch> to origin? [Y/n]` instead, which runs `git push --force-with-lease origin <branch>` and refuses if origin moved since your last fetch. A no leaves the commit local. The questions need a terminal, so a script must pass `--yes`, and a commit made before the push question stays local if that question is not answered.
+- **`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.
+- **`save`** requires a nonempty `-m` and always creates a new commit, without prompts or amending. It stages a single unstaged file automatically; use `--all` to stage several, or stage your selection with `git add`. With nothing staged it fails. It saves locally unless `"--&push"` is supplied, which runs `gith push` after committing. Quote the flag because shells interpret `&`. A failed push leaves the new commit saved locally; retry with `gith push`.
 - **`stash`** saves changes with `git stash push --include-untracked`. `-n` names the stash. It refuses when there is nothing to save.
 - **`find`** (also `search`) lists the newest commits on this branch that match every filter given:
   - `-commit <text>` matches the commit message, ignoring case, and the text is literal.
   - `-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.
@@ -166,12 +193,13 @@ Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `
 - **`remove --detached`** fetches and prunes origin, then lists local branches that have no origin copy and lets you pick from them, the same as `remove --branch --local` but for branches with no origin copy only.
 - **Every removal shows what it will remove** before deleting anything, including the direct `remove -b` form. The picker and the prompt both show it first.
 - **`open`** opens origin in the browser, turning an `ssh` or `https` remote into a web address. GitHub and GitLab style addresses work.
+- **`setup -n npm`** writes `.githooks/pre-commit` for an npm project and sets `core.hooksPath` to `.githooks`, so every clone runs the same checks. The hook runs `lint`, `typecheck` and `test` (the scripts are picked up from package.json; TypeScript projects always run `lint` and `typecheck`, and `test` only when it exists). It uses the package manager from the lockfile (`bun`, `pnpm`, `yarn`, or `npm`). It adds a `prepare` script so installing the project turns the hooks on again. It refuses to overwrite an existing hook unless `--force` is given, and it must run in the folder that holds `.git`. Only `npm` is supported for now.
 - **`doctor`** checks git, a repository, origin, its reachability, `main` and `develop` on origin, and a clean working tree. It exits 1 if a required check fails, and only warns about the tree.
 - **`sync`** runs `git fetch --all --tags --prune`, then syncs the current branch with origin in both directions. `sync --develop` and `sync --main` do the same for that branch, even when another branch is checked out.
 - **`sync <branch>:<branch>`** (for example `sync develop:develop`) is the same as `sync --develop` for any branch name. If origin is ahead, it fetches the branch like `git fetch origin develop:develop`; if local is ahead, it pushes it; if it is the same, it says so. A checked-out branch is fast-forwarded with `merge --ff-only`. Diverged branches stop with an error, and nothing is forced. A branch missing on one side is created there. `sync develop` alone works too.
 - **`tree`** lists the working trees of the repository (`git worktree list`): each path, its branch or `(detached)`, and its short HEAD. The current one is marked `*`, and bare, locked or prunable trees are noted. `-limit <n>` caps the rows; all are shown by default.
 - **`list --tags`** shows every tag once, with yes/no columns for local and origin, so you can see which tags are unpushed or missing locally. Version tags are listed newest first, and only the first 5 are shown by default. `-limit <n>` (or `-l <n>`) changes that and adds a note when rows are left out.
-- **`list --commits`** shows the newest commits on the current branch, one per line: short hash, date, author and subject. With `--graph` it draws the branch graph instead. It shows 5 by default; `-l <n>` (or `-limit <n>`) changes that and must be a positive whole number. `-limit` only applies to listings. `gith list` with no flag prints usage.
+- **`list --commits`** shows the newest commits on the current branch, one per line: short hash, date, author and subject. With `--graph` it draws a framed branch graph with colored topology lanes, highlighted hashes and branch/tag labels, and author/date rows. Colors are enabled in terminals and disabled for pipes, `NO_COLOR`, or `TERM=dumb`. Git preserves merge topology; history remains scoped to the current branch. It shows 5 by default; `-l <n>` (or `-limit <n>`) changes that and must be a positive whole number. `-limit` only applies to listings. `gith list` with no flag prints usage.
 - **`clean`** runs `git clean -fd`. It permanently removes untracked files and directories, but keeps ignored files.
 - **`reset`** runs `git reset --hard` (discards staged and unstaged edits on this branch), then `git clean -fd`. It cannot be undone, so commit or stash first. It does not move the branch to origin.
 
@@ -179,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.
@@ -191,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, 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

@@ -6,8 +6,8 @@ import { exit } from "node:process";
 // src/components/args/args.constants.ts
 var SPECS = new Map([
   ["branch", "auto"],
-  ["release", "optional"],
-  ["hotfix", "optional"],
+  ["release", "auto"],
+  ["hotfix", "auto"],
   ["limit", "value"],
   ["message", "value"],
   ["name", "value"],
@@ -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"],
@@ -33,7 +35,10 @@ var SPECS = new Map([
   ["pockets", "switch"],
   ["detached", "switch"],
   ["all", "switch"],
+  ["&push", "switch"],
+  ["all-branches", "switch"],
   ["no-commit", "switch"],
+  ["force", "switch"],
   ["overall", "switch"],
   ["current-year", "switch"],
   ["current-month", "switch"],
@@ -57,8 +62,13 @@ var SHORT = {
 };
 
 // src/components/args/args.utils.ts
+var assertAllowedFlags = (flags, allowed, command) => {
+  const extra = [...flags.keys()].find((key) => !allowed.includes(key));
+  if (extra !== undefined)
+    throw new Error(`${spelling(extra)} is not supported by gith ${command}.`);
+};
 function resolveFlag(token) {
-  const match = /^(--?)([a-z][a-z-]*)$/.exec(token);
+  const match = /^(--?)([a-z][a-z-]*|&push)$/.exec(token);
   if (!match)
     return;
   const word = match[2] ?? "";
@@ -93,8 +103,6 @@ function parseFlags(argv) {
       if (hasNext) {
         flags.set(name, next);
         i++;
-      } else if (kind === "optional") {
-        flags.set(name, "");
       } else {
         throw new Error(`${token} needs a value.`);
       }
@@ -166,7 +174,7 @@ function capture(args) {
   return run(args.split(" "));
 }
 function hasOnOrigin(branch) {
-  return capture(`ls-remote --heads origin ${branch}`) !== "";
+  return captureArgs(["ls-remote", "--heads", "origin", `refs/heads/${branch}`]) !== "";
 }
 function isAncestor(ancestor, descendant) {
   try {
@@ -443,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";
@@ -488,20 +496,6 @@ async function confirm(question) {
     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.");
@@ -612,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([
@@ -648,31 +652,86 @@ 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) {
+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]");
+    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",
+    "main",
+    "release",
+    "hotfix",
+    "current-release",
+    "current-hotfix"
+  ], "merge");
   if (flags.size === 0)
     return mergePick();
   const kind = onlyOne(flags, [
@@ -818,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)
@@ -834,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);
 }
@@ -892,15 +951,109 @@ function assertNotPushed() {
     throw new Error("HEAD is already on origin; changing it would need a force-push.");
   }
 }
-function remoteSha(branch) {
-  return captureArgs(["ls-remote", "--heads", "origin", branch]).split("\t")[0] ?? "";
-}
-async function askMessage() {
-  const text = await ask("Commit message: ");
-  if (text === "")
-    throw new Error("a commit needs a message; nothing was committed.");
-  return text;
-}
+
+// src/components/remote/remote.utils.ts
+var getBranches = (flags, command) => {
+  if ([...flags.keys()].some((key) => key !== "all-branches"))
+    throw new Error(`usage: gith ${command} [--all-branches]`);
+  if (!flags.has("all-branches"))
+    return [currentBranch()];
+  const branches = captureArgs([
+    "for-each-ref",
+    "--format=%(refname:strip=2)",
+    "refs/heads/"
+  ]);
+  if (branches === "")
+    throw new Error("No local branches; create a branch and commit before syncing.");
+  return branches.split(`
+`);
+};
+var compareOrigin = (branch) => {
+  gitArgs(["fetch", "--no-tags", "origin", `refs/heads/${branch}`]);
+  const counts = captureArgs([
+    "rev-list",
+    "--left-right",
+    "--count",
+    `refs/heads/${branch}...FETCH_HEAD`
+  ]);
+  if (!/^\d+\s+\d+$/.test(counts))
+    throw new Error("Cannot compare commits with origin; check the repository with git fsck.");
+  const parts = counts.split(/\s+/);
+  const ahead = Number(parts[0]);
+  const behind = Number(parts[1]);
+  process.stdout.write(`${branch} -> origin/${branch}: ahead ${ahead}, behind ${behind}.
+`);
+  return { ahead, behind };
+};
+var updateBranch = (branch, current) => {
+  if (branch === current) {
+    gitArgs(["fetch", "--no-tags", "origin", `refs/heads/${branch}`]);
+    gitArgs(["merge", "--ff-only", "FETCH_HEAD"]);
+  } else {
+    gitArgs([
+      "fetch",
+      "--no-tags",
+      "origin",
+      `refs/heads/${branch}:refs/heads/${branch}`
+    ]);
+  }
+};
+
+// src/components/remote/remote.ts
+var push = (flags) => {
+  const branches = getBranches(flags, "push");
+  for (const branch of branches) {
+    if (isDryRun())
+      continue;
+    if (!hasOnOrigin(branch)) {
+      process.stdout.write(`Publishing ${branch} on origin and setting upstream tracking.
+`);
+      continue;
+    }
+    const { ahead, behind } = compareOrigin(branch);
+    if (behind > 0)
+      throw new Error(ahead > 0 ? `${branch} has diverged; merge or rebase origin's changes, then run gith push. Nothing was pushed.` : `${branch} is behind origin; run gith pull before gith push. Nothing was pushed.`);
+    process.stdout.write(`Pushing ${ahead} commit(s) from ${branch}; ensuring upstream tracking.
+`);
+  }
+  gitArgs([
+    "push",
+    ...flags.has("all-branches") ? ["--atomic"] : [],
+    "-u",
+    "origin",
+    ...branches.map((branch) => `refs/heads/${branch}:refs/heads/${branch}`)
+  ]);
+  if (!isDryRun())
+    process.stdout.write(`Push complete: ${branches.length} branch(es) synced with origin.
+`);
+};
+var pull = (flags) => {
+  const branches = getBranches(flags, "pull");
+  const current = currentBranch();
+  assertCleanTree();
+  const updates = [];
+  for (const branch of branches) {
+    if (isDryRun())
+      continue;
+    if (!hasOnOrigin(branch))
+      throw new Error(`origin/${branch} does not exist; run gith push to publish this branch first.`);
+    const { ahead, behind } = compareOrigin(branch);
+    if (ahead > 0 && behind > 0)
+      throw new Error(`${branch} has diverged; merge or rebase origin's changes explicitly. No commits were changed.`);
+    if (behind > 0)
+      updates.push({ branch, behind });
+    else
+      process.stdout.write(ahead > 0 ? `${branch}: no incoming commits; run gith push to publish ${ahead} local commit(s).
+` : `${branch}: already up to date.
+`);
+  }
+  for (const { branch, behind } of isDryRun() ? branches.map((branch) => ({ branch, behind: 0 })) : updates) {
+    updateBranch(branch, current);
+    if (!isDryRun())
+      process.stdout.write(`Pulled ${behind} commit(s) into ${branch}.
+`);
+  }
+};
 
 // src/components/history/history.ts
 function update(flags) {
@@ -926,43 +1079,33 @@ function undo(flags) {
   assertNotPushed();
   gitArgs(["reset", "--soft", "HEAD~1"]);
 }
-async function save(flags) {
+var save = (flags) => {
   const message = flags.get("message");
-  const extra = [...flags.keys()].filter((key) => key !== "message" && key !== "all");
-  if (extra.length > 0)
-    throw new Error("usage: gith save [-m <message>] [--all]");
-  const branch = currentBranch();
+  const extra = [...flags.keys()].filter((key) => key !== "message" && key !== "all" && key !== "&push");
+  if (extra.length > 0 || message === undefined || message.trim() === "")
+    throw new Error('usage: gith save -m <message> [--all] ["--&push"]');
+  currentBranch();
   const unstaged = captureArgs(["add", "-A", "--dry-run"]).split(`
 `).filter(Boolean);
-  const stageAll = flags.has("all") || unstaged.length === 1 || unstaged.length > 1 && await confirm(`Stage all ${unstaged.length} changes first? [Y/n] `);
+  const stageAll = flags.has("all") || unstaged.length === 1;
   if (stageAll && unstaged.length > 0) {
-    console.log(`Staging ${unstaged.length} unstaged change(s):`);
-    for (const line of unstaged)
-      console.log(`  ${line}`);
+    process.stdout.write(`Staging ${unstaged.length} unstaged change(s):
+${unstaged.join(`
+`)}
+`);
   }
   if (stageAll)
     gitArgs(["add", "-A"]);
-  if (captureArgs(["diff", "--cached", "--name-only"]) === "") {
-    throw new Error("nothing staged; stage the changes to save.");
+  if (captureArgs(["diff", "--cached", "--name-only"]) === "" && !(isDryRun() && stageAll && unstaged.length > 0)) {
+    throw new Error("nothing staged; stage the changes with git add, or use gith save -m <message> --all.");
   }
-  const previous = captureArgs(["rev-parse", "HEAD"]);
-  const amend = hasOwnCommit() && await confirm("Amend the previous commit? [Y/n] ");
-  if (amend) {
-    gitArgs(message ? ["commit", "--amend", "-m", message] : ["commit", "--amend", "--no-edit"]);
-  } else {
-    gitArgs(["commit", "-m", message ?? await askMessage()]);
-  }
-  const rewrites = amend && remoteSha(branch) === previous;
-  const question = rewrites ? `Force-push ${branch} to origin? [Y/n] ` : `Push ${branch} to origin? [Y/n] `;
-  if (!await confirm(question)) {
-    console.log("Saved locally; not pushed.");
-    return;
-  }
-  if (rewrites)
-    gitArgs(["push", "--force-with-lease", "origin", branch]);
-  else
-    gitArgs(["push", "-u", "origin", branch]);
-}
+  gitArgs(["commit", "-m", message]);
+  process.stdout.write(isDryRun() ? `Would save locally.
+` : `Saved locally.
+`);
+  if (flags.has("&push"))
+    push(new Map);
+};
 async function squash(flags) {
   const count = parseLimit(flags);
   const message = flags.get("message");
@@ -1004,37 +1147,70 @@ async function squash(flags) {
   else
     gitArgs(["commit", "-C", oldest]);
 }
-function hasOwnCommit() {
-  for (const base of ["origin/develop", "origin/main"]) {
-    try {
-      return captureArgs(["rev-list", "--count", `${base}..HEAD`]) !== "0";
-    } catch {}
-  }
-  return true;
-}
+
+// src/components/version/version.constants.ts
+var MASCOT = [
+  "        o",
+  "   o    |    o",
+  "    \\   |   /",
+  "     \\  |  /",
+  "      \\ | /",
+  "       \\|/",
+  "        |",
+  "      .---.",
+  "     ( o o )",
+  "      '---'",
+  "        |",
+  "       /|\\",
+  "       / \\"
+];
 
 // src/components/list/list.constants.ts
 var DEFAULT_LIMIT2 = 5;
-var GORLUM = [
-  '      .-"""-.',
-  "     /  o o  \\",
-  "    |   ___   |   my precious pockets!",
-  "     \\ (___) /",
-  "      '-._.-'"
+var GRAPH_ARGS = [
+  "-c",
+  "log.graphColors=cyan,magenta,blue,yellow,green,red",
+  "log",
+  "--graph",
+  "--topo-order",
+  "--decorate=short",
+  "--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"
 ];
 
 // src/components/list/list.utils.ts
 function yesNo(value) {
   return value ? "yes" : "no";
 }
-function commits(limit, graph) {
+var commits = (limit, graph) => {
   if (!hasHead()) {
-    console.log("No commits.");
+    process.stdout.write(`No commits.
+`);
     return;
   }
-  const shape = graph ? ["--graph", "--oneline", "--decorate"] : ["--date=short", "--format=%h  %ad  %an  %s"];
-  console.log(captureArgs(["log", `-n${limit}`, ...shape]));
-}
+  if (!graph) {
+    process.stdout.write(`${captureArgs(["log", `-n${limit}`, "--date=short", "--format=%h  %ad  %an  %s"])}
+`);
+    return;
+  }
+  const { NO_COLOR: noColor, TERM: terminal } = process.env;
+  const color = process.stdout.isTTY && noColor === undefined && terminal !== "dumb";
+  const branch = captureArgs(["rev-parse", "--abbrev-ref", "HEAD"]);
+  process.stdout.write(`
+╭─ COMMIT GRAPH ─────────────────────────────────────────
+│  ${branch} · branch history · limit ${limit}
+│
+`);
+  process.stdout.write(`${captureArgs([
+    ...GRAPH_ARGS,
+    `-n${limit}`,
+    color ? "--color=always" : "--color=never"
+  ])}
+`);
+  process.stdout.write(`╰─ * commit  ·  branches & tags in parentheses  ·  -l <n> shows more
+
+`);
+};
 function hasHead() {
   try {
     captureArgs(["rev-parse", "--verify", "--quiet", "HEAD"]);
@@ -1064,6 +1240,7 @@ function tagPairs(local, origin) {
   });
 }
 function list(flags) {
+  assertAllowedFlags(flags, ["tags", "commits", "stashes", "pockets", "graph", "limit"], "list");
   const kind = onlyOne(flags, ["tags", "commits", "stashes", "pockets"]);
   if (!kind)
     throw new Error("usage: gith list --tags | --commits [--graph] | --stashes | --pockets [-limit <n>]");
@@ -1083,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",
@@ -1095,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);
@@ -1104,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) {
@@ -1196,6 +1377,7 @@ async function switchBranch(flags) {
     switchToCommit(commit);
     return;
   }
+  assertAllowedFlags(flags, ["branch"], "switch");
   const branch = requireBranch(flags, "switch");
   const from = isDetached() ? "HEAD" : undefined;
   const exists = (name) => hasLocal(name) || hasOnOrigin(name);
@@ -1262,6 +1444,16 @@ function detachedOptions(times, current) {
   return options.sort((x, y) => x.name.localeCompare(y.name));
 }
 async function remove(flags) {
+  assertAllowedFlags(flags, [
+    "branch",
+    "local",
+    "remote",
+    "obsolete",
+    "detached",
+    "days",
+    "all",
+    "limit"
+  ], "remove");
   const name = flags.get("branch") ?? "";
   const side = onlyOne(flags, ["local", "remote"]);
   const scope = side ?? "pair";
@@ -1571,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");
@@ -1598,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...
 `);
@@ -1607,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");
@@ -1615,10 +1811,120 @@ 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 existsSync5,
+  mkdirSync,
+  readFileSync as readFileSync3,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import path4 from "node:path";
+
+// src/components/setup/setup.constants.ts
+var HOOKS_DIR = ".githooks";
+var HOOK_FILE = `${HOOKS_DIR}/pre-commit`;
+var HOOKS_PATH_COMMAND = `git config core.hooksPath ${HOOKS_DIR}`;
+var LOCKFILES = [
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"]
+];
+var RUN_PREFIX = {
+  bun: "bun run",
+  pnpm: "pnpm run",
+  yarn: "yarn",
+  npm: "npm run"
+};
+
+// src/components/setup/setup.utils.ts
+import { existsSync as existsSync4 } from "node:fs";
+import path3 from "node:path";
+function checkBlock(manager, script, label) {
+  return `echo "▶ ${label}"
+${RUN_PREFIX[manager]} ${script}
+
+`;
+}
+function buildPreCommitHook(pkg, manager, isTypeScript) {
+  const checks = [
+    isTypeScript || pkg.scripts?.lint ? checkBlock(manager, "lint", "Lint") : "",
+    isTypeScript || pkg.scripts?.typecheck ? checkBlock(manager, "typecheck", "Typecheck") : "",
+    pkg.scripts?.test ? checkBlock(manager, "test", "Test") : ""
+  ].join("");
+  return `#!/usr/bin/env sh
+# Generated by gith setup -n npm - runs on every commit via core.hooksPath
+set -e
+
+${checks}`;
+}
+function detectPackageManager(projectPath) {
+  const lockfile = LOCKFILES.find(([file]) => existsSync4(path3.join(projectPath, file)));
+  return lockfile?.[1] ?? "npm";
+}
+function isTypeScriptProject(projectPath, pkg) {
+  if (existsSync4(path3.join(projectPath, "tsconfig.json")))
+    return true;
+  return Boolean(pkg.dependencies?.typescript || pkg.devDependencies?.typescript);
+}
+function withPrepareScript(pkg) {
+  return { ...pkg, scripts: { ...pkg.scripts, prepare: HOOKS_PATH_COMMAND } };
+}
+
+// src/components/setup/setup.ts
+var SETUP_USAGE = "usage: gith setup -n npm [--force]";
+function setup(flags) {
+  const unknown = [...flags.keys()].filter((key) => key !== "name" && key !== "force");
+  if (unknown.length > 0 || flags.get("name") === undefined) {
+    throw new Error(SETUP_USAGE);
+  }
+  const target = flags.get("name");
+  if (target !== "npm") {
+    throw new Error(`unknown setup '${target}': only npm is supported. ${SETUP_USAGE}`);
+  }
+  setupNpmHook({ force: flags.has("force") });
+}
+function setupNpmHook({ force }) {
+  const root = process.cwd();
+  if (!existsSync5(path4.join(root, ".git"))) {
+    throw new Error("not a git repository root: run it in the folder that holds .git");
+  }
+  const packagePath = path4.join(root, "package.json");
+  if (!existsSync5(packagePath))
+    throw new Error("no package.json in this folder");
+  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"));
+  const manager = detectPackageManager(root);
+  const typescript = isTypeScriptProject(root, pkg);
+  const hook = buildPreCommitHook(pkg, manager, typescript);
+  if (isDryRun()) {
+    console.log(`dry run: would write ${HOOK_FILE} (package manager: ${manager})`);
+    return;
+  }
+  mkdirSync(path4.join(root, HOOKS_DIR), { recursive: true });
+  writeFileSync2(hookPath, hook);
+  try {
+    chmodSync(hookPath, 493);
+  } catch {}
+  gitArgs(["config", "core.hooksPath", HOOKS_DIR]);
+  if (pkg.scripts?.prepare !== HOOKS_PATH_COMMAND) {
+    writeFileSync2(packagePath, `${JSON.stringify(withPrepareScript(pkg), null, 2)}
+`);
+    console.log(`✏️  Added "prepare" → "${HOOKS_PATH_COMMAND}" to package.json`);
+  }
+  console.log(`✅ Wrote ${HOOK_FILE} and set core.hooksPath (package manager: ${manager}${typescript ? ", TypeScript" : ""})`);
 }
 
 // src/components/stash/stash.ts
@@ -1819,6 +2125,7 @@ function table(rows) {
 `);
 }
 function stat(flags) {
+  assertAllowedFlags(flags, [...PERIODS, "limit"], "stat");
   const period = onlyOne(flags, PERIODS) ?? "overall";
   const limit = parseLimit(flags);
   const range = periodRange(period, new Date);
@@ -1878,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) {
@@ -1958,34 +2278,22 @@ function tree(flags) {
 }
 
 // src/components/version/version.ts
-import { readFileSync as readFileSync4 } from "node:fs";
-
-// src/components/version/version.constants.ts
-var MASCOT = [
-  "          o",
-  "         /",
-  "   o----o----o",
-  "    \\   |   /",
-  "     \\  |  /",
-  "      (o_o)",
-  "      /|_|\\",
-  "       d b"
-];
+import { readFileSync as readFileSync5 } from "node:fs";
 
 // src/components/version/version.utils.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
-import path2 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 = path2.dirname(fileURLToPath(import.meta.url));
+  let dir = path5.dirname(fileURLToPath(import.meta.url));
   for (;; ) {
-    const candidate = path2.join(dir, "package.json");
-    if (existsSync3(candidate)) {
-      const pkg = JSON.parse(readFileSync3(candidate, "utf8"));
+    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 = path2.dirname(dir);
+    const parent = path5.dirname(dir);
     if (parent === dir)
       throw new Error("gith package.json not found");
     dir = parent;
@@ -1994,12 +2302,23 @@ function packageJsonPath() {
 
 // src/components/version/version.ts
 function readVersion() {
-  const pkg = JSON.parse(readFileSync4(packageJsonPath(), "utf8"));
+  const pkg = JSON.parse(readFileSync5(packageJsonPath(), "utf8"));
   return pkg.version ?? "unknown";
 }
 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(`
 `);
 }
@@ -2011,24 +2330,26 @@ Start and finish work
   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 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)
-  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 switch --release | --hotfix   switch to the newest release/* or hotfix/* (local or origin); -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 --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 --release | --hotfix    merge into the only matching container, or pick one
+  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)
-  gith save [-m <msg>] [--all]       commit staged changes locally; stages unstaged changes first (one silently, several after asking; --all without asking), then asks to amend the previous commit (else asks for a message), then asks to push, or to force-push after an amend
+  gith save -m <msg> [--all] ["--&push"]  new commit without prompts; push only with "--&push"
   gith squash -limit <n> [-m <msg>]  combine the last n commits into one (keeps the oldest message)
 
 Save and reset work
@@ -2051,24 +2372,27 @@ 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 list --commits [--graph] [-l <n>]   newest commits on this branch (default 5)
+  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>]
                                      newest commits on this branch matching every filter (default 5)
-  gith stat [period] [-limit <n>]    fun facts about this branch: biggest commit, busiest day, streaks
-                                     period: --overall (default), --current-year|-month|-week, --last-year|-month|-week
+  gith stat [--overall | --current-year | --current-month | --current-week | --last-year | --last-month | --last-week] [-limit <n>]
+                                     fun facts about this branch: biggest commit, busiest day, streaks
 
 Remote and health
+  gith push [--all-branches]         push to origin, set tracking, report ahead/behind; never force
+  gith pull [--all-branches]         fast-forward from origin; refuse diverged histories
   gith sync                          fetch all remotes and tags, prune stale refs, then sync this branch with origin both ways
   gith sync --develop | --main       the same for develop or main
   gith sync develop:develop          two-way sync of one branch with origin: fetch it when behind, push it when ahead, stop when diverged
   gith open                          open origin in the browser
   gith doctor                        check the repo is ready for the branch flow (exit 1 on failures)
   gith changelog [--dry-run]         add an entry for package.json's version to CHANGELOG.md (commits since the last tag)
+  gith setup -n npm [--force]        write a shared pre-commit hook (lint, typecheck, test) for an npm project; --force overwrites it
 
 Help
   gith help                          show this help
@@ -2077,10 +2401,13 @@ Help
   --dry-run                          (any command) print the git commands that would run, without running them
   --yes                              (any command) answer yes to every question (for scripts)
 
-Flags: a single dash always takes a value, a double dash never does.
-  -b -r -h -l -m -n -limit -message -name -release -hotfix -branch   take a value, e.g. -limit 10
-  --patch --minor --major --local --remote --obsolete --detached --tags --commits --graph --stashes --pockets   switches
-  --branch --release --hotfix alone pick automatically (picker, latest tag)
+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`;
 var args = process.argv.slice(2).filter((arg) => {
   if (arg === "--verbose")
@@ -2137,7 +2464,13 @@ try {
       undo(parseFlags(rest));
       break;
     case "save":
-      await save(parseFlags(rest));
+      save(parseFlags(rest));
+      break;
+    case "push":
+      push(parseFlags(rest));
+      break;
+    case "pull":
+      pull(parseFlags(rest));
       break;
     case "squash":
       await squash(parseFlags(rest));
@@ -2161,6 +2494,9 @@ try {
     case "changelog":
       changelog(parseFlags(rest));
       break;
+    case "setup":
+      setup(parseFlags(rest));
+      break;
     case "doctor":
       if (!doctor(parseFlags(rest)))
         exit(1);
@@ -2173,10 +2509,11 @@ try {
       break;
     case "release": {
       const flags = parseFlags(rest);
+      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.3.3",
+  "version": "0.5.0",
   "description": "Git helper: branch flow with goal branches, release and hotfix containers, and everyday git commands.",
   "type": "module",
   "bin": {
@@ -19,10 +19,10 @@
     "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",
-    "version": "bun run build && node bin/gith.js changelog"
+    "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",
   "author": "Vitalii Balabanov",