gh-stack 0.18.0 → 0.19.0

package/src/lib/run-log.ts

@@ -0,0 +1,117 @@
+// The saved state of a restack/sync/join run, read back: is a run still
+// pending, where did it stop, and what did it do (#15, #29).
+//
+// The state itself is written by restack.ts as the run goes (see RestackState).
+// This module only interprets it, so `restack`, `sync`, `merge`, `join` and
+// `undo` agree on what "an interrupted run" means.
+import pc from "picocolors";
+import * as p from "./output.ts";
+import { InvalidRunStateError, clearRestackState, loadRestackState } from "./metadata.ts";
+import type { RestackState, RunLogEntry } from "../types.ts";
+
+/**
+ * The saved run state, or null. A state that can't be used (unreadable, or
+ * from another gh-stack version) is never upgraded: with `discard` (the
+ * `--fresh` path) it's deleted with a note, otherwise this exits 1 saying how
+ * to discard it.
+ */
+export async function loadRunState(opts: { discard?: boolean } = {}): Promise<RestackState | null> {
+  try {
+    return await loadRestackState();
+  } catch (err) {
+    if (!(err instanceof InvalidRunStateError)) throw err;
+    if (opts.discard) {
+      p.log.warn(`Discarding the saved run state at ${err.path}: ${err.reason}.`);
+      await clearRestackState();
+      return null;
+    }
+    p.cancel(
+      `${err.message}\n\n  Discard it and restack from the current branch:\n    ${pc.green("gh-stack restack --fresh")}`,
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * A saved run that hasn't finished: a conflict stop, a kill, failed or held
+ * pushes, or a rebase that was saved as started but never ran (or was
+ * aborted). All of them are resumable; nothing is inferred from the branch
+ * position, since a kill before the rebase started looks just like an abort.
+ */
+export async function findPendingRun(
+  opts: { discard?: boolean } = {},
+): Promise<RestackState | null> {
+  const state = await loadRunState(opts);
+  return state && !state.finished_at ? state : null;
+}
+
+/** Branches whose push failed, was declined or held, and hasn't succeeded since. */
+export function outstandingPushes(state: RestackState): string[] {
+  const out = new Set<string>();
+  for (const e of state.log) {
+    if (e.action === "push-failed" || e.action === "push-declined" || e.action === "push-held") {
+      out.add(e.branch);
+    } else if (e.action === "pushed") {
+      out.delete(e.branch);
+    }
+  }
+  return [...out];
+}
+
+/** Where the run stopped, for "An interrupted sync was detected (stopped at …)". */
+export function stoppedAt(state: RestackState): string {
+  if (state.rebase) return `${state.rebase.branch}: rebasing onto ${state.rebase.onto}`;
+  const next = state.chain[state.current_index];
+  if (next) return next;
+  const unpushed = outstandingPushes(state);
+  if (unpushed.length > 0) return `${unpushed.join(", ")}: not pushed`;
+  return "the end of its chain";
+}
+
+/** What's left for a resume to do, one line per item. */
+export function remainingSteps(state: RestackState): string[] {
+  const steps: string[] = [];
+  for (const b of outstandingPushes(state)) steps.push(`push ${b}`);
+  if (state.rebase) steps.push(`finish rebasing ${state.rebase.branch}, then push it`);
+  const from = state.current_index + (state.rebase ? 1 : 0);
+  const rest = state.chain.slice(from);
+  if (rest.length > 0) steps.push(`restack and push ${rest.join(", ")}`);
+  return steps;
+}
+
+export function formatLogEntry(e: RunLogEntry): string {
+  const b = pc.yellow(e.branch);
+  switch (e.action) {
+    case "rebased":
+      return `${pc.green("✓")} rebased ${b} onto ${e.onto ?? "its parent"}`;
+    case "up-to-date":
+      return `${pc.dim("·")} ${b} already on ${e.onto ?? "its parent"}`;
+    case "rebase-declined":
+      return `${pc.dim("–")} skipped rebasing ${b} (declined)`;
+    case "pushed":
+      return `${pc.green("✓")} pushed ${b}`;
+    case "push-failed":
+      return `${pc.red("✗")} push of ${b} failed`;
+    case "push-declined":
+      return `${pc.yellow("–")} push of ${b} declined`;
+    case "push-held":
+      return `${pc.yellow("⏸")} held ${b} back${e.detail ? ` (${e.detail})` : ""}`;
+    case "local-only":
+      return `${pc.dim("·")} ${b} is local-only (not submitted), not pushed`;
+  }
+}
+
+/** The run's log as indented lines (empty when nothing happened yet). */
+export function formatRunLog(state: RestackState): string[] {
+  return state.log.map((e) => `  ${formatLogEntry(e)}`);
+}
+
+/** "sync, started 2026-10-27 14:03" (local time) */
+const two = (n: number) => String(n).padStart(2, "0");
+
+export function describeRun(state: RestackState): string {
+  const at = state.started_at ? new Date(state.started_at) : null;
+  if (!at || Number.isNaN(at.getTime())) return state.command;
+  const when = `${at.getFullYear()}-${two(at.getMonth() + 1)}-${two(at.getDate())} ${two(at.getHours())}:${two(at.getMinutes())}`;
+  return `${state.command}, started ${when}`;
+}

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

@@ -62,12 +62,22 @@ export GH_STACK_YES=1     # skip every confirmation, plain output
   (network-free) or `gh-stack status --json` (adds PR/CI/review state).
 - **Always pass `-t`/`-b` to `submit`** so PRs get real titles/bodies instead
   of generic auto-generated ones (see below).
+- **Run `gh-stack config` once per repo** to see its defaults. A repo whose
+  `.gh-stack.toml` sets `[submit] draft = true` opens every new PR as a draft
+  without `--draft`; pass `--no-draft` only when you were asked for a
+  ready-for-review PR. `submit --json` reports `draft` for PRs it created.
+- **Need the PR number or URL? Add `--json` to `submit`** instead of running
+  `gh pr view` afterwards. stdout is only the JSON; logs go to stderr.
 - Commands that rebase (`restack`, `sync`, `merge`) **refuse to run on a dirty
   tree** — commit or stash first.
 - **`--yes` also accepts pushes.** To rebase without publishing (e.g. until a
   human approves), add `--no-push` to `restack`/`sync`, or export
-  `GH_STACK_NO_PUSH=1`. It wins over `--yes` for pushes and lists what's ahead
-  of origin at the end.
+  `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
+  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)
   instead of hanging. If you see `refusing to prompt`, re-run with
   `GH_STACK_YES=1`.
@@ -118,6 +128,30 @@ This resolves the catch-22 where `sync`/`restack` said "not in any stack" for a
 tip you hadn't submitted yet. (`submit` still auto-tracks too — `add` is just the
 no-publish path.)
 
+**Splice an existing branch/PR into a stack — `gh-stack join`.** For a branch
+that should have been stacked but was cut from main on its own (often with its
+own PR already open):
+
+```bash
+gh-stack join <branch> --dry-run          # preview: resulting stack + each PR's projected diff
+gh-stack join <branch>                    # insert as the new bottom of the current stack
+gh-stack join <branch> --above <parent>   # insert between <parent> and its children
+```
+
+`join` syncs the incoming branch onto its new parent first, replaying only its
+own commits, then restacks everything above it, pushes, and retargets the PR
+bases on GitHub. **Don't do this by hand with `git rebase`:** rebasing children
+onto a branch that's behind main silently drags merged main commits into their
+diffs. Run `--dry-run` first and check each PR's commit/file count. A conflict
+syncing the incoming branch leaves the stack untouched (resolve,
+`git rebase --continue`, re-run the join); a conflict restacking above it resumes
+with `gh-stack restack --resume`. A branch alone in its own one-branch stack is
+absorbed; one in a larger stack is refused. Unless you pass `--no-push`, the
+incoming branch must already be on origin (`git push -u origin <branch>`). If a
+child was cut from an older, since-rewritten version of the incoming branch,
+join refuses and prints the `git rebase --onto` that drops the stale copies: run
+it, then re-run the join.
+
 ### 2. Push & create PRs — `submit`
 
 `submit` is the workhorse: **idempotent, scope-aware, self-healing**. It pushes
@@ -128,6 +162,7 @@ visualization in every PR body.
 ```bash
 gh-stack submit                       # push downstack + create/update PRs
 gh-stack submit -d                    # create new PRs as drafts
+gh-stack submit --no-draft            # ready for review despite a draft default
 gh-stack submit --dry-run             # preview, no side effects
 gh-stack submit --restack             # then propagate up to children (see below)
 gh-stack submit -t "<title>" -b "<body>"   # explicit title/body for new PRs
@@ -151,6 +186,54 @@ EOF
 )"
 ```
 
+**`submit --json` returns what happened to each branch** (stdout is only the
+JSON document, on every exit; logs go to stderr, so capture stdout alone):
+
+```bash
+gh-stack submit --json -t "<title>" --body-file /tmp/body.md > /tmp/submit.json
+jq -r '.branches[-1].url' /tmp/submit.json     # the current branch's PR
+```
+
+```json
+{
+  "stack": "my-stack",
+  "current_branch": "feat-b",
+  "branches": [
+    {
+      "branch": "feat-a",
+      "parent": "main",
+      "pr": 101,
+      "url": "https://github.com/org/repo/pull/101",
+      "title": "Feat A (1/2)",
+      "action": "unchanged",
+      "pushed": false,
+      "draft": null
+    },
+    {
+      "branch": "feat-b",
+      "parent": "feat-a",
+      "pr": 102,
+      "url": "https://github.com/org/repo/pull/102",
+      "title": "Feat B (2/2)",
+      "action": "created",
+      "pushed": true,
+      "draft": false
+    }
+  ],
+  "error": null
+}
+```
+
+`branches` is the submit scope (trunk → current) in stack order, so on success
+the last entry is the branch you're on. `action` is `created`, `updated`
+(pushed, or base/title/description edited), `unchanged`, or `failed` (with an
+`error`). `draft` is only known for PRs created this run (else `null`). When
+the run stops early (nothing to submit, a bad `--body-file`, a push failure),
+top-level `error` is `{ "message": "..." }` and `branches` lists what happened
+before it. Exit code is 1 whenever `error` is set or any branch `failed`.
+`--json` implies `--no-edit` and can't be combined with `--dry-run` or
+`--restack`; run `gh-stack restack` as a separate step.
+
 **`submit -t`/`-b` also updates an existing PR in place** — pass them while on a
 branch that already has a PR to change just that one (visualization-safe).
 
@@ -178,6 +261,7 @@ gh-stack sync          # fetch trunk, rebase base onto it, restack ALL children
 gh-stack restack       # rebase current branch + descendants onto their parents
 gh-stack restack --dry-run
 gh-stack restack --no-push   # rebase locally only (also: GH_STACK_NO_PUSH=1)
+gh-stack restack --push      # push despite GH_STACK_NO_PUSH / [restack] push = false
 ```
 
 **⚠️ Restack propagates UPWARD from the current branch.** Run it from the
@@ -196,7 +280,27 @@ edit several branches then restack once at the end (only the last branch ends
 up pushed).
 
 **On rebase conflict:** resolve, `git add <files>`, `git rebase --continue`,
-then `gh-stack restack --resume` to finish the remaining branches.
+then `gh-stack restack --resume` to finish the remaining branches. That's the
+command even when the conflict came from `sync`. If you forget `--resume`, a
+bare `restack`/`sync` notices the interrupted run and, under `--yes`, resumes
+it. Don't pass `--fresh` unless you were asked to abandon the run: it discards
+the run's remaining steps. `git rebase --abort` does not end the run; a resume
+runs that rebase again.
+
+**Interrupted or partly pushed run** (killed, timed out, or a push failed):
+run `gh-stack restack --resume`. It continues from the saved state and retries
+the pushes, parents first. If everything already finished it prints the run's
+log and exits 0. A branch whose parent didn't reach origin is never pushed onto
+it (its PR would be diffed against the parent's old history); the run lists it
+as held and exits 1 until `--resume` gets the parent pushed. `merge` and `join`
+refuse to run while a restack/sync is pending.
+
+**"Origin has commits that the local branches don't"** (restack/sync exit 1
+before changing anything): a branch's copy on origin has commits it never had,
+often the squash commit a `merge --collapse` added on GitHub. Run the
+`git pull --ff-only` / `git cherry-pick` lines it prints, then re-run. Don't
+pass `--overwrite-remote` unless you were asked to drop those commits: it
+deletes them from the PR.
 
 **`sync` is self-correcting:** if you merged the bottom PR in the GitHub UI,
 `sync` detects it and advances the stack past the merged branch (re-rooting onto
@@ -235,11 +339,27 @@ Merge is **top-down everywhere** (collapse PRn → PRn-1 → … → base PR, th
 - **`--collapse`** (with `merge` or `merge --approved`): stop after collapsing
   into the base PR — review on GitHub, then re-run `merge` to finish.
 
+After a collapse, the base branch on origin holds the children's squash
+commits. Pull it before touching it locally (`git pull --ff-only origin <base>`).
+Before the base PR goes to main, `merge` checks those commits are still in it.
+If it exits 2 with "PR #N's changes are missing from PR #base", the base was
+rewritten without them: follow the printed steps (`gh api … | git am`) and
+re-run `merge`. If it exits 2 saying PR #N's changes are UNVERIFIED, nothing
+is known to be lost, but it couldn't be checked (often a GitHub or network
+hiccup: re-run first): compare `gh pr diff <N> --name-only` against the base
+PR's files. `merge --base` does the same check for a base with collapsed PRs. Use `--skip-collapse-check` only after
+confirming the base PR's diff on GitHub really has PR #N's changes.
+
+A push that fails with "fetched but never brought into local <branch>" means
+origin has commits you haven't integrated (git's --force-if-includes): pull or
+cherry-pick them, don't force past it.
+
 ### 7. Maintenance
 
 ```bash
 gh-stack delete        # remove a branch from the stack (re-parents children)
 gh-stack split         # cut a stack into two at a branch
+gh-stack join <b>      # splice an existing branch/PR into the stack (--above <b>, --dry-run)
 gh-stack rename        # rename a tracked branch (keeps metadata in sync)
 gh-stack undo          # restore from the last snapshot
 gh-stack archive       # manage archived stacks
@@ -264,7 +384,7 @@ needed.
 - **Never force-pushes trunk.**
 - **Metadata is local and never committed:** per-stack files under
   `.git/.gh-stack/` plus git branch config. Inspect it via `gh-stack stacks
---json`, not by reading the store. (`gh-stack doctor` migrates the old v2
+  --json`, not by reading the store. (`gh-stack doctor` migrates the old v2
   `.git/gh-stack-metadata.json` monolith.)
 
 ## Don'ts

package/src/types.ts

@@ -59,13 +59,71 @@ export interface Snapshot {
   baseTip?: string;
 }
 
-// Resume state for restack --resume
+/**
+ * One step of a restack/sync/join run, appended to the run's action log as it
+ * happens (#15), so an interrupted run can say what it finished and what's left.
+ */
+export interface RunLogEntry {
+  at: string; // ISO 8601
+  branch: string;
+  action:
+    | "rebased" // rebased onto `onto`
+    | "up-to-date" // already on its parent: nothing to rebase
+    | "rebase-declined"
+    | "pushed"
+    | "push-failed"
+    | "push-declined"
+    | "push-held" // not pushed: its parent isn't on origin at the commit it sits on
+    | "local-only"; // no remote and no PR: left for `submit`
+  onto?: string;
+  detail?: string;
+}
+
+/** A rebase that has started but not been seen to finish (a conflict stop, or a kill). */
+export interface InFlightRebase {
+  branch: string;
+  onto: string; // ref the branch is being rebased onto
+  onto_sha: string; // that ref's tip when the rebase started
+  pre_tip: string; // the branch's tip before the rebase (what `git rebase --abort` restores)
+  /** The `--onto` upstream (`git rebase --onto <onto> <boundary> <branch>`); null for a plain `git rebase <onto>`. */
+  boundary: string | null;
+}
+
+/** Bumped when RestackState changes shape; a file with another version is refused, not upgraded. */
+export const RUN_STATE_VERSION = 2;
+
+/**
+ * The saved state of a restack/sync/join run, at `.git/.gh-stack/restack-state.json`.
+ * Written when the run starts and after every step, and kept after it finishes
+ * (`finished_at` set) so `restack --resume` can report a completed run.
+ */
 export interface RestackState {
-  current_index: number;
+  version: typeof RUN_STATE_VERSION;
+  /** What started the run: "restack", "sync", "join" or "restack --onto". */
+  command: string;
   stack_name: string;
+  /** Branches the run covers, parents before children. */
   chain: string[];
-  /** The interrupted run was `--no-push`; `--resume` keeps it local-only (#36). */
-  no_push?: boolean;
+  /**
+   * Branches in `chain` with only their push left: never rebased by the run
+   * (restack's trunk-parented roots, sync's root) or already rebased by it.
+   */
+  push_only: string[];
+  /** First branch in `chain` not yet processed. */
+  current_index: number;
+  /** The rebase in progress at `chain[current_index]`, if any. */
+  rebase: InFlightRebase | null;
+  /** Branches whose rebase was declined: not done, so a resume offers them again. */
+  declined: string[];
+  /**
+   * The run's push decision. `--resume` keeps it (a local-only run stays
+   * local) unless the resume passes --push/--no-push (#36, #39).
+   */
+  push: boolean;
+  started_at: string;
+  /** Set once every step, pushes included, is done. */
+  finished_at: string | null;
+  log: RunLogEntry[];
 }
 
 // PR info from GitHub API