@tertium/gith 0.3.1 → 0.3.3

package/LICENSE

@@ -1,15 +1,21 @@
-ISC License
+MIT License
 
 Copyright (c) 2026 Vitalii Balabanov
 
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,6 @@
-# gith
+# @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,9 @@ 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
 gith changelog --dry-run            # preview the CHANGELOG.md entry for package.json's version
@@ -158,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.
@@ -176,7 +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`** 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.
@@ -208,16 +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
+## Support
 
-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.
+If this project is useful to you, you can support its development on [Ko-fi](https://ko-fi.com/tertiumnon).

package/bin/gith.js

@@ -168,6 +168,14 @@ function capture(args) {
 function hasOnOrigin(branch) {
   return capture(`ls-remote --heads origin ${branch}`) !== "";
 }
+function isAncestor(ancestor, descendant) {
+  try {
+    captureArgs(["merge-base", "--is-ancestor", ancestor, descendant]);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function listTags() {
   const local = capture("tag --list").split(`
 `);
@@ -466,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 });
@@ -922,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]);
+    gitArgs(["commit", "-m", message ?? await askMessage()]);
   }
-  if (remote === "") {
-    console.log(`origin has no ${branch}; 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 (!isDryRun() && captureArgs(["rev-parse", "HEAD"]) === remote) {
-    console.log("origin already has this commit; 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);
@@ -1291,8 +1294,50 @@ async function remove(flags) {
   await removeBranches(scope, await pick(scope, parseLimit(flags)));
 }
 function sync(flags) {
-  noFlags2(flags, "sync");
+  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)
+    throw new Error(`'${name}' does not exist, locally or on origin.`);
+  if (!remote) {
+    gitArgs(["push", "origin", `${name}:${name}`]);
+    return;
+  }
+  if (!local) {
+    gitArgs(["fetch", "origin", `${name}:${name}`]);
+    return;
+  }
+  const here = capture(`rev-parse refs/heads/${name}`);
+  const there = capture(`rev-parse refs/remotes/origin/${name}`);
+  if (here === there) {
+    console.log(`'${name}' is already in sync with origin.`);
+  } else if (isAncestor(there, here)) {
+    gitArgs(["push", "origin", `${name}:${name}`]);
+  } else if (!isAncestor(here, there)) {
+    throw new Error(`'${name}' has diverged from origin/${name}; merge or rebase one side first.`);
+  } else if (currentBranch2() === name) {
+    gitArgs(["merge", "--ff-only", `origin/${name}`]);
+  } else {
+    gitArgs(["fetch", "origin", `${name}:${name}`]);
+  }
 }
 async function reset(flags) {
   noFlags2(flags, "reset");
@@ -1983,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
@@ -2018,7 +2063,9 @@ 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)
   gith changelog [--dry-run]         add an entry for package.json's version to CHANGELOG.md (commits since the last tag)
@@ -2068,7 +2115,10 @@ try {
       await remove(parseFlags(rest));
       break;
     case "sync":
-      sync(parseFlags(rest));
+      if (rest[0] !== undefined && !rest[0].startsWith("-"))
+        syncBranch(rest);
+      else
+        sync(parseFlags(rest));
       break;
     case "clean":
       await clean(parseFlags(rest));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tertium/gith",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Git helper: branch flow with goal branches, release and hotfix containers, and everyday git commands.",
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
     "release:major": "node bin/gith.js release --major",
     "version": "bun run build && node bin/gith.js changelog"
   },
-  "license": "ISC",
+  "license": "MIT",
   "author": "Vitalii Balabanov",
   "repository": {
     "type": "git",