gh-stack 0.17.2 → 0.19.0

package/README.md

@@ -67,6 +67,10 @@ gh-stack status
 gh-stack split feat-12           # feat-12.. → new stack based on feat-11
 # ...later, after the original stack merges to main:
 gh-stack restack --onto main     # re-root the split stack onto main
+
+# Splice a branch (and its open PR) that was cut from main on its own into the stack
+gh-stack join fix-auth --dry-run # preview the resulting stack + each PR's diff
+gh-stack join fix-auth           # make it the new bottom (or --above <branch>)
 ```
 
 ## Commands
@@ -83,24 +87,37 @@ create <branch-name> [--description <desc>]
     Create a new git branch off the current branch and add it to
     the stack. The current branch must already be tracked.
 
-add [branch]
+add [branch] [--parent <branch>]
     Track an EXISTING local branch (default: the current branch) in a
     stack — without pushing or opening a PR. Walks local ancestry: if the
     branch sits on top of an existing stack it's adopted into it (parent
     auto-detected); otherwise a new stack is created from the chain.
 
+    --parent <branch>: stack it directly on <branch> (which it must
+    already be based on), tracking <branch> first if needed. Use this
+    for a branch with no commits of its own yet — it sits AT its
+    parent's tip, so ancestry can't tell which is the parent and it
+    would otherwise be rooted at trunk (init/add warn when this
+    happens). It also re-homes an already-tracked branch, but only
+    when it's alone in its stack and has no PR.
+
     Use this for a WIP branch you've created with `git checkout -b` but
     aren't ready to submit. It fills the gap between creating a branch and
     `submit`: until a branch is tracked, `sync`/`restack`/navigation don't
     know about it, and `add` is how you track it without publishing. (When
     you do run `submit`, it auto-tracks too — `add` is the no-push path.)
 
-submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file <f>] [--restack] [--dry-run]
+submit [-d|--draft|--no-draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file <f>] [--restack] [--json] [--dry-run]
     Push all downstack branches to GitHub, create PRs for branches
     that don't have them, number each PR title with its stack position
     `(N/M)`, and update all PR descriptions with stack visualization.
     Idempotent — safe to run repeatedly.
 
+    --draft creates new PRs as drafts; --no-draft creates them ready for
+    review. Draft is create-time only: submit never changes the draft
+    state of an existing PR. A repo can make drafts the default with
+    `[submit] draft = true` in .gh-stack.toml (see Configuration).
+
     --restack: after submitting, restack the branches above the current
     one onto it. submit covers DOWNSTACK (trunk → current); restack covers
     UPSTACK (the children), so together they sync the whole stack from
@@ -123,6 +140,24 @@ submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file
     let an agent or script regenerate a PR's title/description safely.
     --body-file reads the body from a file. In --yes mode without --title,
     titles are auto-generated from branch names.
+
+    --json prints the result as one JSON document on stdout, on every
+    exit, so a script or agent gets the PR it just created without a
+    follow-up `gh pr view`:
+      { stack, current_branch,
+        branches: [{ branch, parent, pr, url, title, action, pushed,
+                     draft, error? }],
+        error: null | { message } }
+    branches is the submit scope (trunk → current) in stack order. action
+    is created (new PR), updated (pushed, or base/title/description
+    edited), unchanged, or failed (see the entry's error). draft is
+    true/false for PRs created this run, null otherwise. The top-level
+    error is set when the run stopped early (bad flags, nothing to
+    submit, a push failure): branches then lists what happened before
+    it, and stack/current_branch may be null. Exits 1 if error is set or
+    any branch failed. Logs go to stderr, plain and uncolored. Implies
+    --no-edit; can't be combined with --dry-run or --restack (run
+    `gh-stack restack` separately).
 ```
 
 ### Stack Navigation
