gh-stack 0.19.7 → 0.19.9

package/README.md

@@ -95,6 +95,7 @@ add [branch] [--parent <branch>]
     A PR that gh-stack already recorded for a branch in git config (in
     another worktree of the repo) is kept, so a stack submitted from a
     worktree can be tracked in the main checkout and merged from there.
+    The adding worktree takes the branch over from then on.
 
     --parent <branch>: stack it directly on <branch> (which it must
     already be based on), tracking <branch> first if needed. Use this
@@ -289,7 +290,9 @@ merge --base [--dry-run] [-d|--delete-branch] [--no-push|--push]
     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.
     All merges happen on GitHub so PRs show as "Merged", Linear tickets
-    close automatically, and GitHub Actions fire normally. Skips already-
+    close automatically, and GitHub Actions fire normally. Squash commit
+    subjects leave out the ` (N/M)` stack position that `submit` adds to
+    PR titles. Skips already-
     merged PRs (safe to re-run). Waits for GitHub between merges, and
     self-heals its spurious "Head branch is out of date" (a stale PR
     head pointer after a child squash) by re-syncing and retrying. Before
@@ -496,7 +499,8 @@ config [--json]
 doctor
     Migrate old (v2) metadata to the v3 layout, split any stack left
     with several root branches into one stack per root, reconcile git
-    branch config against the topology files, flag stacks whose base
+    branch config against the topology files (leaving branches another
+    worktree is stacking alone), flag stacks whose base
     stack appears already-merged into main, and report stacks that
     still fail the checks other commands run before loading a stack.
     Safe to run repeatedly.
@@ -650,7 +654,9 @@ Review/CI status is intentionally not shown here. Run `gh-stack update-prs`
 ### Metadata (v3)
 
 Stack metadata lives under `.git/.gh-stack/` (never committed) — a folder of
-per-stack files plus git-native branch config, rather than a single JSON blob:
+per-stack files plus git-native branch config, rather than a single JSON blob.
+A linked worktree keeps its own folder in its own git dir
+(`.git/worktrees/<name>/.gh-stack/`), so each worktree has its own stacks:
 
 ```
 .git/.gh-stack/
@@ -685,8 +691,16 @@ branch.<name>.ghstack-stack   <stack>
 branch.<name>.ghstack-parent  <parent-branch>
 branch.<name>.ghstack-pr      <number>
 branch.<name>.ghstack-id      <uuid>   stable identity (survives rename)
+branch.<name>.ghstack-gitdir  <path>   git dir of the worktree that owns it
 ```
 
+Git config is shared by every worktree, so each branch records the worktree
+that owns it. A write in one worktree never clears or overwrites a branch
+another live worktree owns. `add` (or any command that starts tracking a
+branch) takes a branch over, which is how a stack is handed from one worktree
+to another. Once a worktree is removed, or its checkout is deleted, the next
+write anywhere clears the config it left behind.
+
 The two representations cross-check each other; `gh-stack doctor` reconciles
 any drift. Why this shape:
 

package/package.json

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

package/src/commands/delete.ts

@@ -50,7 +50,8 @@ OPTIONS
     : ensureCurrentStack(meta);
   await ensureValidStack(meta, stackName);
   const stack = meta.stacks[stackName]!;
-  const currentBranch = await git.currentBranch();
+  // Detached HEAD is fine: `delete <branch>` doesn't need a current branch.
+  const currentBranch = (await git.currentBranch().catch(() => null)) ?? undefined;
 
   p.intro(pc.cyan("Delete Branch from Stack"));
 

package/src/commands/doctor.ts

