gh-stack 0.19.0 → 0.19.1

package/README.md

@@ -276,7 +276,7 @@ sync [--dry-run] [--no-push|--push] [--resume | --fresh] [--overwrite-remote]
 
 merge [--dry-run] [-d|--delete-branch] [--collapse] [--skip-collapse-check]
 merge --approved [--collapse] [--dry-run] [-d|--delete-branch]
-merge --base [--dry-run] [-d|--delete-branch]
+merge --base [--dry-run] [-d|--delete-branch] [--no-push|--push]
     Default (top-down collapse): squash-merge the whole stack top-down
     via GitHub (PR3 → PR2 → PR1), then enables auto-merge for the base PR
     into main. The whole stack lands on main as a single squash commit.
@@ -323,7 +323,18 @@ merge --base [--dry-run] [-d|--delete-branch]
                 just its own commits). One PR per run — run it again to
                 land the next. Approval is enforced by GitHub branch
                 protection, not gh-stack. A base PR already merged outside
-                gh-stack is detected and advanced past.
+                gh-stack is detected and advanced past. The re-root waits
+                until origin's main shows the merge commit, and stops (exit
+                2) if it never does. When a re-root stops (a conflict, or
+                main not showing the merge yet), finish it by re-running
+                `gh-stack merge --base` after `git rebase --continue`: it
+                advances past the merged PR and picks up a branch that's
+                already re-rooted. Don't run `restack` there: it would put
+                the branch back on the merged one.
+                --no-push (or GH_STACK_NO_PUSH=1) still merges the PR on
+                GitHub but keeps the re-root and the restack above it
+                local, PR bases included, until `gh-stack submit`. The
+                `[restack] push` config default doesn't apply to merge.
     --collapse  With the default or --approved, stop after collapsing into
                 the base PR WITHOUT merging it to main, so you can review
                 the cumulative diff on GitHub. Re-run `gh-stack merge` to
@@ -520,7 +531,7 @@ If a command needs to prompt but stdin isn't a TTY, it exits 1 with the prompt i
 ```
 GH_STACK_YES=1         Skip all confirmations (same as --yes; also enables --plain)
 GH_STACK_PLAIN=1       Plain output (same as --plain)
-GH_STACK_NO_PUSH=1     restack/sync never push (same as --no-push; wins over --yes; 0 = push)
+GH_STACK_NO_PUSH=1     restack, sync and merge --base never push (same as --no-push; wins over --yes; 0 = push)
 GH_STACK_DRAFT=1       submit creates new PRs as drafts (same as --draft; 0 = ready)
                        (both accept 1/0, true/false, yes/no; anything else is an error)
 GH_STACK_NO_COLOR=1    Disable colored output
@@ -552,8 +563,10 @@ says so in its output.
 | `[restack] push` | `--push` / `--no-push`   | `GH_STACK_NO_PUSH` (inverted) | `true`   |
 
 `[restack] push` governs `restack` and `sync` only. `merge` and
-`submit --restack` always push the branches they restack: publishing is their
-job, and child PRs left stale on GitHub would be worse than any default. A
+`submit --restack` push the branches they restack whatever the config says:
+publishing is their job, and child PRs left stale on GitHub would be worse
+than any default. Only `merge --base` can be kept local, and only by an
+explicit `--no-push` or `GH_STACK_NO_PUSH=1`. A
 `restack --resume` keeps the push decision of the run it resumes unless you
 pass `--push` or `--no-push`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gh-stack",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Stacked PR manager for squash-merge workflows",
   "author": "Kiliman <kiliman@gmail.com>",
   "license": "MIT",

package/src/commands/config.ts

@@ -38,7 +38,7 @@ FILES
 
 ENVIRONMENT (1/0, true/false, or yes/no)
   GH_STACK_DRAFT       submit draft default
-  GH_STACK_NO_PUSH     restack/sync push default (1 = don't push)
+  GH_STACK_NO_PUSH     restack/sync/merge --base push default (1 = don't push)
 
 --yes is not configurable from a file: auto-confirming destructive operations
 must be asked for per run (--yes or GH_STACK_YES=1).

package/src/commands/merge.ts

@@ -32,10 +32,15 @@ import {
   type BranchReview,
   type MergeAction,
 } from "../lib/advance.ts";
+import { flagSetting, parseEnvBool, type Resolved } from "../lib/config.ts";
 
 const MAX_RETRIES = 12;
 const RETRY_DELAY_MS = 5000;
 
+// Waits between fetches while origin's trunk catches up to a merge GitHub has
+// already reported (one entry per retry; ~7s in all).
+const TRUNK_MERGE_WAIT_MS = [1000, 2000, 4000];
+
 // After GitHub rejects a merge with the "still recomputing" signature, back off
 // (capped) and re-poll before retrying. One entry per retry; length+1 = max
 // attempts. Bounds total transient wait per PR to ~30s.
@@ -260,7 +265,7 @@ gh-stack merge — Squash-merge a stack via GitHub
 USAGE
   gh-stack merge [--dry-run] [-d|--delete-branch] [--collapse]
   gh-stack merge --approved [--collapse] [--dry-run] [-d|--delete-branch]
-  gh-stack merge --base [--dry-run] [-d|--delete-branch]
+  gh-stack merge --base [--dry-run] [-d|--delete-branch] [--no-push|--push]
 
 DEFAULT (top-down collapse)
   Squash-merges the whole stack from top to bottom via GitHub:
@@ -280,6 +285,11 @@ DEFAULT (top-down collapse)
   Squash-merges only the bottom PR into main as its own commit, then re-roots
   the next branch onto main. One PR per run — run it again to land the next.
   Approval is enforced by GitHub branch protection, not gh-stack.
+  With --no-push (or GH_STACK_NO_PUSH=1) the PR still merges on GitHub, but
+  the re-rooted branches stay local until ${pc.green("gh-stack submit")}. The
+  \`[restack] push\` config default doesn't apply to merge. If the re-root
+  stops (a conflict, or main not showing the merge yet), finish the fix, then
+  re-run ${pc.green("gh-stack merge --base")}: it picks up the already-merged PR.
 
 --collapse (stop before main)
   With the default or --approved, stop after collapsing into the base PR
@@ -313,6 +323,8 @@ OPTIONS
       --skip-collapse-check
                        Don't verify the collapsed children's content is in
                        the base PR (above)
+      --no-push        With --base: re-root and restack locally only (also
+                       GH_STACK_NO_PUSH=1); --push overrides the variable
       --dry-run        Show what would happen without doing anything
 `);
     return;
