gh-stack 0.17.1 → 0.17.2

package/README.md

@@ -342,6 +342,8 @@ The critical insight: after a parent branch's history is rewritten (e.g., rebase
 
 gh-stack solves this by snapshotting every branch's tip **before** any destructive operation. When restacking a child whose parent has been rewritten, gh-stack walks the snapshots newest-first and finds the most recent recorded tip that's no longer an ancestor of the parent's current tip. That orphaned SHA is the correct rebase base — `git rebase --onto <new-parent-tip> <orphaned-old-tip> <child>` replays only the child's unique commits.
 
+If the child sat **behind** the parent when the snapshot was taken (a placeholder branch created before any work landed on it), the recorded tip isn't in the child's history — but it still pins the parent's pre-rewrite history, so the boundary is derived as the child's fork point on it (`merge-base(child, recorded-tip)`). A child with no unique commits is simply moved to the parent's tip, no rebase involved. When no safe boundary can be determined at all, restack refuses with a manual `git rebase --onto` recipe rather than guessing.
+
 Snapshots also power `gh-stack undo`, so the same data structure does double duty.
 
 ### Stack Position in PR Titles

package/package.json

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

package/src/commands/restack.ts

@@ -15,7 +15,7 @@ import {
   writeMetadata,
 } from "../lib/metadata.ts";
 import { ensureMetadata, ensureCleanWorkingTree, ensureValidStack } from "../lib/safety.ts";
-import { takeSnapshot, findPreRewriteSha, findRecordedBaseTip } from "../lib/snapshot.ts";
+import { takeSnapshot, resolveRestackBoundary, findRecordedBaseTip } from "../lib/snapshot.ts";
 import { confirmAction } from "../lib/ui.ts";
 import type { StackMetadata } from "../types.ts";
 
@@ -549,49 +549,45 @@ async function processChain(
       continue;
     }
 
-    // Resolve the rebase base.
-    //
-    //   Strategy:
-    //     1. Look for a recent snapshot where the parent's recorded tip is no
-    //        longer an ancestor of the parent's current tip AND is still an
-    //        ancestor of the child. That recorded SHA is the orphaned
-    //        old-parent tip — exactly the rebase base we need.
-    //     2. Fall back to `merge-base(branch, parent)` if no snapshot tells us
-    //        the parent was rewritten (typical case: parent only had commits
-    //        appended, not rebased).
-    //
-    //   The child-ancestry check (issue #5) prevents stale snapshots from
-    //   older sessions — where the child has already been rebased past the
-    //   recorded point — from being used as a rebase base.
+    // Resolve the rebase boundary — snapshot pre-rewrite tip, a fork point
+    // derived from a rejected snapshot (#30), or merge-base, in that order.
+    // See resolveRestackBoundary for the full strategy.
     //
     //   Re-read metadata fresh because previous iterations of this loop may
     //   have updated snapshots.
     const freshMeta = (await readMetadata()) ?? meta;
-    const oldBaseFromSnapshot = await findPreRewriteSha(freshMeta, parent, branch);
-    const oldBaseFromMergeBase = await git.mergeBase(branch, parent);
-    const oldBase = oldBaseFromSnapshot ?? oldBaseFromMergeBase;
+    const boundary = await resolveRestackBoundary(freshMeta, parent, branch);
 
     if (verbose) {
       console.log();
       console.log(pc.yellow("  Diagnostic: base resolution"));
       console.log(
-        `  ${pc.cyan("Snapshot pre-rewrite tip:")} ${oldBaseFromSnapshot?.slice(0, 8) ?? "(none)"}`,
-      );
-      console.log(
-        `  ${pc.cyan("Current merge-base:")}      ${oldBaseFromMergeBase?.slice(0, 8) ?? "(none)"}`,
+        `  ${pc.cyan("Boundary:")} ${boundary ? `${boundary.sha.slice(0, 8)} (${boundary.source})` : "(none)"}`,
       );
-      if (
-        oldBaseFromSnapshot &&
-        oldBaseFromMergeBase &&
-        oldBaseFromSnapshot !== oldBaseFromMergeBase
-      ) {
+      if (boundary && boundary.source !== "merge-base") {
         console.log(
-          `  ${pc.yellow("⚠ Parent was rewritten")} — using snapshot base (would have replayed parent commits otherwise)`,
+          `  ${pc.yellow("⚠ Parent was rewritten")} — merge-base alone would have replayed parent commits`,
         );
       }
       console.log();
     }
 
+    if (!boundary) {
+      // No snapshot evidence and no common history — any base would be a
+      // guess, and a wrong guess replays the parent's history onto itself.
+      // Refuse with the manual command, consistent with the --onto reroot
+      // path. (#30: never silently guess when we can't derive the boundary.)
+      p.log.error(
+        `Cannot determine a safe rebase base for ${pc.yellow(branch)} onto ${pc.yellow(parent)}.`,
+      );
+      console.log();
+      console.log("  Rebase it manually with an explicit boundary:");
+      console.log(`    ${pc.green(`git rebase --onto ${parent} <old-parent-tip> ${branch}`)}`);
+      console.log();
+      console.log(`  Then re-run ${pc.green("gh-stack restack")} to continue the chain.`);
+      process.exit(1);
+    }
+
     // Checkout the branch
     p.log.info(`Checking out ${pc.yellow(branch)}...`);
     await git.checkout(branch);
@@ -604,21 +600,28 @@ async function processChain(
     });
 
     let success: boolean;