@@ -152,15 +187,69 @@ ls
 ### Stack Management
 
 ```
-restack [--resume] [--dry-run] [--verbose]
+restack [--resume | --fresh] [--dry-run] [--no-push|--push] [--overwrite-remote] [--verbose]
     Rebase the current branch and all descendants onto their parents.
     Uses metadata snapshots to recover the correct rebase base even
     after a parent's history has been rewritten.
 
+    --no-push (or GH_STACK_NO_PUSH=1, or `[restack] push = false` in
+    config): rebase locally only, and list the refs left ahead of
+    origin. It overrides --yes for pushes, so an agent can restack
+    unattended without publishing anything. --push pushes even when the
+    env var or a config default says not to. --resume keeps the push
+    decision of the run it resumes (an interrupted local-only run stays
+    local) unless the resume itself passes --push or --no-push.
+
     On conflict:
         git rebase --continue
         gh-stack restack --resume
 
+    Interrupted runs: restack and sync save their progress (and a log
+    of every rebase and push) in .git/.gh-stack/restack-state.json
+    after each step, until the last push. `--resume` continues from
+    there: after a conflict, a kill, or failed pushes. If the run had
+    already finished, it prints the run's log and exits 0. A bare
+    `restack` or `sync` with an interrupted run pending asks whether to
+    resume it (with --yes it resumes) instead of starting a different
+    run on top of it. `--fresh` discards the interrupted run and starts
+    over. `git rebase --abort` ends the rebase, not the run: a resume
+    runs that rebase again (so does one killed before git started it),
+    and earlier branches' failed or held pushes stay queued. To abandon
+    the run, use `--fresh`. A state file from an older gh-stack is
+    refused with that same pointer, never upgraded. `merge` and `join`
+    refuse to run while a restack/sync is pending, and `undo` discards
+    the run it rolls back.
+
+    A branch is never pushed onto a parent that isn't on origin at the
+    commit the branch sits on (the parent's push failed or was declined,
+    or it has unpushed commits): its PR would be diffed against the
+    parent's old history. It's held back, the run exits 1 listing the
+    refs that aren't in sync, and `--resume` retries the pushes, parents
+    first.
+
+    Commits only on origin: before rewriting anything, restack and sync
+    check each branch's copy on origin. If it has commits the local
+    branch never had, e.g. the squash commit `merge --collapse` adds to
+    a parent PR's branch on GitHub, rewriting would drop them from the
+    PR, so the run stops, names them, and prints the pull or
+    cherry-pick that brings them in. Earlier versions of local commits
+    left on origin by a --no-push or interrupted run (found in the
+    branch's reflog or a snapshot, or patch-equivalent) don't count, and
+    neither do commits from origin's main (GitHub's "Update branch").
+    A branch whose origin copy couldn't be checked at all (not fetched,
+    or git failed) is treated the same way, never as clean. Interactive
+    runs ask; --yes stops. --overwrite-remote rewrites anyway, dropping
+    them. Sync skips bottom branches whose PRs already merged: it
+    advances past them rather than rewriting them. When an advance past
+    a merged bottom can't push the new bottom, its PR keeps its old base
+    until a later push of that branch lands, which retargets it.
+
+    Every gh-stack force-push (restack, sync, merge, submit, join) uses
+    --force-with-lease --force-if-includes: git refuses to overwrite an
+    origin tip you fetched but never brought into the local branch, and
+    gh-stack explains the refusal. A tip the check above cleared is
+    pushed with an explicit lease on exactly that commit instead.
+
     (alias: rebase)
 
 restack --onto <ref>
@@ -169,9 +258,9 @@ restack --onto <ref>
     onto main once the parent stack has merged — only the stack's own
     commits replay onto the new base.
 
-sync [--dry-run]
-    Fetch main, rebase the base branch onto main, then restack all
-    children. Snapshots every branch's pre-sync tip so children can be
+sync [--dry-run] [--no-push|--push] [--resume | --fresh] [--overwrite-remote]
+    Fetch main, rebase the base branch onto main, push it, then restack
+    all children (every branch above it, in one resumable run). Snapshots every branch's pre-sync tip so children can be
     correctly rebased even though their parent's history was rewritten.
     If the bottom PR(s) already merged on main outside gh-stack (e.g.
     the GitHub web UI), sync detects this and advances the stack past
@@ -179,7 +268,13 @@ sync [--dry-run]
     own commits replay — instead of replaying the now-squashed commits
     and conflicting.
 
-merge [--dry-run] [-d|--delete-branch] [--collapse]
+    --no-push / --push (and their defaults): as for restack. Also skips
+    retargeting a PR's base after advancing past a merged bottom;
+    the next `submit` pushes and retargets together. --resume and
+    --fresh: as for restack (`sync --resume` is `restack --resume`).
+    Commits only on origin / --overwrite-remote: as for restack.
+
+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]
     Default (top-down collapse): squash-merge the whole stack top-down
@@ -195,6 +290,26 @@ merge --base [--dry-run] [-d|--delete-branch]
     resolve with `gh-stack sync`, then re-run), while merely waiting on
     pending checks is fine (auto-merge gates on them).
 
+    Collapse check: before the base PR goes to main (and at the end of
+    --collapse), merge checks that each collapsed child's squash commit
+    is still in what it was squashed into: the base branch on origin,
+    or the parent PR's head when it merged. A rebased copy (same
+    patch-id) counts, and so does a base tree holding every file the
+    squash commit wrote. It fails closed:
+      - proven missing (the base has every file the squash commit
+        touched exactly as before it): merge stops (exit 2), names the
+        PR, and prints how to put the commit back (via its patch from
+        GitHub when the commit itself can't be fetched);
+      - anything it can't establish (a GitHub or fetch failure, a
+        shallow clone, content that matches neither version): the PR is
+        UNVERIFIED, not called missing. Interactive runs ask (default
+        stop, with a retry when the failure looks transient); --yes
+        stops (exit 2) with the checks to run by hand.
+    `merge --base` runs the same check when the base PR carries PRs
+    collapsed into it by an earlier `merge --collapse` (found from
+    GitHub: merged PRs whose base was their stack parent).
+    --skip-collapse-check turns the check off.
+
     --approved  Collapse only the approved run. Walks approval from the
                 BASE up and stops at the first PR that isn't approved
                 (contiguous — an unapproved PR4 caps the run at PR3 even
@@ -229,6 +344,59 @@ split [<branch>] [--name <name>]
     tip. Once the original stack merges, re-root the new stack with
     `gh-stack restack --onto main`.
 
+join <branch> [--above <branch>] [--dry-run] [--push|--no-push] [--verbose]
+    Splice an existing branch — usually one that already has a PR —
+    into a stack. Without --above it becomes the new bottom of the
+    current stack; with --above <branch> it goes between <branch> and
+    its children (--above main = the bottom). The <branch> named by
+    --above picks the stack, so that form works from anywhere.
+
+    The incoming branch is synced FIRST: only its own commits (those
+    above its fork point with main) replay onto the current tip of its
+    new parent. Otherwise a branch that's behind main would carry the
+    main commits it was missing into every child's diff once they're
+    restacked onto it. Then the branches above it are restacked onto it
+    (restack's own loop), each branch is pushed with --force-with-lease,
+    and the PR bases are retargeted on GitHub (the incoming PR onto its
+    new parent, each re-parented child PR onto the incoming branch).
+    Pushing follows the same setting as restack: --no-push,
+    GH_STACK_NO_PUSH, or `[restack] push = false` in .gh-stack.toml or
+    the user config keeps the join local; --push overrides them.
+    An open PR for the incoming branch is adopted into the metadata.
+
+    A stack named after its old bottom branch is renamed after the new
+    bottom (the old stack file is tombstoned under deleted/); a custom
+    name, or a name already used by another active or archived stack,
+    is kept. A branch alone in its own one-branch stack (what `submit`
+    makes of a standalone PR) is absorbed; a branch in a larger stack
+    is refused.
+
+    Without --no-push the incoming branch must already be on origin
+    (`git push -u origin <branch>` first), and if its push is declined
+    or rejected, join stops before touching anything above it. A branch
+    above the insertion point that was cut from an older, since-
+    rewritten version of the incoming branch is refused, with the
+    `git rebase --onto` that drops its stale copies. (A child cut from
+    an earlier tip that was only appended to is handled automatically.)
+    Unknown options are an error.
+
+    --dry-run   Show the resulting stack and, for every affected PR,
+                its projected commits / files changed vs its new parent,
+                plus how far the incoming branch is behind main. Changes
+                nothing (uses the last fetch of origin/main).
+    --no-push   As for restack: rebase and update metadata locally, and
+                leave origin and the PR bases alone. The next `submit`
+                pushes and retargets together.
+
+    Takes a snapshot first (`gh-stack undo` restores every branch,
+    including the incoming one). Refuses on a dirty tree, and when the
+    branches above the insertion point need a restack first. On a
+    conflict syncing the incoming branch the stack is left unchanged:
+    resolve, `git rebase --continue`, and re-run the same join (or
+    `git rebase --abort`). A conflict restacking the branches above it
+    resumes like restack: `git rebase --continue`, then
+    `gh-stack restack --resume`.
+
 rename [<old-name>] <new-name>
     Rename a tracked branch (runs `git branch -m`) and re-key the stack
     topology so it stays tracked, re-parenting any children that pointed
@@ -266,9 +434,13 @@ log
 
 update-prs [--force]
     Refresh the "📚 Stacked on" visualization block in every PR
-    description for the current stack. PRs whose rendered block is
-    unchanged are skipped; --force rewrites all of them. (submit does
-    this automatically — use this to refresh without pushing.)
+    description for the current stack. Each PR's live description is
+    checked, so a block removed by an outside edit (`gh pr edit`, the
+    GitHub UI) is restored; PRs already showing the current block are
+    skipped, and --force rewrites all of them. A tracked branch with no
+    recorded PR is looked up on GitHub first, so a PR opened with
+    `gh pr create` is adopted. (submit refreshes the block too, but
+    compares against what it last wrote — use update-prs to repair.)
 
 stacks [--current] [--json]
     List all stacks and their topology. Read-only and network-free —
@@ -292,6 +464,13 @@ undo
 archive [--restore <name>]
     List archived stacks by default, or restore one by name.
 
+config [--json]
+    Show every configurable flag default, its resolved value, and where
+    it came from (flag/env/repo config/user config/built-in), plus the
+    config file paths. Answers "why did this PR open as a draft?" in
+    one command. Works outside a git repo too (user and env layers
+    only). Read-only; edit the TOML files directly.
+
 doctor
     Migrate old (v2) metadata to the v3 layout, reconcile git branch
     config against the topology files, and flag stacks whose base
@@ -306,9 +485,21 @@ learn [--skill] [--harness <name>] [--global] [--force]
       Claude Code  <root>/.claude/skills/using-gh-stack/SKILL.md
       Codex        <root>/.codex/skills/using-gh-stack/SKILL.md
       Cursor       <root>/.cursor/skills/using-gh-stack/SKILL.md
-    --harness  claude | codex | cursor (skips the interactive prompt)
+    --harness  claude | codex | cursor | all, or a comma list such as
+               claude,codex (skips the interactive prompt). Each target
+               is checked and installed on its own.
     --global   Install under ~/.<harness>/ instead of the project root
-    --force    Overwrite an existing skill file without confirming
+    --force    Overwrite an existing skill file without confirming, and
+               write through a symlinked skill dir or SKILL.md
+    If the skill dir or SKILL.md is a symlink (say, into a skills repo
+    you keep under version control), the install refuses and names the
+    link target. Only --force writes through it; --yes / GH_STACK_YES
+    does not. A dangling link is never written through: remove it to
+    install there. Harnesses that resolve to the same SKILL.md (a linked
+    skill dir or a shared skills/ dir) are written once and reported as
+    installed via the first. Cancelling an overwrite prompt lists what
+    was installed and what was not attempted, and exits non-zero. The
+    closing refresh hint repeats the --global and --harness you used.
 ```
 
 ## Global Options
