gflows 0.1.14 → 0.1.16

package/README.md

@@ -265,7 +265,7 @@ Release and hotfix names must be a version (`vX.Y.Z` or `X.Y.Z`). Branch names u
 | `init`       | `-I`  | Ensure main exists; create dev from main.                                 |
 | `start`      | `-S`  | Create a workflow branch (requires type + name).                          |
 | `finish`     | `-F`  | Merge branch into target(s), optional tag (release/hotfix), delete, push. |
-| `switch`     | `-W`  | Switch to a workflow branch (picker or name).                             |
+| `switch`     | `-W`  | Switch to a workflow branch (picker or name); with uncommitted changes: prompt or `--move` / `--restore` / `--clean` / `--cancel`. |
 | `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).                     |
@@ -395,24 +395,42 @@ bun gflows finish hotfix -s -T -y
 
 ### switch
 
-Switch to a workflow branch. With TTY and no name, shows a picker; otherwise pass branch name.
+Switch to a workflow branch. With TTY and no branch name, shows a picker; otherwise pass the branch name (e.g. `gflows switch dev` or `-B dev`).
+
+**Uncommitted changes:** If the working tree is dirty and stdin is a TTY, you are prompted to choose:
+
+| Option | Description |
+| ------ | ----------- |
+| **Move** | Move current changes to the target branch. |
+| **Restore** | Save changes for this branch; restore target's saved state (if any). |
+| **Clean** | Discard changes and switch clean at HEAD. |
+| **Cancel** | Abort switching. |
+
+You can skip the prompt by passing exactly one of the flags below. If the target branch has saved changes and you use **Clean**, a warning is shown (unless `-q`).
 
 **Examples:**
 
 ```bash
 bun gflows switch
 bun gflows switch feature/auth-refactor