-    if (oldBase) {
-      const sourceLabel = oldBaseFromSnapshot ? "snapshot" : "merge-base";
+    const branchTip = await git.revParse(branch);
+    if (boundary.sha === branchTip) {
+      // The child has no commits of its own (a placeholder branch created off
+      // the parent before any work landed). Nothing to replay — move the ref
+      // instead of invoking rebase. (#30)
       p.log.info(
-        `Rebasing onto ${pc.yellow(parent)} (base: ${oldBase.slice(0, 8)} from ${sourceLabel})`,
+        `${pc.yellow(branch)} has no unique commits — moving it to ${pc.yellow(parent)}'s tip`,
+      );
+      success = await git.resetHard(parent);
+    } else {
+      const sourceLabel =
+        boundary.source === "snapshot-derived" ? "snapshot (derived fork-point)" : boundary.source;
+      p.log.info(
+        `Rebasing onto ${pc.yellow(parent)} (base: ${boundary.sha.slice(0, 8)} from ${sourceLabel})`,
       );
 
       if (verbose) {
-        const count = await git.commitCount(oldBase, branch);
+        const count = await git.commitCount(boundary.sha, branch);
         console.log(`  Moving ${count} commit(s)`);
       }
 
-      success = await git.rebaseOnto(parent, oldBase, branch);
-    } else {
-      p.log.warn("Could not determine rebase base — using simple rebase");
-      success = await git.rebase(parent);
+      success = await git.rebaseOnto(parent, boundary.sha, branch);
     }
 
     if (success) {

package/src/commands/sync.ts

@@ -146,7 +146,7 @@ with the base branch included.
 
   // Take snapshot BEFORE rebasing. This records every branch's pre-rebase
   // tip — including the orphaned base-branch tip that restack will later
-  // need to find when restacking children. (See findPreRewriteSha.)
+  // need to find when restacking children. (See resolveRestackBoundary.)
   await takeSnapshot(meta, stackName, "sync");
 
   // Step 1: Rebase base branch onto main

package/src/lib/advance.ts

@@ -21,7 +21,7 @@ import pc from "picocolors";
 import * as git from "./git.ts";
 import type { StackMetadata } from "../types.ts";
 import { removeBranchFromStack } from "./metadata.ts";
-import { findPreRewriteSha } from "./snapshot.ts";
+import { resolveRestackBoundary } from "./snapshot.ts";
 import { setPrBase } from "./github.ts";
 
 /** What a single bottom branch needs: an active squash-merge, or just advancing
@@ -109,21 +109,19 @@ function reviewReason(decision: string | null): string {
 
 /**
  * Resolve the rebase fork-point for re-rooting `child` after `mergedBranch`
- * landed on the trunk. Mirrors restack's resolver:
- *   1. snapshot pre-rewrite tip of `mergedBranch` (handles the case where the
- *      merged branch was itself rebased earlier in a multi-merge cascade), then
- *   2. `merge-base(child, mergedBranch)` for the common case where the merged
- *      branch still sits at the tip the child was stacked on.
- * Returns null if neither resolves (caller must abort rather than guess).
+ * landed on the trunk. Shares restack's resolver (snapshot pre-rewrite tip →
+ * derived fork point → merge-base; see resolveRestackBoundary) — the snapshot
+ * paths handle a merged branch that was itself rebased earlier in a
+ * multi-merge cascade, including a child that sat behind it (#30).
+ * Returns null if nothing resolves (caller must abort rather than guess).
  */
 export async function resolveForkPoint(
   meta: StackMetadata,
   mergedBranch: string,
   child: string,
 ): Promise<string | null> {
-  const fromSnapshot = await findPreRewriteSha(meta, mergedBranch, child);
-  if (fromSnapshot) return fromSnapshot;
-  return git.mergeBase(child, mergedBranch);
+  const boundary = await resolveRestackBoundary(meta, mergedBranch, child);
+  return boundary?.sha ?? null;
 }
 
 /** Outcome of advancing a single new bottom onto the trunk. */

package/src/lib/git.ts

@@ -285,6 +285,15 @@ export async function rebaseOnto(
   return exitCode === 0;
 }
 
+/**
+ * Move the current branch's ref to `ref` (working tree included).
+ * Returns true if successful. Caller must have verified the tree is clean.
+ */
+export async function resetHard(ref: string): Promise<boolean> {
+  const { exitCode } = await $`git reset --hard ${ref}`.nothrow().quiet();
+  return exitCode === 0;
+}
+
 /**
  * Simple rebase onto a target.
  * Returns true if successful, false if conflicts occurred.

package/src/lib/snapshot.ts

@@ -13,77 +13,97 @@ import { mkdir, readdir, unlink } from "node:fs/promises";
 
 const MAX_SNAPSHOTS_PER_STACK = 10;
 
+/** Where a resolved restack boundary came from. */
+export type BoundarySource = "snapshot" | "snapshot-derived" | "merge-base";
+
+export type RestackBoundary = { sha: string; source: BoundarySource };
+
 /**
- * Find the pre-rewrite SHA for a parent branch by walking snapshots newest-first.
+ * Resolve the rebase boundary for restacking `childBranch` onto
+ * `parentBranch`: the commit whose range `boundary..child` contains exactly
+ * the child's own commits, for `git rebase --onto <parent> <boundary> <child>`.
+ *
+ * Resolution order:
  *
- * Returns the SHA from the most recent snapshot whose recorded tip for
- * `parentBranch` is NOT an ancestor of the parent's current tip — meaning
- * that snapshot was taken before the parent's history got rewritten
- * (typically by `sync` rebasing it onto a new main).
+ * 1. `"snapshot"` (issue #2) — the most recent snapshot whose recorded tip for
+ *    the parent is no longer an ancestor of the parent's current tip: that
+ *    snapshot predates a rewrite of the parent (typically `sync` rebasing it
+ *    onto a new main), and its orphaned old tip is exactly where the child's
+ *    own commits start. The recorded tip must also still be an ancestor of the
+ *    child (issue #5) — a stale tip the child was already rebased past would
+ *    replay a wildly wrong range; those candidates are skipped, not used.
  *
- * That pre-rewrite SHA is the correct rebase base when restacking a child
- * onto this parent — `git rebase --onto <new-tip> <pre-rewrite-tip> <child>`
- * replays only the child's unique commits, never the parent's old history.
+ * 2. `"snapshot-derived"` (issue #30) — a snapshot proves the parent was
+ *    rewritten but its recorded tip is not an ancestor of the child, e.g. the
+ *    child sat BEHIND the parent at snapshot time (committed to the parent,
+ *    then synced, before the child got its first commit). The recorded tip
+ *    still pins the parent's pre-rewrite history, and the child forked
+ *    somewhere on it: `merge-base(child, recordedTip)` is that fork point.
+ *    Only used when it is a DESCENDANT of `merge-base(child, parent)` — the
+ *    higher boundary is always the safe one, since everything below it already
+ *    exists in the new base's history. (A stale #5-shaped snapshot derives a
+ *    fork point BELOW the current merge-base; using it would replay the
+ *    parent's commits, so the current merge-base wins there.)
  *
- * **Child validation (issue #5)**: When `childBranch` is provided, any candidate
- * SHA must also still be an ancestor of the child. If the child has already
- * been rebased past this point (e.g., a previous restack already moved it),
- * the recorded SHA is stale for this child and would cause `rebase --onto`
- * to replay a wildly wrong range. We skip those candidates and keep walking.
+ * 3. `"merge-base"` — `merge-base(child, parent)`, correct whenever the parent
+ *    has only had commits appended, never been rewritten.
  *
- * Returns null if no snapshots exist, no recorded tip qualifies, or every
- * snapshot's recorded tip is still an ancestor of the parent's current tip
- * (i.e., the parent has only had commits appended, never been rebased —
- * `merge-base` is still correct).
+ * Returns null when nothing resolves (no snapshot evidence and no common
+ * history) — the caller must refuse rather than guess.
+ *
+ * If the child branch doesn't exist locally, snapshot validation degrades to
+ * parent-only (the newest rewritten tip is accepted without the child check).
  */
-export async function findPreRewriteSha(
+export async function resolveRestackBoundary(
   meta: StackMetadata,
   parentBranch: string,
-  childBranch?: string,
-): Promise<string | null> {
-  if (!meta.snapshots || meta.snapshots.length === 0) return null;
-
-  let currentParentTip: string;
+  childBranch: string,
+): Promise<RestackBoundary | null> {
+  let currentParentTip: string | null = null;
   try {
     currentParentTip = await git.revParse(parentBranch);
   } catch {
-    return null;
+    currentParentTip = null;
   }
 
   let currentChildTip: string | null = null;
-  if (childBranch) {
-    try {
-      currentChildTip = await git.revParse(childBranch);
-    } catch {
-      // Child doesn't exist locally — fall back to parent-only validation
-      currentChildTip = null;
-    }
+  try {
+    currentChildTip = await git.revParse(childBranch);
+  } catch {
+    currentChildTip = null;
   }
 
-  // Walk newest → oldest
-  for (let i = meta.snapshots.length - 1; i >= 0; i--) {
-    const recorded = meta.snapshots[i]!.branches[parentBranch];
-    if (!recorded) continue;
-    if (recorded === currentParentTip) continue;
-
-    // The recorded SHA must no longer be an ancestor of the parent's current
-    // tip — that's how we detect the parent's history was rewritten.
-    const stillAncestorOfParent = await git.isAncestor(recorded, currentParentTip);
-    if (stillAncestorOfParent) continue;
-
-    // Issue #5 guard: if we know the child, the recorded SHA must still be
-    // an ancestor of the child. Otherwise the child has already been rebased
-    // past this point (or never branched off it) and using it as a base
-    // would replay unrelated history.
-    if (currentChildTip) {
-      const stillAncestorOfChild = await git.isAncestor(recorded, currentChildTip);
-      if (!stillAncestorOfChild) continue;
+  // Walk snapshots newest → oldest for evidence the parent was rewritten.
+  let accepted: string | null = null;
+  let rejected: string | null = null; // newest rewritten tip that failed the child check
+  if (currentParentTip && meta.snapshots) {
+    for (let i = meta.snapshots.length - 1; i >= 0; i--) {
+      const recorded = meta.snapshots[i]!.branches[parentBranch];
+      if (!recorded || recorded === currentParentTip) continue;
+      if (await git.isAncestor(recorded, currentParentTip)) continue; // appended-to, not rewritten
+      if (!currentChildTip || (await git.isAncestor(recorded, currentChildTip))) {
+        accepted = recorded;
+        break;
+      }
+      rejected ??= recorded;
     }
+  }
 
-    return recorded;
+  if (accepted) return { sha: accepted, source: "snapshot" };
+
+  const mbCurrent = await git.mergeBase(childBranch, parentBranch);
+
+  if (rejected && currentChildTip) {
+    const derived = await git.mergeBase(childBranch, rejected);
+    if (derived) {
+      if (!mbCurrent) return { sha: derived, source: "snapshot-derived" };
+      if (derived !== mbCurrent && (await git.isAncestor(mbCurrent, derived))) {
+        return { sha: derived, source: "snapshot-derived" };
+      }
+    }
   }
 
-  return null;
+  return mbCurrent ? { sha: mbCurrent, source: "merge-base" } : null;
 }
 
 /**
@@ -96,7 +116,7 @@ export async function findPreRewriteSha(
  * `git rebase --onto <new-base> <baseTip> <root>` drops the already-merged
  * prefix instead of replaying it.
  *
- * Unlike `findPreRewriteSha`, this does NOT require the base branch to still
+ * Unlike `resolveRestackBoundary`, this does NOT require the base branch to still
  * exist locally — that's the whole point: after a squash-merge deletes the base
  * branch, its tip survives only in these snapshots. The ancestor-of-root check
  * rejects stale candidates (an older base tip the root no longer sits on).