@solaqua/gji 0.15.0 → 0.16.0

package/README.md

@@ -1,157 +1,100 @@
-# gji — Switch Git contexts without stashing
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="website/static/img/logo-dark.svg" />
+  <img src="website/static/img/logo.svg" alt="gji branch mascot" width="72" height="68" />
+</picture>
 
-> Start, review, and switch between Git tasks without disturbing the work already open.
+# gji — Switch tasks. Keep your place.
 
-`gji` makes Git worktrees feel like normal shell navigation. Each task gets its
-own directory, dependencies, editor context, and terminal — so moving to a
-pull request or experiment does not require stashing, checking out, or
-reinstalling.
+Open a new task or review a PR. Your current work stays right where you left it.
 
-## Start your next task
+`gji` is a Git worktree CLI for developers who keep more than one task open.
+Each task gets a separate working directory and dependency installation, so
+switching tasks doesn't mean packing up your changes first. Keep using your
+usual Git commands, editor, and coding tools inside each worktree.
 
-Run `gji new` and let the interactive flow guide you into a fresh worktree:
+[Get started](#get-started) · [Documentation](https://gji.solaqua.dev/docs/intro) · [Is gji a fit?](https://gji.solaqua.dev/docs/comparison)
 
-```sh
-gji new
-```
-
-Choose a task name and setup options, then continue working in the new
-directory. For repeatable workflows, you can still provide a branch directly:
-
-```sh
-gji new feature/payment-refactor
-```
-
-If you prefer to reuse the current worktree, create a branch in place and
-refresh the configured default branch first:
-
-```sh
-gji new --branch-only feature/payment-refactor
-```
-
-This creates the new branch from the latest configured remote default branch
-without creating another worktree or installing dependencies. The current
-worktree must be clean; use `--no-fetch` to create from the local default
-branch as-is.
-
-## The problem
-
-You are halfway through a feature when someone asks you to review a pull
-request. Without worktrees, a quick review often becomes:
-
-```text
-stash → checkout → reinstall → review → checkout back → stash pop
-```
-
-With `gji`, the review gets its own workspace and your current task stays
-untouched:
+<a href="https://gji.solaqua.dev/#workflow">
+  <picture>
+    <source media="(prefers-reduced-motion: reduce)" srcset=".github/assets/readme-workflow.png" />
+    <img src=".github/assets/readme-workflow.gif" alt="Start a new task, open a PR in a separate worktree, then return to feature/payments with the same two modified files." width="960" height="336" />
+  </picture>
+</a>
 
-```sh
-gji pr 1234
-```
-
-<table>
-  <tr>
-    <td width="50%" valign="top">
-      <strong>Before</strong><br />
-      <img src=".github/assets/readme-before.gif" alt="Traditional branch switching with stash and reinstall steps" />
-    </td>
-    <td width="50%" valign="top">
-      <strong>After</strong><br />
-      <img src=".github/assets/readme-after.gif" alt="Creating an isolated pull request worktree with gji" />
-    </td>
-  </tr>
-</table>
-
-## Remember four commands
-
-```sh
-gji new                            # interactively start a task
-gji pr 1234                        # open a pull request in isolation
-gji go main                        # jump to another worktree
-gji done feature/payment-refactor  # finish and clean up a task
-```
+*Illustrated workflow. Shell integration is enabled; setup time is omitted.*
 
-With shell integration enabled, each command moves your shell into the
-selected worktree automatically.
+## Get started
 
-## Install
+You need **Node.js 18+**, Git with worktree support, and **zsh, bash, or fish**
+for automatic directory changes.
 
 ```sh
 npm install -g @solaqua/gji
 gji init
 ```
 
-`gji init` interactively installs shell integration, completions, and an
-available editor. Restart your shell, or source the rc file shown by the
-wizard, then run:
+Restart your shell, or load the shell configuration file shown by the wizard.
+Then, inside a repository you already work in:
 
 ```sh
 gji doctor
+gji new feature/try-gji
+gji back
 ```
 
-Without shell integration, commands still print paths for scripts and other
-non-interactive use. See the [installation guide](https://gji.solaqua.dev/docs/installation)
-for explicit shell setup.
-
-## A typical day
+You just opened a separate worktree and returned to your previous one. Any
+uncommitted files you left there stay there. New worktrees install dependencies
+automatically when a supported lockfile is detected, so the first setup can take
+time. Use `--no-install` to skip it for one task.
 
-```sh
-# Start feature work
-gji new
-
-# Check what is active
-gji
+[Installation and shell setup](https://gji.solaqua.dev/docs/installation) · [Complete the first-worktree walkthrough](https://gji.solaqua.dev/docs/quick-start)
 
-# Review a PR without changing the current task
-gji pr 1234
+## Keep several tasks open
 
-# Move between tasks
-gji go feature/payment-refactor
-gji back
+For example, while working on `feature/payments`:
 
-# Keep worktrees current and remove finished work
-gji sync
-gji done feature/payment-refactor
+```sh
+gji new feature/search       # give another task its own directory
+gji pr 1234                  # open a real PR from your repository
+gji go feature/payments      # return to the changes you left open
 ```
 
-Worktrees use a predictable location by default:
+Replace `1234` with a GitHub pull request in your repository. Each task stays in
+its own worktree. Navigation moves your shell; it doesn't move changes between
+branches or keep files synchronized.
 
-```text
-../worktrees/<repo>/<branch>
-```
-
-That keeps editor bookmarks, scripts, and terminal navigation stable.
+| When you want to… | Run |
+| --- | --- |
+| Start a task | `gji new` |
+| Review a PR locally | `gji pr 1234` |
+| Find an open task | `gji` or `gji go` |
+| Return to the last worktree | `gji back` |
+| Open the current worktree in an editor | `gji open` |
+| Finish a linked worktree | `gji done` |
 
-## More capabilities
+With `gji go`, press **Tab** to browse all registered repositories. Worktrees
+have predictable paths: `../worktrees/<repo>/<branch>`.
 
-Use the documentation when you need to go beyond the core workflow:
+## Make the next worktree ready for your project
 
-- [Daily workflow](https://gji.solaqua.dev/docs/daily-workflow) — navigation, PRs, sync, and cleanup
-- [Commands](https://gji.solaqua.dev/docs/commands) — complete command reference
-- [Shell integration](https://gji.solaqua.dev/docs/shell-integration) — zsh, bash, and fish setup
-- [Configuration](https://gji.solaqua.dev/docs/configuration) — paths, defaults, and local files
-- [Hooks](https://gji.solaqua.dev/docs/hooks) — automate setup and cleanup
-- [Sync and cleanup](https://gji.solaqua.dev/docs/sync-and-cleanup) — maintain active worktrees
-- [Comparison](https://gji.solaqua.dev/docs/comparison) — `gji` vs `git worktree`, `lazygit`, and `ghq`
-- [FAQ and troubleshooting](https://gji.solaqua.dev/docs/faq) — common questions and fixes
+- [Local files and defaults](https://gji.solaqua.dev/docs/configuration) — copy `.env.local`, choose an editor, or adjust dependency setup.
+- [Hooks](https://gji.solaqua.dev/docs/hooks) — run project-specific setup after the built-in dependency install.
+- [Daily workflow](https://gji.solaqua.dev/docs/daily-workflow) — review, experiment, navigate, and open editors.
+- [Sync and cleanup](https://gji.solaqua.dev/docs/sync-and-cleanup) — rebase active worktrees and remove finished ones. Cleanup can delete branches; undo does not recover uncommitted files.
+- [Command reference](https://gji.solaqua.dev/docs/commands) — options, JSON output, and scripting.
+- [Troubleshooting](https://gji.solaqua.dev/docs/troubleshooting) — recover from setup, navigation, or install problems.
 
-`gji` also supports JSON output for scripts and AI-assisted workflows:
+## Contributing
 
 ```sh
-gji --json
-gji new --json feature/dark-mode
-gji go --json feature/dark-mode
+pnpm install
+pnpm test
+pnpm build
 ```
 
-Read the [full documentation](https://gji.solaqua.dev) for configuration,
-dependency bootstrap, hooks, automation, and the complete CLI reference.
-
----
-
-If `gji` has saved you from a `git stash` spiral, a ⭐ on
-[GitHub](https://github.com/sjquant/gji) helps other developers find it.
+The CLI source is in `src/`. See [website/README.md](website/README.md) for site
+and documentation development.
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/dist/cli/commands/back.d.ts

@@ -9,7 +9,7 @@ export interface BackCommandOptions {
     commandName?: string;
     outputEnv?: string;
     print?: boolean;
-    runtime?: CliRuntime<"config" | "historyStore" | "hooks" | "repositoryContext">;
+    runtime?: CliRuntime<"config" | "historyStore" | "hooks" | "repositoryContext" | "slots">;
     stderr: (chunk: string) => void;
     stdout: (chunk: string) => void;
 }

package/dist/cli/commands/back.js

@@ -59,6 +59,7 @@ export async function runBackCommand(options) {
             branch: target.branch ?? undefined,
             path: target.path,
             repo: basename(repository.repoRoot),
+            slot: await runtime.slots.getWorktreeSlot(target.path),
         }, options.stderr);
     }
     catch {

package/dist/cli/commands/clean.d.ts

@@ -9,7 +9,7 @@ export interface CleanCommandOptions {
     json?: boolean;
     paths?: string[];
     stale?: boolean;
-    runtime?: CliRuntime<"git" | "config" | "configStore" | "slots" | "repositoryContext" | "repositoryRegistry" | "worktrees" | "worktreeInfo" | "worktreeLifecycle" | "worktreeCatalog">;
+    runtime?: CliRuntime<"git" | "config" | "configStore" | "hooks" | "slots" | "repositoryContext" | "repositoryRegistry" | "worktrees" | "worktreeInfo" | "worktreeLifecycle" | "worktreeCatalog">;
     stderr: (chunk: string) => void;
     stdout: (chunk: string) => void;
 }

package/dist/cli/commands/clean.js

@@ -30,7 +30,8 @@ export function createCleanCommand(dependencies = {}) {
         const runtime = options.runtime ?? defaultCliDependencies;
         const { readWorktreeHealth, isBranchMergedInto, resolveRemoteBase, runGit, } = runtime.git;
         const { loadEffectiveConfig } = runtime.config;
-        const { releaseWorktreeSlot } = runtime.slots;
+        const { getWorktreeSlot, releaseWorktreeSlot } = runtime.slots;
+        const { extractHooks, runHook } = runtime.hooks;
         const sourceDependencies = {
             ...runtime.repositoryContext,
             ...runtime.repositoryRegistry,
@@ -155,7 +156,8 @@ export function createCleanCommand(dependencies = {}) {
                 emitError(options, message);
             }
             else {
-                options.stderr(`gji clean: ${message} in non-interactive mode (GJI_NO_TUI=1)\n`);
+                options.stderr(`gji clean: ${message} in non-interactive mode\n`);
+                options.stderr("Hint: --force removes every candidate; use --dry-run to preview them first\n");
             }
             return 1;
         }
@@ -225,6 +227,13 @@ export function createCleanCommand(dependencies = {}) {
                 options.stderr(`Skipped ${worktree.path}: no longer a safe stale cleanup candidate\n`);
                 continue;
             }
+            const hooks = extractHooks(await loadEffectiveConfig(repoRoot));
+            await runHook(hooks["before-remove"], worktree.path, {
+                branch: worktree.branch ?? undefined,
+                path: worktree.path,
+                repo: basename(repoRoot),
+                slot: await getWorktreeSlot(worktree.path),
+            }, options.stderr, options.json ? () => undefined : options.stdout);
             try {
                 await removeWorktree(repoRoot, worktree.path);
             }

package/dist/cli/commands/done.js

@@ -10,7 +10,7 @@ export async function runDoneCommand(options) {
     const { readWorktreeHealth, isBranchMergedInto, resolveRemoteDefaultBranch, runGit, } = runtime.git;
     const { loadEffectiveConfig, resolveConfigString } = runtime.config;
     const { loadHistory } = runtime.historyStore;
-    const { releaseWorktreeSlot } = runtime.slots;
+    const { getWorktreeSlot, releaseWorktreeSlot } = runtime.slots;
     const { extractHooks, runHook } = runtime.hooks;
     const { detectRepository } = runtime.repositoryContext;
     const { listWorktrees } = runtime.worktrees;
@@ -69,7 +69,8 @@ export async function runDoneCommand(options) {
         branch: target.branch ?? undefined,
         path: target.path,
         repo: basename(repository.repoRoot),
-    }, options.stderr);
+        slot: await getWorktreeSlot(target.path),
+    }, options.stderr, options.json ? () => undefined : options.stdout);
     try {
         await removeWorktree(repository.repoRoot, target.path);
     }

package/dist/cli/commands/go.js

@@ -10,7 +10,7 @@ import { buildWorktreePromptEntries, promptForSingleWorktree, } from "../../pres
 import { defaultCliDependencies, withPullRequestQueries, } from "../dependencies.js";
 import { isHeadless } from "../runtime/headless.js";
 import { runBackCommand } from "./back.js";
-import { runNewCommand } from "./new.js";
+import { applyConfiguredBranchPrefix, runNewCommand } from "./new.js";
 import { runPrCommand } from "./pr.js";
 const GO_OUTPUT_FILE_ENV = "GJI_GO_OUTPUT_FILE";
 export function createGoCommand(dependencies = {}) {
@@ -42,7 +42,7 @@ export function createGoCommand(dependencies = {}) {
             : [];
         if (!options.branch) {
             if (options.json || isHeadless()) {
-                return emitError(options, "branch argument is required in non-interactive mode (GJI_NO_TUI=1)");
+                return emitError(options, "branch argument is required in non-interactive mode");
             }
             let skippedRegisteredRepos = 0;
             let registeredSources = null;
@@ -150,8 +150,8 @@ async function handleGoBranchResolution(options, resolution, confirmBranchCreati
         case "create":
             return createExistingBranchWorktree(options, confirmBranchCreation, resolution.repository, resolution.branch, resolution.mode, resolution.remote, runtime);
         case "pull-request":
-            if (options.json || isHeadless() || options.print) {
-                return emitError(options, "PR navigation creates a worktree; use `gji pr <ref>` in an interactive shell");
+            if (options.json || options.print) {
+                return emitError(options, "PR navigation creates a worktree; use `gji pr <ref>`");
             }
             return runPrCommand({
                 cwd: resolution.repository.repoRoot,
@@ -197,7 +197,8 @@ function deduplicateSources(sources) {
 }
 async function createExistingBranchWorktree(options, confirmBranchCreation, repository, branch, mode, remote, runtime) {
     if (options.json || isHeadless() || options.print) {
-        return emitError(options, `branch "${branch}" exists but has no worktree; use interactive gji go ${branch} to create one`);
+        const command = await resolveNonInteractiveCreateCommand(repository, branch, mode, remote, runtime ?? defaultCliDependencies);
+        return emitError(options, `branch "${branch}" exists but has no worktree; run ${command} to create one`);
     }
     if (!(await confirmBranchCreation(branch))) {
         options.stderr("Aborted\n");
@@ -214,6 +215,18 @@ async function createExistingBranchWorktree(options, confirmBranchCreation, repo
         runtime,
     });
 }
+async function resolveNonInteractiveCreateCommand(repository, branch, mode, remote, runtime) {
+    if (mode === "track") {
+        return `git worktree add --track -b ${branch} <path> ${remote ?? "origin"}/${branch}`;
+    }
+    // gji new applies branchPrefix, so it would create a different branch.
+    const config = await runtime.config
+        .loadEffectiveConfig(repository.repoRoot)
+        .catch(() => null);
+    return applyConfiguredBranchPrefix(branch, config?.branchPrefix) === branch
+        ? `gji new ${branch}`
+        : `git worktree add <path> ${branch}`;
+}
 async function navigateToExistingWorktree(options, path, worktree, runtime) {
     const repository = await runtime.repositoryContext.detectRepository(path);
     if (options.json) {

package/dist/cli/commands/init.js

@@ -45,13 +45,6 @@ const SHELL_WRAPPED_COMMANDS = [
         names: ["root"],
         tempPrefix: "gji-root",
     },
-    {
-        bypassOptions: ["--help", "-h", "--json"],
-        commandName: "remove",
-        envVar: "GJI_REMOVE_OUTPUT_FILE",
-        names: ["remove", "rm"],
-        tempPrefix: "gji-remove",
-    },
     {
         bypassOptions: ["--help", "-h", "--json"],
         commandName: "done",
@@ -59,13 +52,6 @@ const SHELL_WRAPPED_COMMANDS = [
         names: ["done"],
         tempPrefix: "gji-done",
     },
-    {
-        bypassOptions: ["--print", "--json", "--help", "-h"],
-        commandName: "warp",
-        envVar: "GJI_WARP_OUTPUT_FILE",
-        names: ["warp"],
-        tempPrefix: "gji-warp",
-    },
 ];
 export async function runInitCommand(options) {
     const runtime = options.runtime ?? defaultCliDependencies;

package/dist/cli/commands/new.d.ts

@@ -26,7 +26,7 @@ export interface NewCommandOptions {
     task?: string;
     runtime?: NewRuntime;
 }
-type NewRuntime = CliRuntime<"bootstrap" | "config" | "git" | "history" | "integrations" | "repositoryContext" | "tasks">;
+type NewRuntime = CliRuntime<"bootstrap" | "config" | "git" | "history" | "hooks" | "integrations" | "repositoryContext" | "slots" | "tasks">;
 export interface NewCommandDependencies {
     createBranchPlaceholder: () => string;
     promptForBranch: (placeholder: string) => Promise<string | null>;
@@ -38,3 +38,4 @@ export interface NewCommandDependencies {
 export declare function createNewCommand(dependencies?: Partial<NewCommandDependencies>): (options: NewCommandOptions) => Promise<number>;
 export declare const runNewCommand: (options: NewCommandOptions) => Promise<number>;
 export declare function generateBranchPlaceholder(random?: () => number): string;
+export declare function applyConfiguredBranchPrefix(branch: string, branchPrefix: unknown): string;

package/dist/cli/commands/new.js

@@ -1,5 +1,5 @@
-import { access, mkdir } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { access, mkdir, rmdir } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
 import { confirm, isCancel, text } from "@clack/prompts";
 import { resolveWorktreePath, validateBranchName, } from "../../domain/worktree/policy.js";
 import { createBootstrapReporter } from "../../presentation/bootstrap/output.js";
@@ -56,7 +56,7 @@ export function createNewCommand(dependencies = {}) {
                 options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
             }
             else {
-                options.stderr(`gji new: ${message} in non-interactive mode (GJI_NO_TUI=1)\n`);
+                options.stderr(`gji new: ${message} in non-interactive mode\n`);
             }
             return 1;
         }
@@ -103,7 +103,7 @@ export function createNewCommand(dependencies = {}) {
             if (options.force) {
                 if (!options.dryRun) {
                     try {
-                        await runtime.git.runGit(repository.repoRoot, [
+                        await runtime.git.runGitRetryingContention(repository.repoRoot, [
                             "worktree",
                             "remove",
                             "--force",
@@ -111,6 +111,8 @@ export function createNewCommand(dependencies = {}) {
                         ]);
                     }
                     catch (err) {
+                        // The worktree claims its path below, which an empty leftover would block.
+                        await rmdir(worktreePath).catch(() => undefined);
                         if (!isNotRegisteredWorktreeError(err)) {
                             const msg = `could not remove existing worktree at ${worktreePath}: ${toExecMessage(err)}`;
                             if (options.json) {
@@ -141,7 +143,7 @@ export function createNewCommand(dependencies = {}) {
                     options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
                 }
                 else {
-                    options.stderr(`gji new: ${message} in non-interactive mode (GJI_NO_TUI=1)\n`);
+                    options.stderr(`gji new: ${message} in non-interactive mode\n`);
                     options.stderr(`Hint: Use 'gji done ${worktreeName}' or 'gji clean' to remove the existing worktree\n`);
                     options.stderr(`Hint: Use 'gji run-hook after-create' inside the worktree to re-run setup hooks\n`);
                 }
@@ -229,13 +231,14 @@ export function createNewCommand(dependencies = {}) {
         if (options.take && submoduleFiles.length > 0)
             options.stderr(`Warning: submodule changes are not transferred: ${submoduleFiles.join(", ")}\n`);
         const existingLocalBranch = await localBranchExists(repository.repoRoot, worktreeName, runtime);
-        const shouldRefreshBase = !options.noFetch &&
-            !options.detached &&
-            !options.fromCurrent &&
-            !options.take &&
+        const createsBranch = !options.detached &&
             options.mode !== "track" &&
             options.mode !== "checkout" &&
             !existingLocalBranch;
+        const shouldRefreshBase = createsBranch &&
+            !options.noFetch &&
+            !options.fromCurrent &&
+            !options.take;
         const freshBaseRef = shouldRefreshBase
             ? await resolveFreshBaseRef(repository.repoRoot, config, options, promptForFetchFailure, runtime)
             : undefined;
@@ -253,42 +256,21 @@ export function createNewCommand(dependencies = {}) {
                 return emitNewError(options, `could not stash changes safely: ${toExecMessage(error)}`);
             }
         }
-        const gitArgs = options.detached
-            ? [
-                "worktree",
-                "add",
-                "--detach",
-                worktreePath,
-                ...(takeStartPoint ? [takeStartPoint] : []),
-            ]
-            : options.mode === "track"
-                ? [
-                    "worktree",
-                    "add",
-                    "--track",
-                    "-b",
-                    worktreeName,
-                    worktreePath,
-                    `${options.remote ?? "origin"}/${worktreeName}`,
-                ]
-                : options.mode === "checkout" || existingLocalBranch
-                    ? ["worktree", "add", worktreePath, worktreeName]
-                    : [
-                        "worktree",
-                        "add",
-                        "-b",
-                        worktreeName,
-                        worktreePath,
-                        ...(takeStartPoint
-                            ? [takeStartPoint]
-                            : startPoint
-                                ? [startPoint]
-                                : freshBaseRef
-                                    ? [freshBaseRef]
-                                    : []),
-                    ];
+        const addsNewBranch = createsBranch || (!options.detached && options.mode === "track");
         try {
-            await runtime.git.runGit(repository.repoRoot, gitArgs);
+            await runtime.git.addWorktree(repository.repoRoot, worktreePath, options.detached
+                ? { detachedAt: takeStartPoint }
+                : addsNewBranch
+                    ? {
+                        branch: worktreeName,
+                        create: {
+                            startPoint: options.mode === "track"
+                                ? `${options.remote ?? "origin"}/${worktreeName}`
+                                : (takeStartPoint ?? startPoint ?? freshBaseRef),
+                            track: options.mode === "track",
+                        },
+                    }
+                    : { branch: worktreeName });
         }
         catch (error) {
             if (stashSha)
@@ -297,17 +279,7 @@ export function createNewCommand(dependencies = {}) {
         }
         if (stashSha &&
             !(await applyTakeStash(worktreePath, options.cwd, stashSha, !!options.copy, options.stderr, runtime.git.runGit))) {
-            try {
-                await runtime.git.runGit(repository.repoRoot, [
-                    "worktree",
-                    "remove",
-                    "--force",
-                    worktreePath,
-                ]);
-            }
-            catch {
-                /* rollback best effort */
-            }
+            await runtime.git.removeCreatedWorktree(repository.repoRoot, worktreePath, addsNewBranch ? worktreeName : undefined);
             return emitNewError(options, `could not apply taken changes; your changes are safe in stash: ${stashSha}`);
         }
         if (options.task !== undefined) {
@@ -338,6 +310,17 @@ export function createNewCommand(dependencies = {}) {
                 syncFiles: bootstrap.syncFileFailures,
             });
         }
+        if (createsBranch) {
+            await runNewHooks({
+                branch: worktreeName,
+                config,
+                hookNames: ["after-branch-create"],
+                options,
+                path: worktreePath,
+                repository,
+                runtime,
+            });
+        }
         if (options.json) {
             const navigation = createNavigationTarget(createNavigationRepository(repository.repoName, repository.repoRoot), worktreePath, worktreeName);
             const output = options.take
@@ -438,7 +421,7 @@ async function runBranchOnly(options, runtime, repository, config, rawBranch) {
     try {
         let startPoint = baseBranch;
         if (!options.noFetch) {
-            await runtime.git.runGit(repository.repoRoot, [
+            await runtime.git.runGitRetryingContention(repository.repoRoot, [
                 "fetch",
                 "--prune",
                 remote,
@@ -446,16 +429,29 @@ async function runBranchOnly(options, runtime, repository, config, rawBranch) {
             ]);
             startPoint = `${remote}/${baseBranch}`;
         }
-        await runtime.git.runGit(options.cwd, [
-            "switch",
-            "-c",
-            branchName,
+        await runtime.git.createBranch(repository.repoRoot, branchName, {
             startPoint,
-        ]);
+        });
+        try {
+            await runtime.git.runGit(options.cwd, ["switch", branchName]);
+        }
+        catch (error) {
+            await runtime.git.deleteCreatedBranch(repository.repoRoot, branchName);
+            throw error;
+        }
     }
     catch (error) {
         return emitNewError(options, `failed to create branch in the current worktree: ${toExecMessage(error)}`);
     }
+    await runNewHooks({
+        branch: branchName,
+        config,
+        hookNames: ["after-branch-create", "after-switch"],
+        options,
+        path: repository.currentRoot,
+        repository,
+        runtime,
+    });
     if (options.json) {
         const navigation = createNavigationTarget(createNavigationRepository(repository.repoName, repository.repoRoot), repository.currentRoot, branchName);
         options.stdout(`${JSON.stringify({ ...navigation, baseBranch, branchOnly: true }, null, 2)}\n`);
@@ -467,6 +463,18 @@ async function runBranchOnly(options, runtime, repository, config, rawBranch) {
     }
     return 0;
 }
+async function runNewHooks({ branch, config, hookNames, options, path, repository, runtime, }) {
+    const hooks = runtime.hooks.extractHooks(config);
+    const context = {
+        branch,
+        path,
+        repo: basename(repository.repoRoot),
+        slot: await runtime.slots.getWorktreeSlot(path),
+    };
+    for (const hookName of hookNames) {
+        await runtime.hooks.runHook(hooks[hookName], path, context, options.json ? () => undefined : options.stderr, options.json ? () => undefined : options.stdout);
+    }
+}
 export const runNewCommand = createNewCommand();
 async function resolveFreshBaseRef(repoRoot, config, options, promptForFetchFailure, runtime) {
     const remote = runtime.config.resolveConfigString(config, "syncRemote") ?? "origin";
@@ -480,7 +488,7 @@ async function resolveFreshBaseRef(repoRoot, config, options, promptForFetchFail
             throw new Error("the remote default branch is unknown");
         }
         baseBranch = remoteBase.branch;
-        await runtime.git.runGit(repoRoot, [
+        await runtime.git.runGitRetryingContention(repoRoot, [
             "fetch",
             "--prune",
             remote,
@@ -640,7 +648,7 @@ function generateBranchPlaceholderSuffix(random) {
     }
     return suffix;
 }
-function applyConfiguredBranchPrefix(branch, branchPrefix) {
+export function applyConfiguredBranchPrefix(branch, branchPrefix) {
     if (typeof branchPrefix !== "string" || branchPrefix.length === 0) {
         return branch;
     }

package/dist/cli/commands/open.js

@@ -26,7 +26,7 @@ export function createOpenCommand(dependencies = {}) {
             return 1;
         }
         if (options.select && isHeadless()) {
-            options.stderr("gji open --select: selector is unavailable in non-interactive mode (GJI_NO_TUI=1)\n");
+            options.stderr("gji open --select: selector is unavailable in non-interactive mode; pass a branch instead\n");
             return 1;
         }
         const [worktrees, repository] = await Promise.all([