@@ -948,6 +960,43 @@ async function collapsedChildren(
   return { collapsed, unknown: null };
 }
 
+/**
+ * Fetch the trunk and confirm it holds PR `prNumber`'s merge commit (#51).
+ * The re-root rebases onto `origin/<trunk>`; a trunk fetched before the squash
+ * landed puts the next branch on a main without the merged PR's changes, so
+ * its PR shows them deleted. Not ok when the merge commit can't be confirmed
+ * on the trunk, and the caller must stop rather than re-root.
+ */
+async function fetchTrunkWithMerge(
+  trunk: string,
+  prNumber: number,
+): Promise<{ ok: boolean; mergeCommit: string | null }> {
+  let mergeCommit: string | null = null;
+  for (let attempt = 0; ; attempt++) {
+    mergeCommit ??= (await getPrMergeState(prNumber))?.mergeCommit ?? null;
+    await $`git fetch origin ${trunk}`.nothrow().quiet();
+    if (mergeCommit && (await git.isAncestor(mergeCommit, `origin/${trunk}`))) {
+      return { ok: true, mergeCommit };
+    }
+    if (attempt >= TRUNK_MERGE_WAIT_MS.length) return { ok: false, mergeCommit };
+    await Bun.sleep(TRUNK_MERGE_WAIT_MS[attempt]!);
+  }
+}
+
+/**
+ * Whether `merge --base` pushes the branches it re-roots and restacks:
+ * `--push`/`--no-push`, else GH_STACK_NO_PUSH (#51). The squash itself always
+ * lands on GitHub. The `[restack] push` config default deliberately doesn't
+ * apply: a repo default for restack shouldn't change what a merge publishes.
+ */
+function resolveMergePush(args: string[]): Resolved {
+  const flag = flagSetting("restack.push", args);
+  if (flag) return flag;
+  const noPush = parseEnvBool("GH_STACK_NO_PUSH", process.env.GH_STACK_NO_PUSH);
+  if (noPush === undefined) return { value: true, source: "default" };
+  return { value: !noPush, source: "env", origin: "GH_STACK_NO_PUSH" };
+}
+
 /**
  * `gh-stack merge --base` — squash-merge ONLY the bottom PR into main, then
  * re-root the next branch onto main (replaying just its own commits, via
@@ -974,7 +1023,17 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
   }
 
   const stack = meta.stacks[stackName]!;
-  await ensureValidStack(meta, stackName);
+  const base = stackBase(stack);
+  // The bottom branch may be gone locally once its PR merged: --delete-branch
+  // deletes it, and a re-run then only finishes the re-root (#51).
+  const root = Object.keys(stack.branches).find((b) => stack.branches[b]!.parent === base);
+  const rootPr = root ? stack.branches[root]!.pr : undefined;
+  const rootGone =
+    root != null &&
+    rootPr != null &&
+    !(await git.localBranchExists(root)) &&
+    (await getPrMergeState(rootPr))?.state === "MERGED";
+  await ensureValidStack(meta, stackName, { allowMissing: rootGone ? [root] : [] });
   const ordered = getOrderedBranches(stack);
   if (ordered.length === 0) {
     p.cancel("No branches in this stack");
@@ -983,7 +1042,6 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
 
   // Like top-down merge: a split stack rooted off another stack can't drain to
   // main until it's re-rooted. Require a trunk base.
-  const base = stackBase(stack);
   if (base !== "main" && base !== "master") {
     p.cancel(
       `${pc.yellow(stackName)} is based on ${pc.yellow(base)}, not main — can't merge yet.\n\n` +
@@ -994,6 +1052,7 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
   }
   const trunk = base;
   const targetRef = `origin/${trunk}`;
+  const push = resolveMergePush(args).value;
 
   p.intro(pc.cyan("Merge Base PR (via GitHub)"));
   p.log.info(`Stack: ${pc.yellow(stackName)}`);
@@ -1027,6 +1086,11 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
     console.log(
       `    ${pc.dim(`then re-root ${nextChild} onto ${trunk} — the rest stays a stack`)}`,
     );
+    if (!push) {
+      console.log(
+        `    ${pc.dim(`(--no-push: re-rooted branches stay local; ${pc.green("gh-stack submit")} publishes them)`)}`,
+      );
+    }
   }
   console.log();
 
@@ -1097,8 +1161,6 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
   // Keep a copy of the original topology to archive if the stack fully drains.
   const originalStack = structuredClone(stack);
 
-  await $`git fetch origin ${trunk}`.quiet();
-
   for (let i = 0; i < plan.steps.length; i++) {
     const step = plan.steps[i]!;
     const mergedBranch = step.branch;
@@ -1151,6 +1213,25 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
     }
 
     if (child) {
+      // Re-root onto the trunk as it is now, with the merge in it (#51).
+      const trunkState = await fetchTrunkWithMerge(trunk, step.pr!);
+      if (!trunkState.ok) {
+        console.log();
+        p.log.error(
+          `PR #${step.pr} is merged, but ${targetRef} doesn't show ${
+            trunkState.mergeCommit
+              ? `its merge commit ${trunkState.mergeCommit.slice(0, 8)}`
+              : "its merge commit (GitHub didn't say which it is)"
+          } yet.`,
+        );
+        console.log(
+          `  Stopped before re-rooting ${pc.yellow(child)}: a ${trunk} without the merge would drop its changes from the stack.`,
+        );
+        console.log(`  Once ${trunk} has it, finish with:`);
+        console.log(`    ${pc.green("gh-stack merge --base")}`);
+        process.exit(2);
+      }
+
       const res = await advanceNewBottom({
         meta,
         stackName,
@@ -1159,16 +1240,17 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
         childPr,
         targetRef,
         recordedBase: trunk,
+        push,
         expect: verified.get(child),
       });
       if (!res.ok) {
         console.log();
         if (res.reason === "conflict") {
           p.log.error(`Rebase conflict re-rooting ${pc.yellow(child)} onto ${trunk}.`);
-          console.log(`  Resolve the conflict, then:`);
+          console.log(`  Resolve the conflict, then finish with:`);
           console.log(`    ${pc.green("git rebase --continue")}`);
           console.log(
-            `    ${pc.green("gh-stack restack")}   ${pc.dim("(restacks the rest of the tail)")}`,
+            `    ${pc.green("gh-stack merge --base")}   ${pc.dim(`(pushes ${child}, retargets its PR, restacks the rest)`)}`,
           );
           console.log();
           console.log(
@@ -1228,10 +1310,10 @@ async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean, args: string[
   if (await git.localBranchExists(newBottom)) {
     await git.checkout(newBottom);
     const { default: restack } = await import("./restack.ts");
-    // Always push: merge publishes by nature (the advance above already
-    // pushed), and children left stale on GitHub are worse than any default.
-    // An explicit flag also means no config is read mid-merge.
-    await restack(["--push", ...(overwrite ? ["--overwrite-remote"] : [])]);
+    // Push unless this run is local-only (--no-push / GH_STACK_NO_PUSH): the
+    // tail must match the re-root above. An explicit flag also means the
+    // `[restack] push` config isn't read mid-merge.
+    await restack([push ? "--push" : "--no-push", ...(overwrite ? ["--overwrite-remote"] : [])]);
   }
 
   p.outro(

package/src/commands/sync.ts

@@ -337,9 +337,11 @@ async function advanceMergedBottoms(
         console.log();
         if (res.reason === "conflict") {
           p.log.error(`Rebase conflict re-rooting ${pc.yellow(child)} onto ${trunk}.`);
-          console.log(`  Resolve it, then finish the restack:`);
+          console.log(`  Resolve it, then finish the sync:`);
           console.log(`    ${pc.green("git rebase --continue")}`);
-          console.log(`    ${pc.green("gh-stack restack")}`);
+          console.log(
+            `    ${pc.green("gh-stack sync")}   ${pc.dim(`(picks up the re-rooted ${child}; not restack, which would put it back on ${mergedBranch})`)}`,
+          );
         } else {
           p.log.error(
             `Could not determine a safe rebase base for ${pc.yellow(child)} (${res.reason}).`,

package/src/index.ts

@@ -246,7 +246,7 @@ ${bold("ENVIRONMENT")}
   GH_STACK_PLAIN=1     Same as --plain
   GH_STACK_NO_COLOR    Disable colored output
   GH_STACK_DRAFT=1     submit creates new PRs as drafts (0 = ready)
-  GH_STACK_NO_PUSH=1   restack/sync never push (0 = push)
+  GH_STACK_NO_PUSH=1   restack/sync/merge --base never push (0 = push)
 
 ${bold("CONFIG")}
   .gh-stack.toml (repo root) and ~/.config/gh-stack/config.toml set flag

package/src/lib/advance.ts

@@ -120,6 +120,17 @@ export async function resolveForkPoint(
   mergedBranch: string,
   child: string,
 ): Promise<string | null> {
+  // `gh pr merge --delete-branch` deletes the merged branch locally too, which
+  // leaves the shared resolver no ref to read snapshots against. Its pre-merge
+  // tip is in the snapshot the caller took: use the newest recorded tip the
+  // child still builds on.
+  if (!(await git.localBranchExists(mergedBranch))) {
+    for (const snap of (meta.snapshots ?? []).toReversed()) {
+      const tip = snap.branches[mergedBranch];
+      if (tip && (await git.isAncestor(tip, child))) return tip;
+    }
+    return null;
+  }
   const boundary = await resolveRestackBoundary(meta, mergedBranch, child);
   return boundary?.sha ?? null;
 }
@@ -137,6 +148,9 @@ export type AdvanceResult =
  *
  * The caller MUST have taken a snapshot first — on a rebase conflict this leaves
  * the in-progress `git rebase` for the user to resolve and returns `conflict`.
+ * Metadata still names the merged branch as the child's parent then, so the
+ * fix is to re-run the caller: this skips the finished rebase and does the rest.
+ * (`restack` would rebase the child back onto the merged branch.)
  */
 export async function advanceNewBottom(opts: {
   meta: StackMetadata;
@@ -158,21 +172,32 @@ export async function advanceNewBottom(opts: {
   const push = opts.push ?? true;
   let retargeted = false;
 
-  const forkPoint = await resolveForkPoint(meta, mergedBranch, child);
-  if (!forkPoint) return { ok: false, reason: "no-fork-point" };
+  // Already on the target: an earlier run stopped on a conflict the user then
+  // resolved, or the branch was re-rooted by hand (#51). Its fork point is
+  // behind it now, so skip the rebase and finish the rest (push, PR base,
+  // metadata). Before a re-root the child can't contain the target, which
+  // holds the merged PR's new squash commit.
+  if (await git.isAncestor(targetRef, child)) {
+    p.log.info(
+      `${pc.yellow(child)} is already on ${pc.green(recordedBase)} — finishing its re-root`,
+    );
+  } else {
+    const forkPoint = await resolveForkPoint(meta, mergedBranch, child);
+    if (!forkPoint) return { ok: false, reason: "no-fork-point" };
+
+    // Guard: the fork-point must be an ancestor of the child, else `--onto` would
+    // replay an unrelated range. Bail loudly rather than mangle history.
+    if (!(await git.isAncestor(forkPoint, child))) {
+      return { ok: false, reason: "bad-fork-point", forkPoint };
+    }
 
-  // Guard: the fork-point must be an ancestor of the child, else `--onto` would
-  // replay an unrelated range. Bail loudly rather than mangle history.
-  if (!(await git.isAncestor(forkPoint, child))) {
-    return { ok: false, reason: "bad-fork-point", forkPoint };
+    p.log.info(
+      `Re-rooting ${pc.yellow(child)} onto ${pc.green(recordedBase)} ${pc.dim(`(base: ${forkPoint.slice(0, 8)})`)}`,
+    );
+    const ok = await git.rebaseOnto(targetRef, forkPoint, child);
+    if (!ok) return { ok: false, reason: "conflict", forkPoint };
   }
 
-  p.log.info(
-    `Re-rooting ${pc.yellow(child)} onto ${pc.green(recordedBase)} ${pc.dim(`(base: ${forkPoint.slice(0, 8)})`)}`,
-  );
-  const ok = await git.rebaseOnto(targetRef, forkPoint, child);
-  if (!ok) return { ok: false, reason: "conflict", forkPoint };
-
   if (push) {
     // Push the rebased head first so the PR diff is clean before its base flips.
     // If it didn't land, leave the base alone: retargeting onto the trunk with

package/src/lib/safety.ts

@@ -170,7 +170,11 @@ export function ensureNotMain(branch: string): void {
 /**
  * Validate stack metadata before destructive operations.
  */
-export async function validateStack(meta: StackMetadata, stackName: string): Promise<string[]> {
+export async function validateStack(
+  meta: StackMetadata,
+  stackName: string,
+  opts: { allowMissing?: string[] } = {},
+): Promise<string[]> {
   const stack = meta.stacks[stackName];
   if (!stack) return [`Stack "${stackName}" not found`];
 
@@ -181,7 +185,7 @@ export async function validateStack(meta: StackMetadata, stackName: string): Pro
   for (const branchName of branchNames) {
     const branch = stack.branches[branchName]!;
 
-    if (!(await git.localBranchExists(branchName))) {
+    if (!opts.allowMissing?.includes(branchName) && !(await git.localBranchExists(branchName))) {
       errors.push(`Branch "${branchName}" does not exist locally`);
     }
 
@@ -201,8 +205,12 @@ export async function validateStack(meta: StackMetadata, stackName: string): Pro
   return errors;
 }
 
-export async function ensureValidStack(meta: StackMetadata, stackName: string): Promise<void> {
-  const errors = await validateStack(meta, stackName);
+export async function ensureValidStack(
+  meta: StackMetadata,
+  stackName: string,
+  opts: { allowMissing?: string[] } = {},
+): Promise<void> {
+  const errors = await validateStack(meta, stackName, opts);
   if (errors.length === 0) return;
 
   p.cancel(`Invalid stack metadata for ${pc.yellow(stackName)}`);

package/src/lib/using-gh-stack.md

@@ -74,8 +74,9 @@ export GH_STACK_YES=1     # skip every confirmation, plain output
   human approves), add `--no-push` to `restack`/`sync`, or export
   `GH_STACK_NO_PUSH=1` (a repo may also set `[restack] push = false`). It wins
   over `--yes` for pushes and lists what's ahead of origin at the end; publish
-  later with `gh-stack restack --push`. `merge` and `submit --restack` always
-  push. `restack --resume` keeps the interrupted run's push decision unless you
+  later with `gh-stack restack --push`. `merge --base` honors `--no-push` and
+  `GH_STACK_NO_PUSH` (not the config); other `merge` modes and `submit --restack`
+  always push. `restack --resume` keeps the interrupted run's push decision unless you
   pass `--push`/`--no-push`. `--yes` itself can't come from a config file:
   always pass it or `GH_STACK_YES=1`.
 - A prompt reached without a TTY on stdin **exits 1** (naming the prompt)
@@ -335,7 +336,12 @@ Merge is **top-down everywhere** (collapse PRn → PRn-1 → … → base PR, th
 - **`merge --base`**: squash-merge **only the bottom PR** into trunk and re-root
   the next branch onto trunk — one PR per run, re-run for the next. Use this to
   land reviewed PRs one at a time. Auto-advances past a bottom PR already merged
-  outside gh-stack.
+  outside gh-stack. If the re-root stops (a conflict, or "origin/main doesn't
+  show its merge commit"), fix it (`git rebase --continue`) and **re-run
+  `merge --base`**: it advances past the merged PR and finishes a branch that's
+  already re-rooted. Don't run `restack` there: it would put the branch back on
+  the merged one. `--no-push` / `GH_STACK_NO_PUSH=1` still merges on GitHub but
+  keeps the re-root and the tail local until `gh-stack submit`.
 - **`--collapse`** (with `merge` or `merge --approved`): stop after collapsing
   into the base PR — review on GitHub, then re-run `merge` to finish.