gflows 0.1.11 → 0.1.12

package/README.md

@@ -171,7 +171,7 @@ gflows finish hotfix --push               # merge to main, then dev; tag v1.3.1;
 | `delete`     | `-L`  | Delete local workflow branch(es). Never main/dev.                         |
 | `list`       | `-l`  | List workflow branches; optional type filter and remote.                  |
 | `bump`       | —     | Bump or rollback package version (patch/minor/major).                     |
-| `completion` | —     | Print shell completion script (bash | zsh | fish).                        |
+| `completion` | —     | Print shell completion script (bash/zsh/fish).                            |
 | `status`     | `-t`  | Show current branch, type, base, merge target(s), ahead/behind.           |
 | `help`       | `-h`  | Show usage and quick reference.                                           |
 | `version`    | `-V`  | Show version.                                                             |
@@ -179,13 +179,30 @@ gflows finish hotfix --push               # merge to main, then dev; tag v1.3.1;
 
 **Branch types (for start/finish/list):** `feature` (`-f`), `bugfix` (`-b`), `chore` (`-c`), `release` (`-r`), `hotfix` (`-x`), `spike` (`-e`).
 
+**Common flags** (used by multiple commands):
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--path <dir>` | `-C` | Run as if in `<dir>`. |
+| `--dry-run` | `-d` | Log intended actions only; no writes. |
+| `--verbose` | `-v` | Verbose output. |
+| `--quiet` | `-q` | Minimal output. |
+| `--push` | `-p` | Push after init/start/finish. |
+| `--no-push` | `-P` | Do not push. |
+| `--main <name>` | — | Main branch override. |
+| `--dev <name>` | — | Dev branch override. |
+| `--remote <name>` | `-R` | Remote for push. |
+| `--from <branch>` | `-o` | Base branch override (start). |
+| `--branch <name>` | `-B` | Branch name (finish). |
+| `--yes` | `-y` | Skip confirmations. |
+
 ---
 
 ### init
 
 Ensures the **main** branch exists (exits with error if not). Creates **dev** from main if it does not exist; does nothing if dev already exists. Does not rewrite or force-push.
 
-You can set and persist config with `**--main`**, `**--dev**`, and `**-R`/`--remote**`. Any of these flags cause init to write or update `.gflows.json` with the given values (after a successful init; skipped with `--dry-run`).
+You can set and persist config with `**--main`**, `**--dev`**, and `**-R`/`--remote**`. Any of these flags cause init to write or update `.gflows.json` with the given values (after a successful init; skipped with `--dry-run`).
 
 **Examples:**
 
@@ -197,7 +214,18 @@ gflows init -C ../other-repo    # run in another directory
 gflows init --dry-run           # log intended actions only
 ```
 
-**Flags:** `--push`, `--main <name>`, `--dev <name>`, `-R`/`--remote <name>` (main/dev/remote are persisted to `.gflows.json` when provided), `-C`/`--path <dir>`, `--dry-run`, `-v`/`--verbose`, `-q`/`--quiet`.
+**Flags:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--push` | `-p` | Push dev to remote after creating. |
+| `--main <name>` | — | Main branch name (persisted to `.gflows.json` when provided). |
+| `--dev <name>` | — | Dev branch name (persisted to `.gflows.json` when provided). |
+| `--remote <name>` | `-R` | Remote name (persisted to `.gflows.json` when provided). |
+| `--path <dir>` | `-C` | Run as if in `<dir>`. |
+| `--dry-run` | `-d` | Log intended actions only; no writes. |
+| `--verbose` | `-v` | Verbose output. |
+| `--quiet` | `-q` | Minimal output. |
 
 ---
 
@@ -220,7 +248,18 @@ gflows start feature api-v2 --push               # create branch and push to rem
 gflows start chore deps-update -C ./backend      # run in subdirectory
 ```
 