@@ -322,14 +513,58 @@ learn [--skill] [--harness <name>] [--global] [--force]
 
 `--plain` is auto-enabled when `--yes` / `GH_STACK_YES=1` is set, so agents get clean, easily-filtered output by default. Use `--plain` alone if you want plain output but still interactive prompts.
 
+If a command needs to prompt but stdin isn't a TTY, it exits 1 with the prompt it would have shown, instead of waiting for an answer that can't arrive. Set `GH_STACK_YES=1` (or pass `--yes`) in that context.
+
 ## Environment Variables
 
 ```
 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_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
 ```
 
+## Configuration
+
+Flags that encode a repo's conventions can get a default, so nobody has to
+remember to type them:
+
+```toml
+# .gh-stack.toml at the repo root (commit it), or
+# ~/.config/gh-stack/config.toml for personal defaults (honors XDG_CONFIG_HOME)
+[submit]
+draft = true      # new PRs open as drafts; --no-draft overrides for one PR
+
+[restack]
+push = false      # restack and sync stay local; --push overrides
+```
+
+Precedence, highest first: **CLI flag > env var > repo config > user config >
+built-in default**. `gh-stack config` prints each resolved value and its
+source. When a default (rather than a flag) decides draft or push, the command
+says so in its output.
+
+| Key              | Flags                    | Env                           | Built-in |
+| ---------------- | ------------------------ | ----------------------------- | -------- |
+| `[submit] draft` | `--draft` / `--no-draft` | `GH_STACK_DRAFT`              | `false`  |
+| `[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
+`restack --resume` keeps the push decision of the run it resumes unless you
+pass `--push` or `--no-push`.
+
+Unknown keys print a warning and are ignored. Malformed TOML, an unreadable
+config file, a non-boolean value for a known key, or an env value other than
+`1/0`, `true/false`, `yes/no` is an error naming the file or variable. It is
+reported before the command changes anything, and a command given an explicit
+flag (`--draft`, `--push`, ...) never reads the config for that setting. `--yes` can't be set in a config file:
+auto-confirming destructive operations has to be asked for per run, with
+`--yes` or `GH_STACK_YES=1`.
+
 ## How It Works
 
 ### Smart Init
@@ -397,7 +632,7 @@ per-stack files plus git-native branch config, rather than a single JSON blob:
   archived/<stack>.json        merged/closed stacks
   deleted/<stack>.json         tombstones (recoverable)
   snapshots/<ts>__<stack>.json append-only, retained per-stack
-  restack-state.json           in-flight restack/sync resume state
+  restack-state.json           the last restack/sync/join run: resume point + action log
 ```
 
 A single `active/<stack>.json` looks like:
