@tertium/gith 0.3.1 → 0.3.2

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,4 @@
-# gith
+# @tertium/gith
 
 ```
           o
@@ -101,6 +101,7 @@ gith stat --last-week -limit 50     # the same for last week, looking at no more
 
 # Remote and health
 gith sync                           # fetch all remotes and tags, prune stale refs
+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
@@ -177,6 +178,7 @@ Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `
 - **`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.
 - **`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.
@@ -221,3 +223,7 @@ 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

@@ -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(`
 `);
@@ -1294,6 +1302,39 @@ function sync(flags) {
   noFlags2(flags, "sync");
   gitArgs(["fetch", "--all", "--tags", "--prune"]);
 }
+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.");
+  assertBranchName(name);
+  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;
+  }
+  gitArgs(["fetch", "origin", name]);
+  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");
   const changes = captureArgs(["status", "--short"]).split(`
@@ -2019,6 +2060,7 @@ Look at the repo
 
 Remote and health
   gith sync                          fetch all remotes and tags, prune stale refs
+  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 +2110,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.2",
   "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",