-**Flags:** `--force` (allow dirty working tree), `--push`, `-o`/`--from <branch>` (base override, e.g. `-o main` for bugfix), `-R`/`--remote`, `-C`/`--path`, `--dry-run`, `-v`, `-q`.
+**Flags:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--force` | — | Allow dirty working tree. |
+| `--push` | `-p` | Push new branch to remote after creating. |
+| `--from <branch>` | `-o` | Base branch override (e.g. `-o main` for bugfix). |
+| `--remote <name>` | `-R` | Remote for push. |
+| `--path <dir>` | `-C` | Run as if in `<dir>`. |
+| `--dry-run` | `-d` | Log intended actions only; no writes. |
+| `--verbose` | `-v` | Verbose output. |
+| `--quiet` | `-q` | Minimal output. |
 
 ---
 
@@ -245,7 +284,25 @@ gflows finish -y                           # skip "Delete branch after finish?"
 
 **Branch resolution:** If you omit the branch name, gflows uses the current branch. With `-B` and no value in a TTY, it shows a picker of workflow branches. Without a TTY, you must pass the branch name explicitly.
 
-**Flags:** `-B`/`--branch <name>`, `--no-ff`, `-D`/`--delete` (delete branch after finish), `-N`/`--no-delete`, `--push`, `-s`/`--sign`, `-T`/`--no-tag`, `-M`/`--tag-message`, `-m`/`--message`, `-y`/`--yes`, `-C`, `--dry-run`, `-v`, `-q`.
+**Flags:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--branch <name>` | `-B` | Branch to finish (current branch if omitted; picker in TTY when `-B` with no value). |
+| `--no-ff` | — | Always create a merge commit. |
+| `--delete` | `-D` | Delete branch after finish. |
+| `--no-delete` | `-N` | Do not delete branch after finish. |
+| `--push` | `-p` | Push after merge (finish prompts "Do you want to push?" when neither `-p` nor `-P`). |
+| `--no-push` | `-P` | Do not push. |
+| `--sign` | `-s` | Sign the tag (release/hotfix; GPG). |
+| `--no-tag` | `-T` | Do not create tag (release/hotfix). |
+| `--tag-message <msg>` | `-M` | Tag message. |
+| `--message <msg>` | `-m` | Merge message. |
+| `--yes` | `-y` | Skip confirmations (e.g. "Delete branch after finish?"). |
+| `--path <dir>` | `-C` | Run as if in `<dir>`. |
+| `--dry-run` | `-d` | Log intended actions only; no writes. |
+| `--verbose` | `-v` | Verbose output. |
+| `--quiet` | `-q` | Minimal output. |
 
 ---
 
@@ -261,7 +318,13 @@ gflows switch feature/auth-refactor
 gflows -W feature/auth-refactor    # same with short command
 ```
 
-**Flags:** `-C`/`--path`, `-v`, `-q`.
+**Flags:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--path <dir>` | `-C` | Run as if in `<dir>`. |
+| `--verbose` | `-v` | Verbose output. |
+| `--quiet` | `-q` | Minimal output. |
 
 ---
 
@@ -277,7 +340,13 @@ gflows delete feature/old-spike
 gflows delete feature/one feature/two    # delete multiple
 ```
 
-**Flags:** `-C`/`--path`, `-v`, `-q`.
+**Flags:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--path <dir>` | `-C` | Run as if in `<dir>`. |
+| `--verbose` | `-v` | Verbose output. |
+| `--quiet` | `-q` | Minimal output. |
 
 ---
 
@@ -295,7 +364,15 @@ gflows list -r feature                   # remote + local feature branches
 gflows list --include-remote
 ```
 
-**Flags:** `-r`/`--include-remote`, `-C`/`--path`, `--dry-run`, `-v`, `-q`.
+**Flags:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--include-remote` | `-r` | Include remote-tracking branches (may run `git fetch`). |
+| `--path <dir>` | `-C` | Run as if in `<dir>`. |
+| `--dry-run` | `-d` | Log intended actions only. |
+| `--verbose` | `-v` | Verbose output. |
+| `--quiet` | `-q` | Minimal output. |
 
 ---
 
@@ -317,7 +394,14 @@ gflows bump                              # interactive (direction + type) when T
 gflows bump --dry-run                    # print old → new, no file writes
 ```
 
-**Flags:** `--dry-run`, `-C`/`--path`, `-v`, `-q`.
+**Flags:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--dry-run` | `-d` | Print old → new version only; no file writes. |
+| `--path <dir>` | `-C` | Run as if in `<dir>`. |
+| `--verbose` | `-v` | Verbose output. |
+| `--quiet` | `-q` | Minimal output. |
 
 ---
 
@@ -332,7 +416,13 @@ gflows status
 gflows -t
 ```
 
-**Flags:** `-C`/`--path`, `-v`, `-q`.
+**Flags:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--path <dir>` | `-C` | Run as if in `<dir>`. |
+| `--verbose` | `-v` | Verbose output. |
+| `--quiet` | `-q` | Minimal output. |
 
 ---
 
@@ -386,7 +476,7 @@ Configuration is **optional**. Override branch names, remote, and branch **prefi
 **Resolution order** (later overrides earlier):
 
 1. Built-in defaults (`main`, `dev`, `origin`, and default prefixes).
-2. Repo config file: `**.gflows.json`** in repo root, or `**gflows**` key in `**package.json**`.
+2. Repo config file: `**.gflows.json`** in repo root, or `**gflows`** key in `**package.json**`.
 3. CLI (e.g. `--main`, `--dev`, `-R`/`--remote`).
 
 Only include keys you want to override; the rest stay default. Invalid or malformed config is ignored (with an optional warning when using `-v`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gflows",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "A lightweight CLI for consistent Git branching workflows (main + dev, feature/bugfix/chore/release/hotfix).",
   "license": "MIT",
   "type": "module",

package/src/commands/bump.ts

@@ -210,6 +210,7 @@ export async function run(args: ParsedArgs): Promise<void> {
     const updated = [PACKAGE_JSON];
     if (jsrUpdated) updated.push(JSR_JSON);
     success(`Updated: ${updated.join(", ")}`);
+    // Hint: suggest next step — commit and start release branch
     hint("Commit the change, then run gflows start release vX.Y.Z to release.");
   }
 }