@@ -506,6 +741,7 @@ and gotchas straight from the binary:
 # Teach an agent the current API (always in sync with the installed version)
 gh-stack learn                              # print the skill to stdout
 gh-stack learn --skill --harness claude     # install it for Claude Code
+gh-stack learn --skill -g --harness all     # every harness, in your home dir
 ```
 
 ```bash
@@ -518,7 +754,14 @@ gh-stack submit -n               # Or auto-generate titles
 gh-stack sync
 gh-stack restack
 
+# Rebase without publishing (e.g. before a human approves the push)
+GH_STACK_NO_PUSH=1 gh-stack restack
+
+# Check which defaults apply here (.gh-stack.toml, user config, env)
+gh-stack config
+
 # Structured output
+gh-stack submit --json -t "Title" --body-file body.md   # PR number + URL per branch
 gh-stack status --json
 gh-stack status --current --json
 gh-stack ls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gh-stack",
-  "version": "0.17.2",
+  "version": "0.19.0",
   "description": "Stacked PR manager for squash-merge workflows",
   "author": "Kiliman <kiliman@gmail.com>",
   "license": "MIT",
@@ -33,7 +33,8 @@
   },
   "scripts": {
     "dev": "bun run src/index.ts",
-    "build": "bun build --compile src/index.ts --outfile dist/gh-stack",
+    "build": "bun build --compile src/index.ts --outfile dist/gh-stack && bun run sign",
+    "sign": "[ \"$(uname)\" != Darwin ] || codesign --force --sign - dist/gh-stack",
     "test": "bun test",
     "lint": "oxlint src/",
     "format": "oxfmt --write src/",
@@ -50,17 +51,17 @@
     ]
   },
   "devDependencies": {
-    "@types/bun": "latest",
+    "@types/bun": "1.3.10",
     "husky": "^9.1.7",
-    "lint-staged": "^16.3.3",
-    "oxfmt": "^0.40.0",
-    "oxlint": "^1.55.0"
+    "lint-staged": "^17.6.0",
+    "oxfmt": "^0.74.0",
+    "oxlint": "^1.89.0"
   },
   "peerDependencies": {
     "typescript": "^5"
   },
   "dependencies": {
-    "@clack/prompts": "^1.1.0",
+    "@clack/prompts": "^1.8.1",
     "picocolors": "^1.1.1"
   }
