gh-stack 0.19.9 → 0.19.10

package/README.md

@@ -731,6 +731,14 @@ you at `doctor`.
 
 Before any destructive operation (restack, sync, merge, delete), gh-stack saves a snapshot of all branch HEADs as an append-only file under `snapshots/`, retained per-stack. Run `gh-stack undo` to restore.
 
+### Busy Repositories (git locks)
+
+Git doesn't wait for a lock: a checkout or rebase that finds `index.lock` held fails at once. The usual holder is a background `git status` (an editor, a watcher, another agent session), which takes the lock for a few milliseconds. So every git step gh-stack runs that takes a lock (checkout, rebase, reset, commit, branch and tag writes, branch config) waits and retries: after 0.1, 0.2, 0.4, 0.8, 1.6 and 2 seconds, about 5 seconds in all. A rebase that a lock interrupts midway is continued, not reported as a conflict.
+
+If the lock is still held after that, gh-stack names it and stops with exit 1, never "Rebase Conflict". Nothing conflicted, and the step changed nothing: once the lock is gone, run the command again, or `gh-stack restack --resume` for an interrupted restack or sync. A lock left by a crashed git process stays until you remove it.
+
+gh-stack also runs its own git calls with `GIT_OPTIONAL_LOCKS=0`, so its reads never take the lock.
+
 ## Example Workflow
 
 ```bash

package/package.json

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

package/src/commands/join.ts

@@ -277,7 +277,7 @@ export default async function join(args: string[]): Promise<void> {
   await verifyResult(plan);
 
   if (startBranch && startBranch !== (await git.currentBranch().catch(() => null))) {
-    await $`git checkout ${startBranch}`.nothrow().quiet();
+    await git.tryCheckout(startBranch);
   }
 
   const endMeta = await freshMeta();

package/src/commands/submit.ts

@@ -226,8 +226,11 @@ export default async function submit(args: string[]): Promise<void> {
     await runSubmit(args, run, jsonMode);
   } catch (err) {
     // A ConfigError (bad config file or env value) is an expected stop too: in
-    // --json mode it becomes the document's error, like any refusal.
-    const expected = err instanceof SubmitAbort || err instanceof ConfigError;
+    // --json mode it becomes the document's error, like any refusal. So is a
+    // git lock that outlasted the retries; outside --json, index.ts explains it.
+    if (!jsonMode && err instanceof git.GitLockError) throw err;
+    const expected =
+      err instanceof SubmitAbort || err instanceof ConfigError || err instanceof git.GitLockError;
     if (!jsonMode && !expected) throw err;
     if (!expected) console.error(err);
     error = (err as Error).message;

package/src/commands/undo.ts

@@ -6,7 +6,6 @@ import { ensureMetadata, ensureCleanWorkingTree } from "../lib/safety.ts";
 import { getLastSnapshot, popSnapshot } from "../lib/snapshot.ts";
 import { clearRestackState, loadRestackState } from "../lib/metadata.ts";
 import { confirmAction } from "../lib/ui.ts";
-import { $ } from "bun";
 
 export default async function undo(args: string[]): Promise<void> {
   if (args.includes("--help")) {
@@ -60,9 +59,9 @@ a destructive operation (restack, merge, sync, remove).
   for (const [branch, sha] of Object.entries(snapshot.branches)) {
     try {
       if (branch === activeBranch) {
-        await $`git reset --hard ${sha}`.quiet();
+        await git.runGitOrThrow(["reset", "--hard", sha]);
       } else {
-        await $`git branch -f ${branch} ${sha}`.quiet();
+        await git.runGitOrThrow(["branch", "-f", branch, sha]);
       }
       p.log.success(`Restored ${pc.yellow(branch)} → ${sha.slice(0, 8)}`);
     } catch {

package/src/index.ts

@@ -19,6 +19,12 @@ const colorOff =
   process.env.GH_STACK_PLAIN === "1";
 if (colorOff) process.env.NO_COLOR = "1";
 
+// gh-stack's own read-only git calls (status, diff) shouldn't take index.lock
+// to save a refreshed stat cache: that only contends with our own writes and
+// with a gh-stack running in another worktree (#69). Bun's shell reads
+// process.env at each call, so this reaches every git we run.
+process.env.GIT_OPTIONAL_LOCKS ??= "0";
+
 const { ensureGitRepo } = await import("./lib/safety.ts");
 const { parseCliArgs } = await import("./lib/cli.ts");
 const { setAutoYes } = await import("./lib/ui.ts");
@@ -64,6 +70,7 @@ const commandArgs = parsed.commandArgs;
 // A config problem (malformed TOML, a non-boolean env value) is reported as
 // one clean line, whichever command hit it.
 const { ConfigError } = await import("./lib/config.ts");
+const { GitLockError } = await import("./lib/git.ts");
 try {
   switch (command) {
     case "log":
@@ -183,11 +190,39 @@ try {
       process.exit(1);
   }
 } catch (err) {
+  if (err instanceof GitLockError) await reportHeldLock(err);
   if (!(err instanceof ConfigError)) throw err;
   console.error(`gh-stack: ${err.message}`);
   process.exit(1);
 }
 
+/**
+ * Another git process held a lock past every retry (#69). Say so plainly:
+ * nothing conflicted, and the step runs again once the lock is gone.
+ */
+async function reportHeldLock(err: InstanceType<typeof GitLockError>): Promise<never> {
+  const { findPendingRun } = await import("./lib/run-log.ts");
+  const pending = await findPendingRun().catch(() => null);
+  const lines = [
+    `gh-stack: another git process holds ${err.lockPath}, and still did after waiting ${(err.waitedMs / 1000).toFixed(1)}s.`,
+    `  Nothing conflicted: ${err.command} couldn't take the lock, so it changed nothing.`,
+  ];
+  if (err.rebaseInProgress) {
+    lines.push(
+      `  The rebase is paused, not conflicted. Once the lock is gone:`,
+      `    git rebase --continue`,
+    );
+  }
+  lines.push(
+    pending
+      ? `  Once the lock is gone, pick the run up where it stopped:\n    gh-stack restack --resume`
+      : `  Once the lock is gone, run the command again.`,
+    `  If no other git process is running, the lock is stale; remove it:\n    rm ${err.lockPath}`,
+  );
+  console.error(lines.join("\n"));
+  process.exit(1);
+}
+
 function printHelp() {
   console.log(`
 gh-stack v${VERSION} — Stacked PR manager for squash-merge workflows

package/src/lib/branch-config.ts

@@ -27,6 +27,7 @@
 import { $ } from "bun";
 import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
+import { runGit } from "./git.ts";
 
 export interface BranchMembership {
   stack?: string;
@@ -68,12 +69,16 @@ async function setOrUnset(branch: string, key: string, value: string | undefined
     await unsetKey(branch, key);
     return;
   }
-  await $`git config ${configKey(branch, key)} ${value}`.quiet().nothrow();
+  // The repo's config is shared by every worktree, so another gh-stack (or any
+  // `git config` write) can hold config.lock for a moment: runGit waits it out
+  // instead of silently dropping the write.
+  await runGit(["config", configKey(branch, key), value]);
 }
 
 async function unsetKey(branch: string, key: string): Promise<void> {
-  // `--unset` exits 5 when the key is already absent — harmless, so nothrow.
-  await $`git config --unset ${configKey(branch, key)}`.quiet().nothrow();
+  // `--unset` exits 5 when the key is already absent — harmless, so the exit
+  // code is ignored.
+  await runGit(["config", "--unset", configKey(branch, key)]);
 }
 
 /**

package/src/lib/git.ts

@@ -2,10 +2,168 @@
 import { $ } from "bun";
 import { createHash } from "node:crypto";
 import { mkdir } from "node:fs/promises";
+import pc from "picocolors";
 
 export const STACK_SYNC_TAG_PREFIX = "stack-sync-base";
 export const STACK_SYNC_TAG_GLOB = `${STACK_SYNC_TAG_PREFIX}-*`;
 
+// ── Lock contention (#69) ──────────────────────────────────────────────────
+//
+// Git doesn't wait for a lock: a checkout, rebase or config write that finds
+// `index.lock` (or `config.lock`, a ref lock) already present fails at once.
+// The usual holder is a background reader (an editor's or agent's `git
+// status`) that grabs index.lock for a few milliseconds to save a refreshed
+// stat cache, so the lock is gone almost immediately. Every gh-stack git call
+// that takes a lock goes through runGit, which waits and retries instead.
+
+/** git's message for a lock file that already exists (lockfile.c). */
+const LOCK_HELD = /Unable to create '([^']+\.lock)': File exists/;
+/**
+ * `git config` words it differently, naming the config file rather than its
+ * lock (and it already waits about a second on its own before failing).
+ */
+const CONFIG_LOCK_HELD = /could not lock config file (.+): File exists/;
+
+/** Waits between attempts: quick at first, then backing off (~5 s in all). */
+const DEFAULT_LOCK_RETRY_DELAYS_MS = [100, 200, 400, 800, 1600, 2000];
+let lockRetryDelaysMs = DEFAULT_LOCK_RETRY_DELAYS_MS;
+
+/** Shorten the retry schedule in tests; `null` restores the default. */
+export function setLockRetryDelays(delays: number[] | null): void {
+  lockRetryDelaysMs = delays ?? DEFAULT_LOCK_RETRY_DELAYS_MS;
+}
+
+/** The lock file another process holds, if git's output says one blocked it. */
+export function heldLock(output: string): string | null {
+  const lock = LOCK_HELD.exec(output)?.[1];
+  if (lock) return lock;
+  const config = CONFIG_LOCK_HELD.exec(output)?.[1];
+  return config ? `${config}.lock` : null;
+}
+
+/**
+ * A lock was still held after every retry. Nothing conflicted: the step can
+ * simply run again once the other git process lets go.
+ */
+export class GitLockError extends Error {
+  constructor(
+    readonly lockPath: string,
+    readonly command: string,
+    /** The lock interrupted a rebase midway; it's paused, not conflicted. */
+    readonly rebaseInProgress: boolean,
+    /** How long gh-stack waited for it before giving up. */
+    readonly waitedMs: number,
+  ) {
+    super(`another git process holds ${lockPath} (${command})`);
+    this.name = "GitLockError";
+  }
+}
+
+export interface GitResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Run `git <args>`, retrying while another process holds a lock it needs.
+ * Retrying is safe because git takes the lock before changing anything: the
+ * failed attempt left the repo as it was. Throws GitLockError when retries
+ * run out; any other failure is returned for the caller to judge.
+ *
+ * `echo` replays git's output to the terminal (rebase progress and conflict
+ * messages), leaving out the attempts a lock blocked.
+ */
+export async function runGit(args: string[], opts: { echo?: boolean } = {}): Promise<GitResult> {
+  return retryLocks(args, opts.echo ?? false, async () => ({ next: args }));
+}
+
+/** Run `git <args>` with lock retries, throwing if it fails for another reason. */
+export async function runGitOrThrow(args: string[], opts: { echo?: boolean } = {}): Promise<void> {
+  const { exitCode, stderr } = await runGit(args, opts);
+  if (exitCode !== 0) {
+    throw new Error(`git ${args.join(" ")} failed (exit ${exitCode}): ${stderr.trim()}`);
+  }
+}
+
+interface Retry {
+  next: string[];
+  /** The retry resumes a rebase that a lock paused midway. */
+  resumesRebase?: boolean;
+}
+
+/**
+ * A rebase, retried around lock contention. A lock held when the rebase
+ * starts fails it before anything happens ("could not detach HEAD"), so it
+ * runs again as is. A lock that turns up midway makes git reschedule the
+ * pick it couldn't apply and pause, with nothing conflicted: `git rebase
+ * --continue` picks it up. Returns false only for a real conflict.
+ * (Exported for tests; commands use rebaseOnto and rebase.)
+ */
+export async function runRebase(args: string[]): Promise<boolean> {
+  const result = await retryLocks(args, true, async () => {
+    if (!(await isRebaseInProgress())) return { next: args };
+    // A conflict leaves unmerged paths; a lock-paused rebase doesn't.
+    if (await hasUnmergedPaths()) return null;
+    return { next: ["rebase", "--continue"], resumesRebase: true };
+  });
+  return result.exitCode === 0;
+}
+
+/**
+ * The retry loop. When an attempt fails because a lock is held, `onLocked`
+ * returns the command to retry with (or null to stop and return the failure).
+ */
+async function retryLocks(
+  args: string[],
+  echo: boolean,
+  onLocked: () => Promise<Retry | null>,
+): Promise<GitResult> {
+  let retry: Retry = { next: args };
+  let announced = false;
+  let waitedMs = 0;
+  for (let attempt = 0; ; attempt++) {
+    let shell = $`git ${retry.next}`.quiet().nothrow();
+    // Resuming a lock-paused pick reuses the commit's message; never stop to
+    // open an editor for it.
+    if (retry.resumesRebase) shell = shell.env({ ...process.env, GIT_EDITOR: "true" });
+    const raw = await shell;
+    const result = {
+      exitCode: raw.exitCode,
+      stdout: raw.stdout.toString(),
+      stderr: raw.stderr.toString(),
+    };
+
+    const lock = result.exitCode === 0 ? null : heldLock(result.stderr);
+    const next = lock ? await onLocked() : null;
+    if (!lock || !next) {
+      if (echo) {
+        process.stdout.write(result.stdout);
+        process.stderr.write(result.stderr);
+      }
+      return result;
+    }
+
+    const delay = lockRetryDelaysMs[attempt];
+    if (delay === undefined) {
+      throw new GitLockError(lock, `git ${args.join(" ")}`, next.resumesRebase ?? false, waitedMs);
+    }
+    if (!announced) {
+      console.error(pc.dim(`  Another git process holds ${lock}; waiting for it to finish…`));
+      announced = true;
+    }
+    await Bun.sleep(delay);
+    waitedMs += delay;
+    retry = next;
+  }
+}
+
+/** Whether the index has unmerged (conflicted) entries. */
+async function hasUnmergedPaths(): Promise<boolean> {
+  const out = await $`git diff --name-only --diff-filter=U`.quiet().nothrow().text();
+  return out.trim() !== "";
+}
+
 /**
  * Get the current branch name.
  * Throws if in detached HEAD state.
@@ -61,9 +219,13 @@ export async function repoRoot(): Promise<string> {
  * Refreshes the index first to avoid false positives from stale stat info.
  */
 export async function isCleanWorkingTree(): Promise<boolean> {
+  // Refresh index to avoid false positives from stat changes (timestamps, etc.).
+  // Outside the try: a lock that never frees must surface, not read as dirty.
+  // No -q: it also hides the lock message, and a refresh the lock blocked
+  // leaves stale stat info that makes a clean tree look dirty. The output
+  // ("needs update" lines) is captured and dropped.
+  await runGit(["update-index", "--refresh"]);
   try {
-    // Refresh index to avoid false positives from stat changes (timestamps, etc.)
-    await $`git update-index -q --refresh`.quiet().nothrow();
     await $`git diff-index --quiet HEAD --`.quiet();
     return true;
   } catch {
@@ -96,13 +258,13 @@ export async function isRebaseInProgress(): Promise<boolean> {
 }
 
 /**
- * Checkout a branch. Throws a raw ShellError on failure — only use this where a
- * failure is unexpected (e.g. after ensureCleanWorkingTree). For user-facing
- * branch switching, prefer tryCheckout so a dirty-tree refusal can be rendered
- * as a clean message instead of a stack trace.
+ * Checkout a branch. Throws on failure — only use this where a failure is
+ * unexpected (e.g. after ensureCleanWorkingTree). For user-facing branch
+ * switching, prefer tryCheckout so a dirty-tree refusal can be rendered as a
+ * clean message instead of a stack trace.
  */
 export async function checkout(branch: string): Promise<void> {
-  await $`git checkout ${branch}`.quiet();
+  await runGitOrThrow(["checkout", branch]);
 }
 
 /**
@@ -111,15 +273,15 @@ export async function checkout(branch: string): Promise<void> {
  * message and the offending file list when a dirty tree blocks the switch).
  */
 export async function tryCheckout(branch: string): Promise<{ ok: boolean; stderr: string }> {
-  const { exitCode, stderr } = await $`git checkout ${branch}`.quiet().nothrow();
-  return { ok: exitCode === 0, stderr: stderr.toString() };
+  const { exitCode, stderr } = await runGit(["checkout", branch]);
+  return { ok: exitCode === 0, stderr };
 }
 
 /**
  * Create and checkout a new branch from the current HEAD.
  */
 export async function createBranch(name: string): Promise<void> {
-  await $`git checkout -b ${name}`;
+  await runGitOrThrow(["checkout", "-b", name], { echo: true });
 }
 
 /**
@@ -324,7 +486,7 @@ export async function localBranchExists(branch: string): Promise<boolean> {
  * the branch didn't exist or the delete failed.
  */
 export async function deleteLocalBranch(branch: string): Promise<boolean> {
-  const { exitCode } = await $`git branch -D ${branch}`.nothrow().quiet();
+  const { exitCode } = await runGit(["branch", "-D", branch]);
   return exitCode === 0;
 }
 
@@ -334,7 +496,7 @@ export async function deleteLocalBranch(branch: string): Promise<boolean> {
  * Returns false if the rename failed (e.g. the new name already exists).
  */
 export async function renameBranch(oldName: string, newName: string): Promise<boolean> {
-  const { exitCode } = await $`git branch -m ${oldName} ${newName}`.nothrow().quiet();
+  const { exitCode } = await runGit(["branch", "-m", oldName, newName]);
   return exitCode === 0;
 }
 
@@ -350,7 +512,7 @@ export async function deleteRemoteBranch(branch: string): Promise<boolean> {
  * Create a temporary tag at a specific commit.
  */
 export async function createTag(name: string, commit: string): Promise<void> {
-  await $`git tag -f ${name} ${commit}`.quiet();
+  await runGitOrThrow(["tag", "-f", name, commit]);
 }
 
 /**
@@ -361,7 +523,7 @@ export async function deleteTagsMatching(pattern: string): Promise<void> {
     const result = await $`git tag -l ${pattern}`.text();
     const tags = result.trim().split("\n").filter(Boolean);
     for (const tag of tags) {
-      await $`git tag -d ${tag}`.quiet();
+      await runGitOrThrow(["tag", "-d", tag]);
     }
   } catch {
     // No tags to delete — that's fine
@@ -386,8 +548,7 @@ export async function rebaseOnto(
   oldBase: string,
   branch: string,
 ): Promise<boolean> {
-  const { exitCode } = await $`git rebase --onto ${newBase} ${oldBase} ${branch}`.nothrow();
-  return exitCode === 0;
+  return runRebase(["rebase", "--onto", newBase, oldBase, branch]);
 }
 
 /**
@@ -395,7 +556,7 @@ export async function rebaseOnto(
  * 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();
+  const { exitCode } = await runGit(["reset", "--hard", ref]);
   return exitCode === 0;
 }
 
@@ -404,8 +565,7 @@ export async function resetHard(ref: string): Promise<boolean> {
  * Returns true if successful, false if conflicts occurred.
  */
 export async function rebase(target: string): Promise<boolean> {
-  const { exitCode } = await $`git rebase ${target}`.nothrow();
-  return exitCode === 0;
+  return runRebase(["rebase", target]);
 }
 
 /**
@@ -413,7 +573,7 @@ export async function rebase(target: string): Promise<boolean> {
  * Returns true if successful.
  */
 export async function mergeSquash(branch: string): Promise<boolean> {
-  const { exitCode } = await $`git merge --squash ${branch}`.nothrow();
+  const { exitCode } = await runGit(["merge", "--squash", branch], { echo: true });
   return exitCode === 0;
 }
 
@@ -421,7 +581,7 @@ export async function mergeSquash(branch: string): Promise<boolean> {
  * Commit with a message.
  */
 export async function commit(message: string): Promise<void> {
-  await $`git commit -m ${message}`;
+  await runGitOrThrow(["commit", "-m", message], { echo: true });
 }
 
 /**

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

@@ -303,6 +303,13 @@ 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.
 
+**"Another git process holds …index.lock"**: some other process (often a
+background `git status`) held a git lock. gh-stack waits and retries for about 5
+seconds first, so seeing this means the lock outlasted that. It is not a
+conflict and the step changed nothing: run the same command again, or
+`gh-stack restack --resume` if a restack/sync was interrupted. If no git process
+is running, the lock is stale; remove the file it names.
+
 **Why did the push fail?** gh-stack prints the last lines of `git push`'s
 output, which includes a pre-push hook's own messages, and saves all of it to
 `.git/.gh-stack/push-failure.log`. Fix the cause (a failing check, say), then