package/src/commands/delete.ts

@@ -80,6 +80,7 @@ export async function run(args: ParsedArgs): Promise<void> {
       }
     }
     if (!quiet && !dryRun) {
+      // Hint: suggest listing remaining branches
       hint("Use gflows list to see remaining workflow branches.");
     }
     return;
@@ -139,6 +140,7 @@ export async function run(args: ParsedArgs): Promise<void> {
     }
   }
   if (!quiet && !dryRun && chosen.length > 0) {
+    // Hint: suggest listing remaining branches
     hint("Use gflows list to see remaining workflow branches.");
   }
 }

package/src/commands/finish.ts

@@ -242,10 +242,21 @@ export async function run(args: ParsedArgs): Promise<void> {
     }
   }
 
-  const doPush = args.push && !args.noPush;
-  const didCreateTag = !!(
+  const createdTagName =
     meta.mergeTarget === "main-then-dev" && meta.tagOnFinish && version && !args.noTag
-  );
+      ? normalizeTagVersion(version)
+      : undefined;
+  const didCreateTag = Boolean(createdTagName);
+
+  let doPush = args.push && !args.noPush;
+  if (!args.push && !args.noPush && isTTY) {
+    const { confirm } = await import("@inquirer/prompts");
+    doPush = await confirm({
+      message: "Do you want to push?",
+      default: true,
+    });
+  }
+
   if (doPush) {
     const remote = args.remote ?? config.remote;
     const refsToPush: string[] = [config.dev];
@@ -271,7 +282,9 @@ export async function run(args: ParsedArgs): Promise<void> {
   }
 
   if (!args.quiet && !args.dryRun) {
-    success(`gflows: finished '${branchToFinish}' into ${meta.mergeTarget}.`);
+    const tagSuffix = createdTagName ? ` (tag ${createdTagName})` : "";
+    success(`gflows: finished '${branchToFinish}' into ${meta.mergeTarget}${tagSuffix}.`);
+    // Hint: suggest next step — create a new workflow branch
     hint("Run gflows start <type> <name> to create a new workflow branch.");
   }
 }

package/src/commands/help.ts

@@ -32,7 +32,7 @@ Types: feature (-f), bugfix (-b), chore (-c), release (-r), hotfix (-x), spike (
 
 Common flags:
   -p, --push           Push after init/start/finish
-  -P, --no-push        Do not push
+  -P, --no-push        Do not push (finish: prompts "Do you want to push?" when neither -p nor -P)
   --main <name>        Main branch (init: persist to .gflows.json)
   --dev <name>         Dev branch (init: persist to .gflows.json)
   -R, --remote <name>  Remote for push (init: persist to .gflows.json)

package/src/commands/init.ts

@@ -102,6 +102,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   }
 
   if (!args.quiet) {
+    // Hint: suggest next step — create first workflow branch
     hint("Run gflows start feature <name> to create a workflow branch.");
   }
 }

package/src/commands/list.ts

@@ -90,8 +90,10 @@ export async function run(args: ParsedArgs): Promise<void> {
 
   if (!quiet && sorted.length === 0) {
     console.error("No workflow branches found.");
+    // Hint: suggest creating first workflow branch
     hint("Run gflows start <type> <name> to create a workflow branch.");
   } else if (!quiet && sorted.length > 0) {
+    // Hint: suggest switching to a listed branch
     hint("Use gflows switch <branch> to switch to a branch.");
   }
 }

package/src/commands/start.ts

@@ -141,6 +141,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   }
 
   if (!args.quiet && !args.dryRun) {
+    // Hint: suggest next step — merge branch when done
     hint(`When done, run gflows finish ${type} to merge into the target branch.`);
   }
 }

package/src/commands/status.ts

@@ -138,6 +138,7 @@ export async function run(args: ParsedArgs): Promise<void> {
 
   if (!quiet) {
     console.log(`Ahead/behind: ${ahead} ahead, ${behind} behind`);
+    // Hint: suggest next step — finish current branch
     hint(`Run gflows finish ${classification} to merge into ${mergeTargetDisplay}.`);
   }
 }

package/src/commands/switch.ts

@@ -65,6 +65,7 @@ export async function run(args: ParsedArgs): Promise<void> {
     });
     if (!quiet && !dryRun) {
       success(`Switched to branch '${branchName}'.`);
+      // Hint: suggest listing branches
       hint("Use gflows list to see all workflow branches.");
     }
     return;
@@ -104,6 +105,7 @@ export async function run(args: ParsedArgs): Promise<void> {
   });
   if (!quiet && !dryRun) {
     success(`Switched to branch '${chosen}'.`);
+    // Hint: suggest listing branches
     hint("Use gflows list to see all workflow branches.");
   }
 }