@tertium/gith 0.3.2 → 0.3.3

package/README.md

@@ -1,5 +1,7 @@
 # @tertium/gith
 
+gith: git-only branch flow CLI (goal branches, release/hotfix containers, synced merges).
+
 ```
           o
          /
@@ -15,19 +17,6 @@ Git helper: the branch flow from [git-convention](https://github.com/Tertiumnon/
 
 > **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
-```
-
-From a clone of this repository, build the CLI and link it: `bun install`, `bun run build`, `npm link`.
-
-`bun install` also points git at `.githooks/`, so each commit runs `bun run typecheck`, `bun run format:check` and `bun run lint` first, and a failing check stops it. `bun run format` rewrites files to the formatter's style.
-
 ## Usage
 
 ```bash
@@ -58,7 +47,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]         # 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 squash -limit 3 [-m "msg"]     # combine the last 3 commits into one (keeps the oldest message)
 
 # Save and reset work
@@ -100,7 +89,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 sync                           # fetch all remotes and tags, prune stale refs
+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
@@ -159,7 +149,7 @@ 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.
+- **`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.
 - **`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.
@@ -177,8 +167,8 @@ Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `
 - **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.
 - **`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.
@@ -210,20 +200,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

@@ -474,8 +474,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 });
@@ -930,43 +932,36 @@ async function save(flags) {
   if (extra.length > 0)
     throw new Error("usage: gith save [-m <message>] [--all]");
   const branch = currentBranch();
-  if (flags.has("all"))
+  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] `);
+  if (stageAll && unstaged.length > 0) {
+    console.log(`Staging ${unstaged.length} unstaged change(s):`);
+    for (const line of unstaged)
+      console.log(`  ${line}`);
+  }
+  if (stageAll)
     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;
-    }
+    throw new Error("nothing staged; stage the changes to save.");
   }
-  if (owned) {
+  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 {
-    const text = message ?? await askMessage();
-    gitArgs(["commit", "-m", text]);
-  }
-  if (remote === "") {
-    console.log(`origin has no ${branch}; not pushed.`);
-    return;
+    gitArgs(["commit", "-m", message ?? await askMessage()]);
   }
-  if (!isDryRun() && captureArgs(["rev-parse", "HEAD"]) === remote) {
-    console.log("origin already has this commit; not pushed.");
+  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 (rewrite)
+  if (rewrites)
     gitArgs(["push", "--force-with-lease", "origin", branch]);
   else
-    gitArgs(["push", "origin", branch]);
+    gitArgs(["push", "-u", "origin", branch]);
 }
 async function squash(flags) {
   const count = parseLimit(flags);
@@ -1299,15 +1294,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 +1321,6 @@ function syncBranch(args) {
     gitArgs(["push", "origin", `${name}:${name}`]);
     return;
   }
-  gitArgs(["fetch", "origin", name]);
   if (!local) {
     gitArgs(["fetch", "origin", `${name}:${name}`]);
     return;
@@ -2024,7 +2028,7 @@ Start and finish work
 
 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]       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 squash -limit <n> [-m <msg>]  combine the last n commits into one (keeps the oldest message)
 
 Save and reset work
@@ -2059,7 +2063,8 @@ Look at the repo
                                      period: --overall (default), --current-year|-month|-week, --last-year|-month|-week
 
 Remote and health
-  gith sync                          fetch all remotes and tags, prune stale refs
+  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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tertium/gith",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Git helper: branch flow with goal branches, release and hotfix containers, and everyday git commands.",
   "type": "module",
   "bin": {