@solaqua/gji 0.14.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

@@ -7,8 +7,9 @@ export interface CleanCommandOptions {
     dryRun?: boolean;
     force?: boolean;
     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

@@ -1,7 +1,11 @@
+import { realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 import { confirm, isCancel } from "@clack/prompts";
 import { loadLinkedWorktrees, } from "../../application/worktree/catalog.js";
 import { deduplicateWorktreeSources, listRegisteredWorktreeSources, } from "../../application/worktree/sources.js";
 import { mapWithConcurrency } from "../../domain/shared/concurrency.js";
+import { createWorktreePathFilter, escapePathPattern, findGlobIndex, unescapePathPattern, } from "../../domain/worktree/path-filter.js";
+import { expandTildeInPath } from "../../domain/worktree/policy.js";
 import { buildWorktreePromptEntries, promptForMultipleWorktrees, } from "../../presentation/worktree/picker.js";
 import { defaultConfirmForceDeleteBranch, defaultConfirmForceRemoveWorktree, } from "../../presentation/worktree/prompts.js";
 import { defaultCliDependencies, } from "../dependencies.js";
@@ -26,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,
@@ -35,8 +40,27 @@ export function createCleanCommand(dependencies = {}) {
         const { formatLastCommit, formatUpstreamState, readWorktreeInfos, serializeWorktreeInfo, } = runtime.worktreeInfo;
         const { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isSubmoduleWorktreeRemovalError, isWorktreeDeletionError, isWorktreeForceRemovalError, removeWorktree, } = runtime.worktreeLifecycle;
         const { linkedWorktrees, repository } = await loadLinkedWorktrees(options.cwd, sourceDependencies);
+        const pathPatterns = await canonicalizePathPatterns(options.cwd, options.paths ?? []);
+        const matchesPathFilter = createWorktreePathFilter(pathPatterns);
+        // An explicit path may point at another registered repository, so
+        // --path starts in the all-repositories scope.
+        const searchAllRepositories = pathPatterns.length > 0;
+        let allSourceCount = 0;
+        const emitNoCandidates = (sourceCount) => {
+            if (pathPatterns.length > 0 && sourceCount === 0) {
+                emitError(options, "No linked worktrees match --path");
+                return 1;
+            }
+            if (options.stale) {
+                emitNoStaleCandidates(options);
+                return 0;
+            }
+            emitError(options, "No linked worktrees to clean");
+            return 1;
+        };
         const currentSources = linkedWorktrees
-            .filter((worktree) => worktree.path !== repository.currentRoot)
+            .filter((worktree) => worktree.path !== repository.currentRoot &&
+            matchesPathFilter(worktree.path))
             .map((worktree) => ({
             repoName: repository.repoName,
             repoRoot: repository.repoRoot,
@@ -77,7 +101,9 @@ export function createCleanCommand(dependencies = {}) {
                 ...registered.sources,
             ]).filter((source) => source.repoRoot !== undefined &&
                 source.worktree.path !== source.repoRoot &&
-                source.worktree.path !== repository.currentRoot);
+                source.worktree.path !== repository.currentRoot &&
+                matchesPathFilter(source.worktree.path));
+            allSourceCount = sources.length;
             const otherRepositorySources = sources.filter((source) => source.repoRoot !== repository.repoRoot);
             const otherRepositoryCandidates = await resolveCleanupCandidates({
                 sources: otherRepositorySources,
@@ -110,28 +136,19 @@ export function createCleanCommand(dependencies = {}) {
                 };
             },
         };
-        if (currentCandidates.length === 0 && interactiveSelection) {
+        if (searchAllRepositories ||
+            (interactiveSelection && currentCandidates.length === 0)) {
             const loadedAllCandidates = await loadAllCandidates();
             if (loadedAllCandidates.length === 0) {
-                if (options.stale) {
-                    emitNoStaleCandidates(options);
-                    return 0;
-                }
-                emitError(options, "No linked worktrees to clean");
-                return 1;
+                return emitNoCandidates(allSourceCount);
             }
             currentScope = false;
             activeCandidates = loadedAllCandidates;
             scope.label = "all repositories";
             scope.toggleLabel = "current repository";
         }
-        if (currentCandidates.length === 0 && !interactiveSelection) {
-            if (options.stale) {
-                emitNoStaleCandidates(options);
-                return 0;
-            }
-            emitError(options, "No linked worktrees to clean");
-            return 1;
+        else if (currentCandidates.length === 0) {
+            return emitNoCandidates(currentSources.length);
         }
         if (!options.dryRun && !options.force && (options.json || isHeadless())) {
             const message = "--force is required";
@@ -139,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;
         }
@@ -209,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);
             }
@@ -314,6 +339,29 @@ export function createCleanCommand(dependencies = {}) {
     };
 }
 export const runCleanCommand = createCleanCommand();
+async function canonicalizePathPatterns(cwd, patterns) {
+    return Promise.all(patterns.map((pattern) => canonicalizeLiteralPrefix(resolve(cwd, expandTildeInPath(pattern)))));
+}
+// Git records canonical worktree paths, so resolve symlinks in the pattern's
+// longest existing literal prefix before matching.
+async function canonicalizeLiteralPrefix(pattern) {
+    const globIndex = findGlobIndex(pattern);
+    let prefix = globIndex === -1 ? pattern : dirname(`${pattern.slice(0, globIndex)}x`);
+    let suffix = pattern.slice(prefix.length);
+    for (;;) {
+        try {
+            const canonicalPrefix = escapePathPattern(await realpath(unescapePathPattern(prefix)));
+            return `${canonicalPrefix}${suffix}`.replace(/^\/\//, "/");
+        }
+        catch {
+            const parent = dirname(prefix);
+            if (parent === prefix)
+                return pattern;
+            suffix = join("/", basename(prefix), suffix);
+            prefix = parent;
+        }
+    }
+}
 async function resolveCleanupCandidates(options, dependencies) {
     const { sources, stale, stderr, signal } = options;
     const grouped = new Map();

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;