@tertium/gith 0.3.2 → 0.4.0

package/README.md

@@ -1,5 +1,7 @@
 # @tertium/gith
 
+gith: git-only branch flow CLI (goal branches, release/hotfix containers, synced merges).
+
 ```
           o
          /
@@ -11,22 +13,11 @@
        d b
 ```
 
-Git helper: the branch flow from [git-convention](https://github.com/Tertiumnon/git-convention) (work branches named develop--<goal>, `release/*` and `hotfix/*` containers, merges that sync both sides with origin), plus everyday git commands: status, switch, update, undo, save, squash, stash, remove, list, tree, sync, clean, reset, open, doctor and stat. Any command takes `--dry-run` to show the git commands it would run. No dependencies beyond git and [Bun](https://bun.com).
-
-> **Very early state (0.1.0).** Commands and flags may change without notice, and the tool has only been run against throwaway test repositories. Check the result with `git log` and `git status` before you push.
-
-## Install
-
-Needs [Node.js](https://nodejs.org) 18 or newer and git on the PATH.
-
-```bash
-npm install -g @tertium/gith
-gith --version
-```
+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).
 
-From a clone of this repository, build the CLI and link it: `bun install`, `bun run build`, `npm link`.
+See [Command design rules](docs/RULES.md) before changing or adding commands and flags.
 
-`bun install` also points git at `.githooks/`, so each commit runs `bun run typecheck`, `bun run format:check` and `bun run lint` first, and a failing check stops it. `bun run format` rewrites files to the formatter's style.
+> **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
 
@@ -35,20 +26,21 @@ From a clone of this repository, build the CLI and link it: `bun install`, `bun
 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 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)
@@ -58,7 +50,7 @@ gith release --major                # npm version major, from develop into main
 
 # Fix history
 gith undo                           # undo the last commit, keep its changes staged (not if pushed)
-gith save [-m "msg"] [--all]         # --all stages every change first; fold staged changes into the last commit, or make a new commit with them if the branch has none yet (asks for a message); pushes if origin differs
+gith 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
@@ -100,13 +92,20 @@ 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 sync                           # fetch all remotes and tags, prune stale refs
+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
 gith open                           # open origin in the browser
 gith doctor                         # check the repo is ready for the branch flow
 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
@@ -117,34 +116,39 @@ 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` |
 | `--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.
@@ -159,7 +163,8 @@ Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `
 - **`status`** prints the branch and how far it is ahead of or behind its origin branch, then counts staged, unstaged, untracked and conflicting files. It changes nothing.
 - **`update`** fetches `origin/develop` and merges it into the current work branch. It needs a clean working tree and refuses containers. If the merge conflicts, it aborts the merge and says so. It does not push.
 - **`undo`** runs `git reset --soft HEAD~1`: the last commit is removed and its changes stay staged. It refuses when HEAD is already on origin, because undoing a pushed commit needs a force-push.
-- **`save`** saves the staged changes. If the branch has commits of its own (commits origin's `develop`, or `main`, lacks), it folds them into the last commit with `git commit --amend --no-edit`, keeping its message. `-m` replaces the message. If the branch has no commits of its own, it never touches the base commit: it creates a new commit, asking for its message (an empty answer is refused, and `-m` skips the question). It refuses with nothing staged. It pushes only when origin already has this branch and its copy differs from the new commit: a plain `git push origin <branch>` when the commit only moves forward, or, when a pushed commit was rewritten, a `Save it and force-push ...? [Y/n]` question (Enter means yes; a no changes nothing) followed by `git push --force-with-lease origin <branch>`, which refuses if origin moved since your last fetch. If origin has no such branch, the save stays local. The questions need a terminal, so a script cannot force-push or commit by accident.
+- **`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.
@@ -176,12 +181,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`.
-- **`sync <branch>:<branch>`** (for example `sync develop:develop`) syncs one branch with origin in both directions. 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.
+- **`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.
 
@@ -202,7 +208,7 @@ 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`.
+- **`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`.
 
 Both need a clean working tree and a `package.json` with a version, because they call `npm version`.
 
@@ -210,20 +216,6 @@ Both need a clean working tree and a `package.json` with a version, because they
 
 Each failure exits with code 1 and a message. Conflicts leave you on the work branch with the merge aborted, so you can resolve and retry.
 
-## Development
-
-```bash
-bun install
-bun run test        # unit tests
-bun run lint        # biome check
-bun run lint:fix    # biome check --write
-bun run typecheck   # tsc --noEmit
-```
-
-## Publishing
-
-The package ships one built file, `bin/gith.js`, which runs on Node. `npm pack --dry-run` lists what would be published. `prepublishOnly` runs lint, typecheck, the tests and the build before any publish. `.github/workflows/publish.yml` runs the same checks, then `npm publish --access public`, whenever a `v*` tag is pushed. It uses npm trusted publishing (OIDC), so no npm token is stored in the repo. Bump the version with `gith release` or `npm version`, which creates the tag.
-
 ## Support
 
 If this project is useful to you, you can support its development on [Ko-fi](https://ko-fi.com/tertiumnon).

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"],
@@ -33,7 +33,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 +60,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 +101,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 +172,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 {
@@ -474,8 +480,10 @@ async function confirm(question) {
     console.log(`dry run: would ask: ${question}`);
     return true;
   }
-  if (assumeYes)
+  if (assumeYes) {
+    console.log(`${question}yes (--yes)`);
     return true;
+  }
   if (!process.stdin.isTTY)
     throw new Error("this needs a terminal to confirm; pass --yes to skip the question.");
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -486,20 +494,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.");
@@ -658,9 +652,10 @@ function open(kind, version) {
 
 // src/components/flow/flow.ts
 function create(flags) {
+  assertAllowedFlags(flags, ["branch", "release", "hotfix"], "create");
   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");
   const value = flags.get(kind) ?? "";
   if (kind === "branch") {
     if (!value)
@@ -671,6 +666,14 @@ function create(flags) {
   open(kind, value || nextContainerVersion(kind));
 }
 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, [
@@ -890,15 +893,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) {
@@ -924,50 +1021,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();
-  if (flags.has("all"))
-    gitArgs(["add", "-A"]);
-  if (captureArgs(["diff", "--cached", "--name-only"]) === "") {
-    throw new Error("nothing staged; stage the changes to add to the last commit.");
-  }
-  const owned = hasOwnCommit();
-  const pushed = captureArgs(["branch", "-r", "--contains", "HEAD"]) !== "";
-  const rewrite = owned && pushed;
-  const remote = remoteSha(branch);
-  if (rewrite && remote === "") {
-    throw new Error("HEAD is already on origin under another branch; changing it would need a force-push.");
-  }
-  if (rewrite) {
-    const yes = await confirm(`HEAD is already on origin/${branch}. Save it and force-push ${branch}? [Y/n] `);
-    if (!yes) {
-      console.log("save cancelled; nothing changed.");
-      return;
-    }
-  }
-  if (owned) {
-    gitArgs(message ? ["commit", "--amend", "-m", message] : ["commit", "--amend", "--no-edit"]);
-  } else {
-    const text = message ?? await askMessage();
-    gitArgs(["commit", "-m", text]);
-  }
-  if (remote === "") {
-    console.log(`origin has no ${branch}; not pushed.`);
-    return;
+  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;
+  if (stageAll && unstaged.length > 0) {
+    process.stdout.write(`Staging ${unstaged.length} unstaged change(s):
+${unstaged.join(`
+`)}
+`);
   }
-  if (!isDryRun() && captureArgs(["rev-parse", "HEAD"]) === remote) {
-    console.log("origin already has this commit; not pushed.");
-    return;
+  if (stageAll)
+    gitArgs(["add", "-A"]);
+  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.");
   }
-  if (rewrite)
-    gitArgs(["push", "--force-with-lease", "origin", branch]);
-  else
-    gitArgs(["push", "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");
@@ -1009,17 +1089,19 @@ 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/list/list.constants.ts
 var DEFAULT_LIMIT2 = 5;
+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"
+];
 var GORLUM = [
   '      .-"""-.',
   "     /  o o  \\",
@@ -1032,14 +1114,35 @@ var GORLUM = [
 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"]);
@@ -1069,6 +1172,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>]");
@@ -1201,6 +1305,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);
@@ -1267,6 +1372,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";
@@ -1299,15 +1414,25 @@ async function remove(flags) {
   await removeBranches(scope, await pick(scope, parseLimit(flags)));
 }
 function sync(flags) {
-  noFlags2(flags, "sync");
-  gitArgs(["fetch", "--all", "--tags", "--prune"]);
+  const kind = onlyOne(flags, ["develop", "main"]);
+  const extra = [...flags.keys()].filter((key) => key !== kind);
+  if (extra.length > 0)
+    throw new Error("usage: gith sync [--develop | --main]");
+  const name = kind ?? currentBranch2();
+  if (name === "HEAD")
+    throw new Error("HEAD is detached; check out a branch, or use gith sync --develop | --main.");
+  syncWithOrigin(name);
 }
 function syncBranch(args) {
   const [spec = ""] = args;
   const [name = "", other = name] = spec.split(":");
   if (args.length !== 1 || other !== name || name === "")
     throw new Error("usage: gith sync <branch>:<branch>, the same name on both sides.");
+  syncWithOrigin(name);
+}
+function syncWithOrigin(name) {
   assertBranchName(name);
+  gitArgs(["fetch", "--all", "--tags", "--prune"]);
   const local = hasLocal(name);
   const remote = hasOnOrigin(name);
   if (!local && !remote)
@@ -1316,7 +1441,6 @@ function syncBranch(args) {
     gitArgs(["push", "origin", `${name}:${name}`]);
     return;
   }
-  gitArgs(["fetch", "origin", name]);
   if (!local) {
     gitArgs(["fetch", "origin", `${name}:${name}`]);
     return;
@@ -1617,6 +1741,115 @@ function releaseFromDevelop(kind) {
 `);
 }
 
+// src/components/setup/setup.ts
+import {
+  chmodSync,
+  existsSync as existsSync4,
+  mkdirSync,
+  readFileSync as readFileSync3,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import path3 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 existsSync3 } from "node:fs";
+import path2 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]) => existsSync3(path2.join(projectPath, file)));
+  return lockfile?.[1] ?? "npm";
+}
+function isTypeScriptProject(projectPath, pkg) {
+  if (existsSync3(path2.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 (!existsSync4(path3.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))
+    throw new Error("no package.json in this folder");
+  const hookPath = path3.join(root, HOOK_FILE);
+  if (existsSync4(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(path3.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
 function stash(flags) {
   const name = flags.get("name");
@@ -1815,6 +2048,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);
@@ -1954,7 +2188,7 @@ function tree(flags) {
 }
 
 // src/components/version/version.ts
-import { readFileSync as readFileSync4 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 
 // src/components/version/version.constants.ts
 var MASCOT = [
@@ -1969,19 +2203,19 @@ var MASCOT = [
 ];
 
 // src/components/version/version.utils.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
-import path2 from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "node:fs";
+import path4 from "node:path";
 import { fileURLToPath } from "node:url";
 function packageJsonPath() {
-  let dir = path2.dirname(fileURLToPath(import.meta.url));
+  let dir = path4.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 = path4.join(dir, "package.json");
+    if (existsSync5(candidate)) {
+      const pkg = JSON.parse(readFileSync4(candidate, "utf8"));
       if (pkg.name === "@tertium/gith")
         return candidate;
     }
-    const parent = path2.dirname(dir);
+    const parent = path4.dirname(dir);
     if (parent === dir)
       throw new Error("gith package.json not found");
     dir = parent;
@@ -1990,7 +2224,7 @@ 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() {
@@ -2007,24 +2241,25 @@ 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 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
 
 Fix history
   gith undo                          undo the last commit, keep its changes staged (not if pushed)
-  gith save [-m <msg>] [--all]       fold staged changes (--all stages every change first) into the last commit, or commit them if the branch has none yet (asks for a message); pushes if origin differs (asks before a force-push)
+  gith 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
@@ -2048,22 +2283,26 @@ Clean up branches (every removal shows what it will remove first)
 
 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 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 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 sync                          fetch all remotes and tags, prune stale refs
+  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
@@ -2072,10 +2311,12 @@ 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
+  --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")
@@ -2132,7 +2373,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));
@@ -2156,6 +2403,9 @@ try {
     case "changelog":
       changelog(parseFlags(rest));
       break;
+    case "setup":
+      setup(parseFlags(rest));
+      break;
     case "doctor":
       if (!doctor(parseFlags(rest)))
         exit(1);
@@ -2168,6 +2418,7 @@ try {
       break;
     case "release": {
       const flags = parseFlags(rest);
+      assertAllowedFlags(flags, ["patch", "minor", "major"], "release");
       const kind = onlyOne(flags, ["patch", "minor", "major"]);
       if (!kind)
         throw new Error("usage: gith release --patch | --minor | --major");

package/package.json

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