@tertium/gith 0.3.0 → 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
@@ -11,7 +11,7 @@
        d b
 ```
 
-Git helper: the branch flow from [git-convention](https://github.com/Tertiumnon/git-convention) (goal-named work branches, `release/*` and `hotfix/*` containers, merges that sync both sides with origin), plus everyday git commands: status, switch, update, undo, save, squash, stash, remove, list, tree, sync, clean, reset, open, doctor and stat. Any command takes `--dry-run` to show the git commands it would run. No dependencies beyond git and [Bun](https://bun.com).
+Git helper: the branch flow from [git-convention](https://github.com/Tertiumnon/git-convention) (work branches named develop--<goal>, `release/*` and `hotfix/*` containers, merges that sync both sides with origin), plus everyday git commands: status, switch, update, undo, save, squash, stash, remove, list, tree, 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.
 
@@ -26,17 +26,19 @@ 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
 # Start and finish work
-gith create -b login-redirect       # work branch from develop, named by its goal; stays on the current branch
+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 switch                         # list local and origin branches, and switch to the one you pick
-gith switch -b login-redirect       # switch to the branch, creating it from develop if it is missing
+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
@@ -45,7 +47,8 @@ gith merge                          # 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 -r 1.2.0                 # this branch into release/1.2.0
+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 -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)
@@ -55,7 +58,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"]                # 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]         # --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 squash -limit 3 [-m "msg"]     # combine the last 3 commits into one (keeps the oldest message)
 
 # Save and reset work
@@ -98,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
@@ -120,9 +124,12 @@ One rule applies to every command: **a single dash always takes a value, and a d
 | `-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` |
+| `--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` |
@@ -145,7 +152,7 @@ Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `
 
 ## Git commands
 
-- **`switch -b`** switches to a branch. If the branch exists neither locally nor on origin, it is created first, the same way as `create -b`, and then checked out.
+- **`switch -b`** switches to a branch. If a branch with that name exists (locally or on origin), it is checked out. Otherwise, if `develop--<name>` exists, that one is checked out. If neither exists, `develop--<name>` is created from `origin/develop`, the same way as `create -b`, and checked out.
 - **`switch -commit <sha>`** detaches HEAD at that commit so you can look at old code. It refuses a commit that does not exist, and it refuses while tracked files have changes (untracked files do not block it). It lists the files that block it, and points to `gith stash`. On a detached HEAD, `gith switch -b <name>` creates the branch at the current commit, so commits made there stay on it. It does not create or switch branches for other commits, so commits made on a detached HEAD are easy to lose: name a branch before you leave.
 - **`remove -b <branch>`** removes the branch on both sides: the local branch first (with `git branch -d`, so git refuses to delete an unmerged branch), then the origin branch. A side that does not exist is skipped, so a branch that lives only here is still removed. A name that exists in neither place is an error. `--local` touches only this clone; `--remote` touches only origin. Containers (`develop`, `main`, `release/*`, `hotfix/*`) are refused.
 - **`remove`** with no name opens the list of branches and asks which to remove, the same as `remove --branch`. By default it lists branch pairs, meaning branches that exist both here and on origin. `--local` lists local branches and `--remote` lists origin branches. Each choice is removed on the same sides as above. `-limit <n>` shows only the first `n` (all by default), and the picker numbers only those. Pick with the arrow keys: up and down move, space checks an item, enter confirms the checked items, and esc cancels. `switch` takes one item with enter. The list needs a terminal, and that is checked before anything is listed. The checked-out branch and containers are never listed. Choosing items is the confirmation, so nothing else is asked. If a delete fails (for example, an unmerged branch), the removal stops there and earlier picks stay deleted.
@@ -171,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.
@@ -179,7 +187,7 @@ Commands that choose between flags (for example `create -b`, `-r` and `-h`, or `
 
 ## What it does
 
-- **`create -b`** creates the branch from `origin/develop`, pushes it with upstream tracking, and leaves the current branch checked out. It does not touch the working tree, so it works with uncommitted changes.
+- **`create -b`** creates `develop--<name>` from `origin/develop`, pushes it with upstream tracking, and leaves the current branch checked out. The prefix shows the source branch; `create -b develop` and `create -b main` are refused. It does not touch the working tree, so it works with uncommitted changes.
 - **`create -r` / `create -h`** creates a container from its base (`develop` for release, `main` for hotfix), refusing names that already exist on origin. Like `create -b`, it does not switch.
 - **With `--release` or `--hotfix` (no value)**, the version is worked out from the highest `vX.Y.Z` tag across local tags and origin: `-r` takes the next minor (`1.2.1` → `1.3.0`), `-h` takes the next patch (`1.2.1` → `1.2.2`). With no tags yet, the first release is `0.1.0` and the first hotfix `0.0.1`. The version is printed before the branch is created.
 - **`merge --current-release`** and **`--current-hotfix`** pick the newest `release/*` or `hotfix/*` branch by version (numbers compare as numbers, so `1.10.0` beats `1.9.0`), checking both local branches and origin, and merge into it. The target must exist on origin, because the merge pushes it; a newest branch that only exists here stops the command with a message.
@@ -215,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

@@ -6,8 +6,8 @@ import { exit } from "node:process";
 // src/components/args/args.constants.ts
 var SPECS = new Map([
   ["branch", "auto"],
-  ["release", "auto"],
-  ["hotfix", "auto"],
+  ["release", "optional"],
+  ["hotfix", "optional"],
   ["limit", "value"],
   ["message", "value"],
   ["name", "value"],
@@ -29,6 +29,7 @@ var SPECS = new Map([
   ["current-release", "switch"],
   ["current-hotfix", "switch"],
   ["develop", "switch"],
+  ["main", "switch"],
   ["pockets", "switch"],
   ["detached", "switch"],
   ["all", "switch"],
@@ -89,10 +90,14 @@ function parseFlags(argv) {
     if (style === "single") {
       if (kind === "switch")
         throw new Error(`${token} is a switch; write --${name}.`);
-      if (!hasNext)
+      if (hasNext) {
+        flags.set(name, next);
+        i++;
+      } else if (kind === "optional") {
+        flags.set(name, "");
+      } else {
         throw new Error(`${token} needs a value.`);
-      flags.set(name, next);
-      i++;
+      }
     } else if (kind === "switch") {
       flags.set(name, "true");
     } else if (kind === "value") {
@@ -163,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(`
 `);
@@ -548,7 +561,7 @@ async function select(question, options, multi) {
 
 // src/components/rules/rules.constants.ts
 var CONTAINER = /^(develop|main|release\/.+|hotfix\/.+)$/;
-var TARGET = /^(develop|release\/.+|hotfix\/.+)$/;
+var TARGET = /^(main|develop|release\/.+|hotfix\/.+)$/;
 
 // src/components/rules/rules.ts
 function isContainer(name) {
@@ -597,7 +610,7 @@ function nextVersion(tags, bump) {
 }
 
 // src/components/flow/flow.utils.ts
-function newestContainer(kind) {
+function containers(kind) {
   const prefix = `${kind}/`;
   const local = captureArgs([
     "for-each-ref",
@@ -608,15 +621,19 @@ function newestContainer(kind) {
   const origin = captureArgs(["ls-remote", "--heads", "origin"]).split(`
 `).map((line) => (line.split("\t")[1] ?? "").replace(/^refs\/heads\//, ""));
   const candidates = new Set([...local, ...origin].filter((name) => name.startsWith(prefix)));
-  let newest;
+  const versioned = [];
   for (const name of candidates) {
     const version = parseSemver(name.slice(prefix.length));
-    if (version && (!newest || compare(version, newest.version) > 0))
-      newest = { name, version };
+    if (version)
+      versioned.push({ name, version });
   }
+  return versioned.sort((a, b) => compare(b.version, a.version)).map((item) => item.name);
+}
+function newestContainer(kind) {
+  const [newest] = containers(kind);
   if (!newest)
     throw new Error(`no ${kind} branch exists, locally or on origin.`);
-  return newest.name;
+  return newest;
 }
 function nextContainerVersion(kind) {
   const bump = kind === "release" ? "minor" : "patch";
@@ -658,6 +675,7 @@ async function merge(flags) {
     return mergePick();
   const kind = onlyOne(flags, [
     "develop",
+    "main",
     "release",
     "hotfix",
     "current-release",
@@ -666,31 +684,50 @@ async function merge(flags) {
   let target = "develop";
   if (kind === "develop")
     target = "develop";
+  else if (kind === "main")
+    target = "main";
   else if (kind === "current-release")
     target = newestContainer("release");
   else if (kind === "current-hotfix")
     target = newestContainer("hotfix");
   else if (kind) {
     const version = flags.get(kind) ?? "";
-    if (!version) {
-      throw new Error(`usage: gith merge -${kind === "release" ? "r" : "h"} <version>`);
-    }
-    target = containerName(kind, version);
+    const picked = version === "" ? await pickContainer(kind) : containerName(kind, version);
+    if (picked === undefined)
+      return;
+    target = picked;
   }
   await mergeInto(target);
 }
+async function pickContainer(kind) {
+  const names = containers(kind);
+  if (names.length === 0)
+    throw new Error(`no ${kind} branch exists, locally or on origin.`);
+  if (names.length === 1)
+    return names[0];
+  if (!process.stdin.isTTY) {
+    throw new Error(`several ${kind} branches exist; pass -${kind === "release" ? "r" : "h"} <version> instead; the list needs a terminal`);
+  }
+  const [picked] = await select(`Merge into which ${kind}?`, names.map((name) => ({ name, label: name })), false);
+  return picked;
+}
+function workBranchName(goal, from) {
+  return from === undefined ? `develop--${goal}` : goal;
+}
 function createBranch(goal, from) {
   if (isContainer(goal))
     throw new Error(`'${goal}' is a container name; pick a goal.`);
-  if (hasOnOrigin(goal))
-    throw new Error(`'${goal}' already exists on origin.`);
+  const name = workBranchName(goal, from);
+  if (hasOnOrigin(name))
+    throw new Error(`'${name}' already exists on origin.`);
   if (from === undefined) {
     gitArgs(["fetch", "origin", "develop"]);
-    gitArgs(["branch", goal, "origin/develop"]);
+    gitArgs(["branch", name, "origin/develop"]);
   } else {
-    gitArgs(["branch", goal, from]);
+    gitArgs(["branch", name, from]);
   }
-  gitArgs(["push", "-u", "origin", goal]);
+  gitArgs(["push", "-u", "origin", name]);
+  return name;
 }
 async function mergeInto(target, from) {
   if (!isTarget(target))
@@ -889,10 +926,12 @@ function undo(flags) {
 }
 async function save(flags) {
   const message = flags.get("message");
-  const extra = [...flags.keys()].filter((key) => key !== "message");
+  const extra = [...flags.keys()].filter((key) => key !== "message" && key !== "all");
   if (extra.length > 0)
-    throw new Error("usage: gith save [-m <message>]");
+    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.");
   }
@@ -1163,10 +1202,14 @@ async function switchBranch(flags) {
     return;
   }
   const branch = requireBranch(flags, "switch");
-  if (!hasLocal(branch) && !hasOnOrigin(branch)) {
-    createBranch(branch, isDetached() ? "HEAD" : undefined);
+  const from = isDetached() ? "HEAD" : undefined;
+  const exists = (name) => hasLocal(name) || hasOnOrigin(name);
+  let name = branch;
+  if (!exists(branch)) {
+    const made = workBranchName(branch, from);
+    name = exists(made) ? made : createBranch(branch, from);
   }
-  gitArgs(["switch", "--", branch]);
+  gitArgs(["switch", "--", name]);
 }
 function candidates(scope, local, remote, current) {
   const notContainer = (name) => !isContainer(name);
@@ -1259,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(`
@@ -1928,26 +2004,27 @@ function versionText() {
 var USAGE = `gith - git helper: branch flow and everyday git commands
 
 Start and finish work
-  gith create -b <branch>            work branch from develop, named by its goal (no switch)
+  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 switch                        list local and origin branches, and switch to the one picked
-  gith switch -b <branch>            switch to a branch, creating it from develop if missing (on a detached HEAD: from that commit)
+  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 <v> / -h <v> for one version
+  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 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                         pick the branch to merge, then the target (develop, release/*, hotfix/*)
-  gith merge [-r <v> | -h <v>]       merge this branch into develop, release/<v> or hotfix/<v>
+  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 --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>]               fold staged changes 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]       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 squash -limit <n> [-m <msg>]  combine the last n commits into one (keeps the oldest message)
 
 Save and reset work
@@ -1983,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)
@@ -2032,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.0",
+  "version": "0.3.2",
   "description": "Git helper: branch flow with goal branches, release and hotfix containers, and everyday git commands.",
   "type": "module",
   "bin": {
@@ -15,13 +15,16 @@
     "test": "bun test --no-coverage",
     "lint": "biome check src",
     "lint:fix": "biome check --write src",
+    "format": "biome format --write src",
+    "format:check": "biome format src",
     "typecheck": "tsc --noEmit",
+    "prepare": "git config core.hooksPath .githooks || true",
     "release:patch": "node bin/gith.js release --patch",
     "release:minor": "node bin/gith.js release --minor",
     "release:major": "node bin/gith.js release --major",
     "version": "bun run build && node bin/gith.js changelog"
   },
-  "license": "ISC",
+  "license": "MIT",
   "author": "Vitalii Balabanov",
   "repository": {
     "type": "git",