-}
+}

package/src/commands/add.ts

@@ -13,7 +13,7 @@ import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { gateLegacyMetadata } from "../lib/safety.ts";
 import { readMetadata, writeMetadata, findStackForBranch, stackBase } from "../lib/metadata.ts";
-import { resolveOrCreateStack } from "../lib/chain.ts";
+import { colocatedBranches, resolveOrCreateStack } from "../lib/chain.ts";
 import type { StackMetadata } from "../types.ts";
 
 export default async function add(args: string[]): Promise<void> {
@@ -22,26 +22,40 @@ export default async function add(args: string[]): Promise<void> {
 gh-stack add — track an existing local branch in a stack (no push, no PR)
 
 USAGE
-  gh-stack add [branch]
+  gh-stack add [branch] [--parent <branch>]
 
 Registers the branch (default: the current branch) into a stack so sync,
 restack, and navigation work before you've submitted it. Walks local ancestry:
 if the branch sits on top of an existing stack it's adopted into that stack;
 otherwise a new stack is created from the chain, rooted at the trunk.
 
+OPTIONS
+  --parent <branch>  Stack the branch directly on <branch> instead of detecting
+                     it (which must already be based on it). Needed when the
+                     branch has no commits of its own yet, since it then sits AT
+                     its parent's tip and ancestry can't tell them apart.
+                     Also re-homes an already-tracked branch, when it's alone in
+                     its stack and has no PR (e.g. a mistaken ${"`"}init${"`"} at trunk).
+
 Network-free — nothing is pushed and no PR is opened. Run ${"`"}gh-stack submit${"`"} when
 you're ready to publish.
 
 EXAMPLES
   gh-stack add                    Track the current branch
   gh-stack add my-wip-branch      Track a specific local branch
+  gh-stack add --parent feat-1    Track the current branch on top of feat-1
 `);
     return;
   }
 
   await gateLegacyMetadata();
 
-  const positional = args.find((a) => !a.startsWith("-"));
+  let parentFlag: string | undefined;
+  let positional: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--parent" && args[i + 1]) parentFlag = args[++i];
+    else if (!args[i]!.startsWith("-")) positional ??= args[i];
+  }
   const branch = positional ?? (await git.currentBranch());
 
   if (!(await git.localBranchExists(branch))) {
@@ -65,9 +79,15 @@ EXAMPLES
     stacks: {},
   };
 
+  if (parentFlag) {
+    await addUnderParent(meta, branch, parentFlag, trunk);
+    return;
+  }
+
   const already = findStackForBranch(meta, branch);
   if (already) {
     p.log.info(`${pc.yellow(branch)} is already tracked in stack ${pc.yellow(already)}.`);
+    await warnIfColocated(branch, trunk);
     return;
   }
 
@@ -100,7 +120,115 @@ EXAMPLES
   for (const b of resolution.addedBranches) {
     console.log(`  ${pc.green("+")} ${b}`);
   }
+  if (resolution.created && resolution.chain.length === 1) await warnIfColocated(branch, trunk);
+
+  p.outro(
+    `Tracked — ${pc.green("gh-stack sync")}/${pc.green("restack")} now work. ${pc.dim("Run")} ${pc.green("gh-stack submit")} ${pc.dim("to open PRs.")}`,
+  );
+}
 
+/**
+ * A branch with no commits of its own sits AT its parent's tip, so ancestry
+ * can't find the parent and it gets rooted at trunk. Say so, and how to fix it,
+ * rather than leaving a stack that `sync` would later rebase onto trunk —
+ * replaying the parent's commits. (#37)
+ */
+export async function warnIfColocated(branch: string, trunk: string): Promise<void> {
+  const same = await colocatedBranches(branch, trunk);
+  if (same.length === 0) return;
+  p.log.warn(
+    `${pc.yellow(branch)} has no commits of its own — it shares its tip with ${same.map((b) => pc.yellow(b)).join(", ")}, so it was rooted at ${trunk}.\n` +
+      `  If it belongs on one of those, re-home it:\n` +
+      same.map((b) => `    ${pc.green(`gh-stack add ${branch} --parent ${b}`)}`).join("\n"),
+  );
+}
+
+/**
+ * `add --parent`: stack `branch` directly on `parent`, tracking `parent` first
+ * (from its own ancestry) if needed. An already-tracked branch is re-homed only
+ * when that can't lose anything: it's alone in its stack and has no PR — the
+ * shape a mistaken `init` at trunk leaves behind. Metadata-only; the branch
+ * must already be based on `parent`. (#37)
+ */
+async function addUnderParent(
+  meta: StackMetadata,
+  branch: string,
+  parent: string,
+  trunk: string,
+): Promise<void> {
+  if (parent === branch) {
+    p.cancel(`A branch can't be its own parent.`);
+    process.exit(1);
+  }
+  if (parent === trunk || parent === "main" || parent === "master") {
+    p.cancel(
+      `--parent is for stacking on a feature branch. To root ${pc.yellow(branch)} at ${trunk}, run ${pc.green("gh-stack add")} without --parent.`,
+    );
+    process.exit(1);
+  }
+  if (!(await git.localBranchExists(parent))) {
+    p.cancel(`Branch ${pc.yellow(parent)} doesn't exist locally.`);
+    process.exit(1);
+  }
+  if (!(await git.isAncestor(parent, branch))) {
+    p.cancel(
+      `${pc.yellow(branch)} isn't based on ${pc.yellow(parent)} — rebase it first:\n\n    ${pc.green(`git rebase ${parent} ${branch}`)}`,
+    );
+    process.exit(1);
+  }
+
+  const oldStackName = findStackForBranch(meta, branch);
+  const oldBranch = oldStackName ? meta.stacks[oldStackName]!.branches[branch]! : null;
+
+  if (oldStackName && oldBranch) {
+    if (oldBranch.parent === parent) {
+      p.log.info(`${pc.yellow(branch)} is already stacked on ${pc.yellow(parent)}.`);
+      return;
+    }
+    const oldStack = meta.stacks[oldStackName]!;
+    const alone = Object.keys(oldStack.branches).length === 1;
+    if (!alone || oldBranch.pr != null) {
+      p.cancel(
+        `${pc.yellow(branch)} is already tracked in stack ${pc.yellow(oldStackName)}` +
+          (oldBranch.pr != null ? ` with PR #${oldBranch.pr}` : " alongside other branches") +
+          ` — re-homing it could strand them, so add --parent won't move it.`,
+      );
+      process.exit(1);
+    }
+  }
+
+  // Track the parent first, from its own ancestry, if it isn't yet. Resolved
+  // before dropping the branch's old stack so a failure leaves nothing changed.
+  let targetStackName = findStackForBranch(meta, parent);
+  const adoptedParents: string[] = [];
+  if (!targetStackName) {
+    try {
+      const res = await resolveOrCreateStack(meta, parent, trunk);
+      targetStackName = res.stackName;
+      adoptedParents.push(...res.addedBranches);
+    } catch (err) {
+      p.cancel((err as Error).message);
+      process.exit(1);
+    }
+  }
+
+  // Drop the throwaway one-branch stack. Deleted, not archived: restoring it
+  // would track the branch in two stacks at once.
+  if (oldStackName && oldStackName !== targetStackName) delete meta.stacks[oldStackName];
+
+  const target = meta.stacks[targetStackName]!;
+  target.branches[branch] = { ...oldBranch, parent };
+  target.last_branch = branch;
+  meta.current_stack = targetStackName;
+  await writeMetadata(meta);
+
+  p.intro(pc.cyan("Add to Stack"));
+  for (const b of adoptedParents) console.log(`  ${pc.green("+")} ${b}`);
+  p.log.success(
+    oldStackName
+      ? `Re-homed ${pc.yellow(branch)} onto ${pc.yellow(parent)} in stack ${pc.yellow(targetStackName)} ${pc.dim(`(removed one-branch stack ${oldStackName})`)}`
+      : `Added ${pc.yellow(branch)} onto ${pc.yellow(parent)} in stack ${pc.yellow(targetStackName)}`,
+  );
   p.outro(
     `Tracked — ${pc.green("gh-stack sync")}/${pc.green("restack")} now work. ${pc.dim("Run")} ${pc.green("gh-stack submit")} ${pc.dim("to open PRs.")}`,
   );