+bun gflows switch dev --restore
+bun gflows switch main --clean
 bun gflows -W feature/auth-refactor
 ```
 
 **Flags:**
 
 
-| Flag           | Short | Description           |
-| -------------- | ----- | --------------------- |
-| `--path <dir>` | `-C`  | Run as if in `<dir>`. |
-| `--verbose`    | `-v`  | Verbose output.       |
-| `--quiet`      | `-q`  | Minimal output.       |
+| Flag           | Short | Description                                                                 |
+| -------------- | ----- | --------------------------------------------------------------------------- |
+| `--path <dir>` | `-C`  | Run as if in `<dir>`.                                                      |
+| `--branch <name>` | `-B` | Branch to switch to (alternative to positional).                           |
+| `--move`       | —     | Move current changes to the target branch; no prompt.                       |
+| `--restore`    | —     | Save for this branch; restore target's saved state (if any); no prompt.     |
+| `--clean`      | —     | Discard changes and switch clean at HEAD; no prompt.                       |
+| `--cancel`     | —     | Abort switching; no prompt.                                                |
+| `--verbose`    | `-v`  | Verbose output.                                                            |
+| `--quiet`      | `-q`  | Minimal output (suppresses Clean warning about saved changes on target).  |
 
 
 ---

package/package.json

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

package/src/cli.ts

@@ -95,6 +95,11 @@ function buildParseArgsOptions() {
       // list (-r is context-dependent: list → include-remote; start/finish → release)
       includeRemote: { type: "boolean" as const },
       "include-remote": { type: "boolean" as const },
+      // switch: explicit mode (--restore, --clean, --cancel, --move)
+      restore: { type: "boolean" as const },
+      clean: { type: "boolean" as const },
+      cancel: { type: "boolean" as const },
+      move: { type: "boolean" as const },
     },
   };
 }
@@ -312,6 +317,25 @@ export function parse(argv: string[] = Bun.argv.slice(2)): ParsedArgs {
   else if (command === "completion" && name === "zsh") completionShell = "zsh";
   else if (command === "completion" && name === "fish") completionShell = "fish";
 
+  let switchMode: "restore" | "clean" | "cancel" | "move" | undefined;
+  if (command === "switch") {
+    const restore = v.restore === true;
+    const clean = v.clean === true;
+    const cancel = v.cancel === true;
+    const move = v.move === true;
+    const count = [restore, clean, cancel, move].filter(Boolean).length;
+    if (count > 1) {
+      console.error(
+        "gflows switch: only one of --restore, --clean, --cancel, or --move may be used at a time.",
+      );
+      process.exit(EXIT_USER);
+    }
+    if (restore) switchMode = "restore";
+    else if (clean) switchMode = "clean";
+    else if (cancel) switchMode = "cancel";
+    else if (move) switchMode = "move";
+  }
+
   return {
     command,
     cwd,
@@ -342,6 +366,7 @@ export function parse(argv: string[] = Bun.argv.slice(2)): ParsedArgs {
     tagMessage: typeof v.tagMessage === "string" ? v.tagMessage : undefined,
     message: typeof v.message === "string" ? v.message : undefined,
     includeRemote,
+    switchMode,
   };
 }
 

package/src/commands/help.ts

@@ -48,6 +48,10 @@ Start:  --force         Allow dirty working tree
 Finish: --no-ff         Always create merge commit; -D/--delete, -N/--no-delete;
         -s/--sign, -T/--no-tag, -M/--tag-message, -m/--message
 List:   -r, --include-remote   Include remote-tracking branches
+Switch: --move      Move current changes to the target branch
+        --restore   Save for this branch; restore target's saved state (if any)
+        --clean     Discard changes and switch clean at HEAD
+        --cancel    Abort switching
 
 Exit codes: 0 success, 1 usage/validation, 2 Git or system error.
 

package/src/commands/switch.ts

@@ -4,12 +4,30 @@
  */
 
 import { resolveConfig } from "../config.js";
-import { EXIT_OK, EXIT_USER } from "../constants.js";
+import { EXIT_GIT, EXIT_OK, EXIT_USER } from "../constants.js";
 import { NotRepoError } from "../errors.js";
-import { branchList, checkout, resolveRepoRoot } from "../git.js";
+import {
+  branchList,
+  checkout,
+  cleanUntracked,
+  findStashRefByBranch,
+  findStashRefByMessage,
+  getCurrentBranch,
+  isClean,
+  resolveRepoRoot,
+  restoreTracked,
+  STASH_SWITCH_MOVE_SUBSTRING,
+  stashDropRef,
+  stashPopRef,
+  stashPush,
+  stashPushMove,
+} from "../git.js";
 import { hint, success } from "../out.js";
 import type { BranchType, ParsedArgs } from "../types.js";
 
+/** User choice when switching with uncommitted changes. */
+type SwitchWhenUncommitted = "cancel" | "restore" | "clean" | "move";
+
 const BRANCH_TYPES: BranchType[] = ["feature", "bugfix", "chore", "release", "hotfix", "spike"];
 
 /**
@@ -43,58 +61,147 @@ export async function run(args: ParsedArgs): Promise<void> {
   });
 
   const branchName = (branch?.trim() || name?.trim() || "").trim() || undefined;
+  const isTTY = typeof process.stdin.isTTY === "boolean" && process.stdin.isTTY;
+
+  let targetBranch: string;
 
   if (branchName) {
-    await checkout(root, branchName, {
-      dryRun,
-      verbose: args.verbose,
+    targetBranch = branchName;
+  } else {
+    if (!isTTY) {
+      console.error(
+        "gflows switch: no branch name given and stdin is not a TTY. Pass a branch name (e.g. gflows switch feature/my-branch) or run from an interactive terminal.",
+      );
+      process.exit(EXIT_USER);
+    }
+
+    const allLocal = await branchList(root, { dryRun, verbose: args.verbose });
+    const workflowBranches = getWorkflowBranches(allLocal, config.prefixes);
+    const mainAndDev = [config.main, config.dev].filter((b) => allLocal.includes(b));
+    const choices = [...mainAndDev, ...workflowBranches];
+
+    if (choices.length === 0) {
+      if (!quiet) {
+        console.error("No branches found.");
+      }
+      process.exit(EXIT_OK);
+    }
+
+    const { select } = await import("@inquirer/prompts");
+    const chosen = await select({
+      message: "Switch to branch",
+      choices: choices.map((b) => ({ name: b, value: b })),
     });
-    if (!quiet && !dryRun) {
-      success(`Switched to branch '${branchName}'.`);
-      // Hint: suggest listing branches
-      hint("Use gflows list to see all workflow branches.");
+
+    if (typeof chosen !== "string") {
+      process.exit(EXIT_USER);
     }
-    return;
+    targetBranch = chosen;
   }
 
-  const isTTY = typeof process.stdin.isTTY === "boolean" && process.stdin.isTTY;
-  if (!isTTY) {
-    console.error(
-      "gflows switch: no branch name given and stdin is not a TTY. Pass a branch name (e.g. gflows switch feature/my-branch) or run from an interactive terminal.",
-    );
+  const gitOpts = { dryRun, verbose: args.verbose };
+  const treeClean = await isClean(root, gitOpts);
+  /** Only set when tree is dirty (or a mode flag was passed). When tree is clean and no flag, we just checkout. */
+  let whenUncommitted: SwitchWhenUncommitted | undefined;
+
+  if (args.switchMode !== undefined) {
+    whenUncommitted = args.switchMode;
+  } else if (!treeClean && isTTY) {
+    const { select: selectPrompt } = await import("@inquirer/prompts");
+    whenUncommitted = await selectPrompt({
+      message: "Working tree has uncommitted changes. What do you want to do?",
+      choices: [
+        { name: "Move — Move current changes to the target branch", value: "move" as const },
+        {
+          name: "Restore — Save changes for this branch; restore target's saved state (if any)",
+          value: "restore" as const,
+        },
+        { name: "Clean — Discard changes and switch clean at HEAD", value: "clean" as const },
+        { name: "Cancel — Abort switching", value: "cancel" as const },
+      ],
+    });
+  } else if (!treeClean) {
+    whenUncommitted = "cancel";
+  }
+  // When tree is clean and no flag: whenUncommitted stays undefined; we just checkout below.
+
+  if (whenUncommitted === "cancel") {
+    if (!quiet) {
+      console.error("Switch cancelled.");
+    }
     process.exit(EXIT_USER);
   }
 
-  const allLocal = await branchList(root, { dryRun, verbose: args.verbose });
-  const workflowBranches = getWorkflowBranches(allLocal, config.prefixes);
-  // Include main and dev so we always show whatever branches exist
-  const mainAndDev = [config.main, config.dev].filter((b) => allLocal.includes(b));
-  const choices = [...mainAndDev, ...workflowBranches];
+  if (!treeClean && whenUncommitted === "move") {
+    await stashPushMove(root, gitOpts);
+  }
 
-  if (choices.length === 0) {
-    if (!quiet) {
-      console.error("No branches found.");
+  if (!treeClean && whenUncommitted === "restore") {
+    const currentBranch = await getCurrentBranch(root, gitOpts);
+    if (currentBranch) {
+      const existingStashRef = await findStashRefByBranch(root, currentBranch, gitOpts);
+      if (existingStashRef) {
+        await stashDropRef(root, existingStashRef, gitOpts);
+      }
+      await stashPush(root, currentBranch, gitOpts);
     }
-    process.exit(EXIT_OK);
   }
 
-  const { select } = await import("@inquirer/prompts");
-  const chosen = await select({
-    message: "Switch to branch",
-    choices: choices.map((b) => ({ name: b, value: b })),
-  });
+  if (whenUncommitted === "clean") {
+    const targetHasSavedState = await findStashRefByBranch(root, targetBranch, gitOpts);
+    if (targetHasSavedState && !quiet) {
+      console.error(
+        'Warning: This branch has saved changes. Clean will not restore them and will open the branch at its last commit. Use "Restore" if you want to reapply the saved changes.',
+      );
+    }
+    if (!treeClean) {
+      await restoreTracked(root, gitOpts);
+      await cleanUntracked(root, gitOpts);
+    }
+  }
 
-  if (typeof chosen !== "string") {
-    process.exit(EXIT_USER);
+  await checkout(root, targetBranch, gitOpts);
+
+  if (whenUncommitted === "move") {
+    const moveStashRef = await findStashRefByMessage(root, STASH_SWITCH_MOVE_SUBSTRING, gitOpts);
+    if (moveStashRef) {
+      try {
+        await stashPopRef(root, moveStashRef, gitOpts);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(
+          "gflows switch: conflicts occurred while applying your changes on the target branch.",
+        );
+        console.error(
+          "The stash was not dropped. Resolve conflicts, then commit or run `git stash drop` as needed.",
+        );
+        if (args.verbose && msg) console.error(msg);
+        process.exit(EXIT_GIT);
+      }
+    }
+  }
+
+  if (whenUncommitted === "restore") {
+    const targetStashRef = await findStashRefByBranch(root, targetBranch, gitOpts);
+    if (targetStashRef) {
+      try {
+        await stashPopRef(root, targetStashRef, gitOpts);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(
+          `gflows switch: conflicts occurred while restoring saved changes for '${targetBranch}'.`,
+        );
+        console.error(
+          "The stash was not dropped. Resolve conflicts, then commit or run `git stash drop` as needed.",
+        );
+        if (args.verbose && msg) console.error(msg);
+        process.exit(EXIT_GIT);
+      }
+    }
   }
 
-  await checkout(root, chosen, {
-    dryRun,
-    verbose: args.verbose,
-  });
   if (!quiet && !dryRun) {
-    success(`Switched to branch '${chosen}'.`);
-    // Hint: suggest listing branches
+    success(`Switched to branch '${targetBranch}'.`);
     hint("Use gflows list to see all workflow branches.");
   }
 }

package/src/git.ts

@@ -314,6 +314,173 @@ export async function isClean(cwd: string, options: GitRunOptions = {}): Promise
   return result.stdout.trim() === "";
 }
 
+/** Stash message prefix for per-branch switch restore. Full message: gflows-switch:<branchName>. */
+export const STASH_SWITCH_PREFIX = "gflows-switch:";
+
+/**
+ * Stashes uncommitted changes (including untracked) for the given branch (git stash push -u -m "gflows-switch:<branch>").
+ * Used for per-branch restore so the stash can be found and applied when switching back.
+ * Callers that want at most one stash per branch should drop an existing stash for that branch
+ * (findStashRefByBranch + stashDropRef) before calling this.
+ *
+ * @param cwd - Repo root.
+ * @param branchName - Branch name to tag the stash with.
+ * @param options - dryRun, verbose.
+ * @throws Error if stash fails.
+ */
+export async function stashPush(
+  cwd: string,
+  branchName: string,
+  options: GitRunOptions = {},
+): Promise<void> {
+  const message = `${STASH_SWITCH_PREFIX}${branchName}`;
+  const result = await runGit(["stash", "push", "-u", "-m", message], { cwd, ...options });
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || "git stash push failed.");
+  }
+}
+
+/**
+ * Returns the stash ref (e.g. stash@{0}) for the most recent stash tagged with gflows-switch:<branchName>, or null.
+ * Parses `git stash list` and matches the message; stash list is newest-first.
+ *
+ * @param cwd - Repo root.
+ * @param branchName - Branch name (stash message is gflows-switch:<branchName>).
+ * @param options - dryRun, verbose.
+ */
+export async function findStashRefByBranch(
+  cwd: string,
+  branchName: string,
+  options: GitRunOptions = {},
+): Promise<string | null> {
+  const result = await runGit(["stash", "list"], { cwd, ...options });
+  if (result.exitCode !== 0 || !result.stdout.trim()) return null;
+  const tag = `${STASH_SWITCH_PREFIX}${branchName}`;
+  const escaped = tag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`${escaped}(?:[\\s:]|$)`);
+  for (const line of result.stdout.trim().split("\n")) {
+    const match = line.match(/^(stash@\{\d+\})/);
+    const ref = match?.[1];
+    if (ref && re.test(line)) return ref;
+  }
+  return null;
+}
+
+/** Stash message used for "move changes to target" (one-off stash, popped after checkout). */
+const STASH_SWITCH_MOVE_MESSAGE = "gflows-switch-move";
+
+/**
+ * Stashes uncommitted changes (including untracked) for "move to target" flow (git stash push -u -m "<move message>").
+ * The stash is popped on the target branch; use findStashRefByMessage + stashPopRef after checkout.
+ *
+ * @param cwd - Repo root.
+ * @param options - dryRun, verbose.
+ * @throws Error if stash fails.
+ */
+export async function stashPushMove(cwd: string, options: GitRunOptions = {}): Promise<void> {
+  const result = await runGit(["stash", "push", "-u", "-m", STASH_SWITCH_MOVE_MESSAGE], {
+    cwd,
+    ...options,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || "git stash push failed.");
+  }
+}
+
+/**
+ * Returns the stash ref (e.g. stash@{0}) for the most recent stash whose message contains the given substring, or null.
+ * Used to find the "move" stash after checkout.
+ *
+ * @param cwd - Repo root.
+ * @param messageSubstring - Substring to search for in stash list lines.
+ * @param options - dryRun, verbose.
+ */
+export async function findStashRefByMessage(
+  cwd: string,
+  messageSubstring: string,
+  options: GitRunOptions = {},
+): Promise<string | null> {
+  const result = await runGit(["stash", "list"], { cwd, ...options });
+  if (result.exitCode !== 0 || !result.stdout.trim()) return null;
+  for (const line of result.stdout.trim().split("\n")) {
+    if (!line.includes(messageSubstring)) continue;
+    const match = line.match(/^(stash@\{\d+\})/);
+    const ref = match?.[1];
+    if (ref) return ref;
+  }
+  return null;
+}
+
+/** Message substring used to find the "move" stash after checkout (internal). */
+export const STASH_SWITCH_MOVE_SUBSTRING = "gflows-switch-move";
+
+/**
+ * Pops a specific stash by ref (e.g. stash@{0}). Used to restore per-branch stash for target branch.
+ * On success the stash is removed. On conflict Git keeps the stash so the user can retry or drop it.
+ *
+ * @param cwd - Repo root.
+ * @param stashRef - Stash ref from findStashRefByBranch (e.g. "stash@{0}").
+ * @param options - dryRun, verbose.
+ * @throws Error if stash pop fails (e.g. merge conflicts).
+ */
+export async function stashPopRef(
+  cwd: string,
+  stashRef: string,
+  options: GitRunOptions = {},
+): Promise<void> {
+  const result = await runGit(["stash", "pop", stashRef], { cwd, ...options });
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || `git stash pop ${stashRef} failed.`);
+  }
+}
+
+/**
+ * Drops a specific stash by ref (e.g. stash@{0}). Used to overwrite per-branch stash before pushing a new one.
+ *
+ * @param cwd - Repo root.
+ * @param stashRef - Stash ref (e.g. "stash@{0}").
+ * @param options - dryRun, verbose.
+ * @throws Error if stash drop fails.
+ */
+export async function stashDropRef(
+  cwd: string,
+  stashRef: string,
+  options: GitRunOptions = {},
+): Promise<void> {
+  const result = await runGit(["stash", "drop", stashRef], { cwd, ...options });
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || `git stash drop ${stashRef} failed.`);
+  }
+}
+
+/**
+ * Discards tracked changes in the working tree (git restore .). Does not remove untracked files.
+ *
+ * @param cwd - Repo root.
+ * @param options - dryRun, verbose.
+ * @throws Error if restore fails.
+ */
+export async function restoreTracked(cwd: string, options: GitRunOptions = {}): Promise<void> {
+  const result = await runGit(["restore", "."], { cwd, ...options });
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || "git restore . failed.");
+  }
+}
+
+/**
+ * Removes untracked files and directories (git clean -fd).
+ *
+ * @param cwd - Repo root.
+ * @param options - dryRun, verbose.
+ * @throws Error if clean fails.
+ */
+export async function cleanUntracked(cwd: string, options: GitRunOptions = {}): Promise<void> {
+  const result = await runGit(["clean", "-fd"], { cwd, ...options });
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || "git clean -fd failed.");
+  }
+}
+
 /**
  * Returns the current branch name, or null if HEAD is detached.
  *

package/src/types.ts

@@ -119,4 +119,6 @@ export interface ParsedArgs {
   message: string | undefined;
   // list
   includeRemote: boolean;
+  // switch: explicit mode when uncommitted (overrides prompt)
+  switchMode?: "restore" | "clean" | "cancel" | "move";
 }