@@ -17,7 +17,6 @@ import {
 import { validateStack } from "../lib/safety.ts";
 import { legacyMetadataPath, legacyRestackStatePath, restackStateFile } from "../lib/paths.ts";
 import { writeSnapshotFile } from "../lib/snapshot.ts";
-import { allBranchMemberships } from "../lib/branch-config.ts";
 
 const HELP = `
 gh-stack doctor — Migrate & repair stack metadata
@@ -28,9 +27,10 @@ USAGE
 Migrates old (v2) metadata to the v3 layout (per-stack files under
 .git/.gh-stack/ + git branch config), splits any stack left with several
 root branches into one stack per root, reconciles branch config against
-the topology files, flags stacks whose base stack looks already-merged
-into main, and reports stacks that still fail the checks other commands
-run before they load a stack.
+the topology files (leaving branches another worktree is stacking
+alone), flags stacks whose base stack looks already-merged into main,
+and reports stacks that still fail the checks other commands run
+before they load a stack.
 
 Safe to run repeatedly — it's idempotent.
 `;
@@ -204,11 +204,6 @@ function inferStack(
 // ── Reconciliation ──
 
 async function reconcile(meta: StackMetadata): Promise<void> {
-  // Re-syncing config is what writeMetadata already does: set desired
-  // membership, clear stale. Snapshot the before-state so we can report what
-  // drifted, then apply.
-  const before = await allBranchMemberships();
-
   // Report topology branches that no longer exist locally (can't auto-fix
   // safely — re-parenting children is a judgement call).
   const deadBranches: { stack: string; branch: string }[] = [];
@@ -220,31 +215,22 @@ async function reconcile(meta: StackMetadata): Promise<void> {
     }
   }
 
-  // Build desired membership to diff against `before`.
-  const desired = new Set<string>();
-  let drift = 0;
-  for (const [name, stack] of Object.entries(meta.stacks)) {
-    for (const [branch, b] of Object.entries(stack.branches)) {
-      desired.add(branch);
-      const cur = before.get(branch);
-      if (!cur || cur.stack !== name || cur.parent !== b.parent || cur.pr !== b.pr) drift++;
-    }
-  }
-  let orphans = 0;
-  for (const branch of before.keys()) {
-    if (!desired.has(branch)) orphans++;
-  }
-
-  // Apply the reconciliation (idempotent).
-  await writeMetadata(meta);
+  // Re-syncing config is what writeMetadata already does: set desired
+  // membership, clear stale, leave other worktrees' branches alone.
+  const { updated, cleared, foreign } = await writeMetadata(meta);
 
-  if (drift > 0 || orphans > 0) {
+  if (updated.length > 0 || cleared.length > 0) {
     p.log.success(
-      `Reconciled branch config: ${drift} updated, ${orphans} stale membership(s) cleared.`,
+      `Reconciled branch config: ${updated.length} updated, ${cleared.length} stale membership(s) cleared.`,
     );
   } else {
     p.log.info("Branch config already in sync with topology.");
   }
+  if (foreign.length > 0) {
+    p.log.info(
+      `Left ${foreign.length} branch(es) alone that another worktree is stacking: ${foreign.join(", ")}`,
+    );
+  }
 
   if (deadBranches.length > 0) {
     console.log();

package/src/commands/merge.ts

@@ -25,6 +25,7 @@ import type { Stack } from "../types.ts";
 import { confirmAction, isAutoYes } from "../lib/ui.ts";
 import { guardRemoteContent } from "../lib/remote-guard.ts";
 import { ensureNoPendingRun } from "./restack.ts";
+import { stripSeqSuffix } from "./update-prs.ts";
 import {
   planMerges,
   advancePastMerged,
@@ -62,6 +63,24 @@ export function isTransientMergeError(stderr: string): boolean {
   );
 }
 
+/**
+ * The squash commit subject for a PR titled `title`, without the ` (N/M)`
+ * stack position `submit` adds to PR titles, which GitHub would otherwise put
+ * on the trunk's commit. Null when the title has no position, so GitHub's own
+ * "<title> (#N)" stands.
+ */
+export function squashSubject(title: string, prNumber: number): string | null {
+  const base = stripSeqSuffix(title);
+  return base === title.trimEnd() ? null : `${base} (#${prNumber})`;
+}
+
+/** `gh pr merge` args setting the squash subject (see squashSubject); empty to keep GitHub's. */
+async function squashSubjectArgs(prNumber: number): Promise<string[]> {
+  const title = (await getPrInfo(prNumber))?.title;
+  const subject = title ? squashSubject(title, prNumber) : null;
+  return subject ? ["--subject", subject] : [];
+}
+
 /**
  * Squash-merge a PR, healing the two timing artifacts a top-down cascade
  * provokes — neither of which is a real conflict:
@@ -87,8 +106,9 @@ async function squashMergeWithRetry(
   s: ReturnType<typeof p.spinner>,
 ): Promise<{ ok: true } | { ok: false; stderr: string; genuine: boolean }> {
   const maxAttempts = MERGE_RETRY_BACKOFF_MS.length + 1;
+  const subject = await squashSubjectArgs(prNumber);
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    const ghArgs = ["pr", "merge", String(prNumber), "--squash"];
+    const ghArgs = ["pr", "merge", String(prNumber), "--squash", ...subject];
     if (deleteFlag) ghArgs.push("--delete-branch");
 
     const proc = Bun.spawn(["gh", ...ghArgs], { stdout: "pipe", stderr: "pipe" });
@@ -423,7 +443,8 @@ OPTIONS
           : "Single branch stack — enabling auto-merge on GitHub.",
       );
       if (!dryRun) {
-        const auto = await $`gh pr merge ${basePr} --squash --auto`.nothrow().quiet();
+        const subject = await squashSubjectArgs(basePr);
+        const auto = await $`gh pr merge ${basePr} --squash --auto ${subject}`.nothrow().quiet();
         if (auto.exitCode === 0) {
           p.log.success(`Auto-merge enabled for PR #${basePr}`);
         } else {
@@ -712,6 +733,7 @@ OPTIONS
 
   const enableAutoMerge = async (): Promise<{ ok: boolean; stderr: string }> => {
     const ghArgs = ["pr", "merge", String(basePr), "--squash", "--auto"];
+    if (basePr != null) ghArgs.push(...(await squashSubjectArgs(basePr)));
     if (deleteFlag) ghArgs.push("--delete-branch");
     const proc = Bun.spawn(["gh", ...ghArgs], { stdout: "pipe", stderr: "pipe" });
     const stderr = await new Response(proc.stderr).text();

package/src/lib/branch-config.ts

@@ -7,6 +7,7 @@
 //   branch.<name>.ghstack-parent  <parent-branch>
 //   branch.<name>.ghstack-pr      <number>
 //   branch.<name>.ghstack-id      <uuid>  (stable identity; survives rename)
+//   branch.<name>.ghstack-gitdir  <path>  (the git dir of the worktree that owns it)
 //
 // Why config and not JSON: git maintains the `branch.<name>` section for us.
 //   • `git branch -m old new`  → the section moves      → rename tracking free
@@ -18,13 +19,21 @@
 // alphanumerics and `-` in config keys (underscores are rejected outright),
 // and it lowercases the variable portion on read — so `ghstack-stack` round
 // -trips exactly while a camelCase key would read back mangled.
+//
+// Git config is shared by every worktree of a repo, but each worktree keeps its
+// own stack files (under its own git dir). `ghstack-gitdir` records which
+// worktree wrote a branch's membership, so a write in one worktree leaves the
+// branches another worktree is stacking alone (#64).
 import { $ } from "bun";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
 
 export interface BranchMembership {
   stack?: string;
   parent?: string;
   pr?: number;
   id?: string;
+  gitdir?: string;
 }
 
 const KEY_PREFIX = "ghstack-";
@@ -32,6 +41,7 @@ const STACK_KEY = "ghstack-stack";
 const PARENT_KEY = "ghstack-parent";
 const PR_KEY = "ghstack-pr";
 const ID_KEY = "ghstack-id";
+const GITDIR_KEY = "ghstack-gitdir";
 
 function configKey(branch: string, key: string): string {
   return `branch.${branch}.${key}`;
@@ -50,6 +60,7 @@ export async function setBranchMembership(
   await setOrUnset(branch, PARENT_KEY, membership.parent);
   await setOrUnset(branch, PR_KEY, membership.pr != null ? String(membership.pr) : undefined);
   await setOrUnset(branch, ID_KEY, membership.id);
+  await setOrUnset(branch, GITDIR_KEY, membership.gitdir);
 }
 
 async function setOrUnset(branch: string, key: string, value: string | undefined): Promise<void> {
@@ -83,6 +94,7 @@ export async function clearBranchMembership(branch: string): Promise<void> {
   await unsetKey(branch, PARENT_KEY);
   await unsetKey(branch, PR_KEY);
   await unsetKey(branch, ID_KEY);
+  await unsetKey(branch, GITDIR_KEY);
 }
 
 /**
@@ -121,6 +133,7 @@ export async function allBranchMemberships(): Promise<Map<string, BranchMembersh
     if (field === STACK_KEY) m.stack = value;
     else if (field === PARENT_KEY) m.parent = value;
     else if (field === ID_KEY) m.id = value;
+    else if (field === GITDIR_KEY) m.gitdir = value;
     else if (field === PR_KEY) {
       const n = Number(value);
       if (Number.isFinite(n)) m.pr = n;
@@ -130,3 +143,29 @@ export async function allBranchMemberships(): Promise<Map<string, BranchMembersh
 
   return out;
 }
+
+/**
+ * True if `m` belongs to a worktree other than `mine` that still exists.
+ * Membership with no owner (written before owners were recorded) or with an
+ * owner that's gone is up for grabs.
+ */
+export function ownedByOtherWorktree(m: BranchMembership | undefined, mine: string): boolean {
+  return !!m?.gitdir && m.gitdir !== mine && gitDirIsLive(m.gitdir);
+}
+
+/**
+ * A worktree's git dir is live while it exists and, for a linked worktree,
+ * while its checkout does too: `.git/worktrees/<name>/gitdir` names the
+ * checkout's `.git` file, which is what `git worktree prune` checks. The main
+ * checkout's git dir has no `gitdir` file.
+ */
+function gitDirIsLive(dir: string): boolean {
+  if (!existsSync(dir)) return false;
+  const pointer = path.join(dir, "gitdir");
+  if (!existsSync(pointer)) return true;
+  try {
+    return existsSync(readFileSync(pointer, "utf8").trim());
+  } catch {
+    return false;
+  }
+}

package/src/lib/git.ts

@@ -39,6 +39,15 @@ export async function gitDir(): Promise<string> {
   return result.trim();
 }
 
+/**
+ * Absolute path to this worktree's git dir. `gitDir()` is relative (`.git`) in
+ * the main checkout, which can't identify a worktree from another one.
+ */
+export async function absoluteGitDir(): Promise<string> {
+  const result = await $`git rev-parse --absolute-git-dir`.text();
+  return result.trim();
+}
+
 /**
  * Get the absolute path to the repository's working-tree root.
  */

package/src/lib/metadata.ts

@@ -29,6 +29,7 @@ import {
   allBranchMemberships,
   setBranchMembership,
   clearBranchMembership,
+  ownedByOtherWorktree,
   type BranchMembership,
 } from "./branch-config.ts";
 import { loadSnapshots } from "./snapshot.ts";
@@ -256,7 +257,7 @@ function serializeStack(stack: Stack): string {
  * tombstone any stack file that's no longer present, and reconcile git branch
  * config to match active membership.
  */
-export async function writeMetadata(meta: StackMetadata): Promise<void> {
+export async function writeMetadata(meta: StackMetadata): Promise<BranchConfigSync> {
   await ensureDirs();
 
   // 0. stamp a stable id on any active branch that lacks one, so a later
@@ -269,6 +270,13 @@ export async function writeMetadata(meta: StackMetadata): Promise<void> {
   const aDir = await activeDir();
   const arDir = await archivedDir();
 
+  // Branches this worktree tracked before this write. Any other active branch
+  // is joining it now, which claims its config from another worktree.
+  const tracked = new Set<string>();
+  for (const stack of Object.values(await readStackDir(aDir))) {
+    for (const name of Object.keys(stack.branches ?? {})) tracked.add(name);
+  }
+
   // 2. write active + archived stack files (write desired state BEFORE
   //    removing anything — that's what makes "can't vanish" hold).
   for (const [name, stack] of Object.entries(meta.stacks)) {
@@ -286,7 +294,7 @@ export async function writeMetadata(meta: StackMetadata): Promise<void> {
   await reconcileStale(arDir, archivedNames, (name) => activeNames.has(name));
 
   // 4. mirror active membership into git config
-  await syncBranchConfig(meta);
+  return syncBranchConfig(meta, tracked);
 }
 
 /**
@@ -321,38 +329,80 @@ async function reconcileStale(
   }
 }
 
+/** What `syncBranchConfig` changed. */
+export interface BranchConfigSync {
+  /** Branches whose membership was written. */
+  updated: string[];
+  /** Branches whose stale membership was removed. */
+  cleared: string[];
+  /** Branches left alone because another live worktree owns them. */
+  foreign: string[];
+}
+
 /**
- * Reconcile git branch config so it exactly mirrors active-stack membership.
+ * Reconcile git branch config so it mirrors this worktree's active membership.
  * Only branches whose recorded membership differs are touched, to avoid
  * shelling out to `git config` for every branch on every write.
+ *
+ * Git config is shared by every worktree, so a branch another live worktree
+ * owns is left alone (#64): it isn't cleared when this worktree doesn't track
+ * it, and it isn't overwritten when both do. The exception is a branch joining
+ * this worktree's stacks in this write (`add`, `create`, adopting a chain),
+ * which is the handoff, so this worktree takes it over. `tracked` is what this
+ * worktree tracked before the write.
  */
-async function syncBranchConfig(meta: StackMetadata): Promise<void> {
+async function syncBranchConfig(
+  meta: StackMetadata,
+  tracked: Set<string>,
+): Promise<BranchConfigSync> {
+  const mine = await git.absoluteGitDir();
   const desired = new Map<string, BranchMembership>();
   for (const [stackName, stack] of Object.entries(meta.stacks)) {
     for (const [branchName, b] of Object.entries(stack.branches)) {
-      desired.set(branchName, { stack: stackName, parent: b.parent, pr: b.pr, id: b.id });
+      desired.set(branchName, {
+        stack: stackName,
+        parent: b.parent,
+        pr: b.pr,
+        id: b.id,
+        gitdir: mine,
+      });
     }
   }
 
   const existing = await allBranchMemberships();
+  const result: BranchConfigSync = { updated: [], cleared: [], foreign: [] };
 
   for (const [branch, m] of desired) {
     const cur = existing.get(branch);
+    if (tracked.has(branch) && ownedByOtherWorktree(cur, mine)) {
+      result.foreign.push(branch);
+      continue;
+    }
     if (
       !cur ||
       cur.stack !== m.stack ||
       cur.parent !== m.parent ||
       cur.pr !== m.pr ||
-      cur.id !== m.id
+      cur.id !== m.id ||
+      cur.gitdir !== m.gitdir
     ) {
       await setBranchMembership(branch, m);
+      result.updated.push(branch);
     }
   }
 
   // Branches that still carry gh-stack config but are no longer active members.
-  for (const branch of existing.keys()) {
-    if (!desired.has(branch)) await clearBranchMembership(branch);
+  for (const [branch, m] of existing) {
+    if (desired.has(branch)) continue;
+    if (ownedByOtherWorktree(m, mine)) {
+      result.foreign.push(branch);
+      continue;
+    }
+    await clearBranchMembership(branch);
+    result.cleared.push(branch);
   }
+
+  return result;
 }
 
 /**
@@ -564,11 +614,6 @@ export async function removeBranchFromStack(
     }
     delete stack.branches[branchName];
 
-    // The removed branch may still exist in git but is no longer a member —
-    // drop its membership config explicitly (syncBranchConfig also would, but
-    // be direct since the branch is gone from `meta`).
-    await clearBranchMembership(branchName);
-
     if (stack.last_branch === branchName) {
       const remaining = Object.keys(stack.branches);
       stack.last_branch = remaining.length > 0 ? remaining[remaining.length - 1]! : null;

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

@@ -133,6 +133,8 @@ no-publish path.)
 but the PR numbers gh-stack records in git config are shared. So after
 submitting from a worktree, `gh-stack add <top-branch>` in the main checkout
 tracks the whole chain _with_ its PRs, and `sync`/`merge --base` work there.
+Each branch's config records the worktree that owns it, so worktrees running
+gh-stack side by side don't clear each other's; `add` takes a branch over.
 
 **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