@solaqua/gji 0.4.0 → 0.5.0

package/README.md

@@ -1,9 +1,11 @@
 # gji — Git worktrees without the hassle
 
-> Jump between tasks instantly. No stash. No reinstall. No mess.
+> Jump between tasks instantly. No stash. No branch juggling. No mess.
 
 `gji` wraps Git worktrees into a fast, ergonomic CLI. Each branch gets its own directory, its own `node_modules`, and its own terminal — so switching context is a single command instead of a ritual.
 
+That matters even more in AI-assisted workflows, where one repository often has several active tasks in parallel: your main feature, a PR review, a scratch experiment, or an agent-driven refactor. `gji` keeps each one isolated and easy to enter.
+
 ```sh
 gji new feature/payment-refactor   # new branch + worktree, cd in
 gji pr 1234                        # review PR in isolation, cd in
@@ -11,6 +13,23 @@ gji go main                        # jump back, shell changes directory
 gji remove feature/payment-refactor
 ```
 
+## Before / After
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <strong>Before</strong><br />
+      <img src=".github/assets/readme-before.gif" alt="Traditional branch review flow with git stash, branch switching, reinstalling dependencies, and a merge conflict on stash pop." />
+    </td>
+    <td width="50%" valign="top">
+      <strong>After</strong><br />
+      <img src=".github/assets/readme-after.gif" alt="gji creating an isolated pull request worktree from the terminal in a few commands." />
+    </td>
+  </tr>
+</table>
+
+Maintainer note: `pnpm generate:readme-demos` currently expects macOS, `zsh`, Google Chrome, `asciinema`, and `ffmpeg`.
+
 ---
 
 **If `gji` has saved you from a `git stash` spiral, a ⭐ on [GitHub](https://github.com/sjquant/gji) means a lot — it helps other developers find this tool.**
@@ -23,13 +42,26 @@ You are deep in a feature branch. A colleague asks for a quick review. You:
 
 1. stash your changes
 2. checkout their branch
-3. wait for `pnpm install` to finish
+3. wait for `npm install` to finish
 4. review
 5. checkout back
 6. pop your stash
 7. realize something is broken
 
-**Or you use `gji` and it is just `gji pr 1234`.**
+**Or you use `gji`, run `gji pr 1234`, and let the fresh worktree boot itself.**
+
+## Why it matters more now
+
+AI increases the amount of parallel work around a codebase.
+
+It is increasingly normal to have:
+
+1. your own branch open
+2. another branch for review
+3. a scratch space for testing an AI-generated change
+4. a separate worktree for validating a risky migration or refactor
+
+That makes Git worktrees more important, because a single shared checkout becomes the bottleneck. `gji` turns worktrees into a daily workflow instead of a Git power-user feature.
 
 ## Install
 
@@ -41,10 +73,32 @@ Then add shell integration so `gji go`, `gji new`, and `gji remove` can change y
 
 ```sh
 # zsh
-echo 'eval "$(gji init zsh)"' >> ~/.zshrc && source ~/.zshrc
+echo 'eval "$(gji init zsh)"' >> ~/.zshrc
 
 # bash
-echo 'eval "$(gji init bash)"' >> ~/.bashrc && source ~/.bashrc
+echo 'eval "$(gji init bash)"' >> ~/.bashrc
+
+# fish
+gji init fish --write
+source ~/.config/fish/config.fish
+```
+
+Install completions as separate files:
+
+```sh
+# zsh
+mkdir -p ~/.zsh/completions
+gji completion zsh > ~/.zsh/completions/_gji
+# add this before running compinit in ~/.zshrc
+fpath=(~/.zsh/completions $fpath)
+
+# bash
+mkdir -p ~/.local/share/bash-completion/completions
+gji completion bash > ~/.local/share/bash-completion/completions/gji
+
+# fish
+mkdir -p ~/.config/fish/completions
+gji completion fish > ~/.config/fish/completions/gji.fish
 ```
 
 ## Quick start
@@ -88,17 +142,33 @@ gji go feature/auth-refactor      # jump to a worktree
 gji root                          # jump to repo root
 
 gji status                        # health overview + ahead/behind counts
-gji ls                            # compact list
+gji ls                            # list with status/upstream/last commit
+gji ls --compact                  # branch/path only
 
 gji sync                          # rebase current worktree onto default branch
 gji sync --all                    # rebase every worktree
 
 gji clean                         # interactive bulk cleanup
+gji clean --stale                 # only target safe stale cleanup candidates
 gji remove feature/auth-refactor  # remove one worktree and its branch
 
 gji trigger-hook afterCreate      # re-run setup in the current worktree
 ```
 
+## Comparison
+
+`gji` sits between raw Git primitives and larger Git or repository tools:
+
+- **vs raw `git worktree`**: same underlying capability, but with branch-first commands, shell handoff, PR checkout, hooks, sync, and cleanup built into the workflow
+- **vs `lazygit`**: `lazygit` is a broad Git UI; `gji` is narrower and faster for opening, jumping between, and removing isolated branch directories
+- **vs `ghq`**: `ghq` organizes repositories; `gji` organizes active branches and PRs within one repository
+
+Use `gji` when your bottleneck is repeated context switching between features, reviews, and maintenance work without disturbing what is already open.
+
+It is especially useful when those contexts are happening in parallel across both human and AI-assisted work.
+
+See the full comparison in [website/docs/comparison.mdx](./website/docs/comparison.mdx).
+
 ## Shell setup
 
 Without shell integration `gji` prints paths and exits — which is fine for scripts but means it cannot `cd` you into a new worktree. Install the integration once:
@@ -107,7 +177,7 @@ Without shell integration `gji` prints paths and exits — which is fine for scr
 gji init zsh   # prints the shell function, review it if you like
 ```
 
-To install automatically:
+Install the wrapper once:
 
 ```sh
 # zsh
@@ -115,12 +185,42 @@ echo 'eval "$(gji init zsh)"' >> ~/.zshrc
 
 # bash
 echo 'eval "$(gji init bash)"' >> ~/.bashrc
+
+# fish
+gji init fish --write
+```
+
+Install completions separately so your shell rc stays small:
+
+```sh
+# zsh
+mkdir -p ~/.zsh/completions
+gji completion zsh > ~/.zsh/completions/_gji
+# add this before running compinit in ~/.zshrc
+fpath=(~/.zsh/completions $fpath)
+
+# bash
+mkdir -p ~/.local/share/bash-completion/completions
+gji completion bash > ~/.local/share/bash-completion/completions/gji
+
+# fish
+mkdir -p ~/.config/fish/completions
+gji completion fish > ~/.config/fish/completions/gji.fish
 ```
 
-After a reinstall or upgrade, re-source to pick up changes:
+After a reinstall or upgrade, refresh both the wrapper and the completion file:
 
 ```sh
+# zsh
 eval "$(gji init zsh)"
+gji completion zsh > ~/.zsh/completions/_gji
+# if zsh is already running, refresh completion discovery too
+autoload -Uz compinit && compinit
+
+# fish
+gji init fish --write
+gji completion fish > ~/.config/fish/completions/gji.fish
+source ~/.config/fish/config.fish
 ```
 
 For scripts that need the raw path, use `--print`:
@@ -139,13 +239,14 @@ path=$(gji root --print)
 | `gji go [branch] [--print]` | jump to a worktree |
 | `gji root [--print]` | jump to the main repo root |
 | `gji status [--json]` | repo overview, worktree health, ahead/behind |
-| `gji ls [--json]` | list active worktrees |
+| `gji ls [--compact] [--json]` | list active worktrees |
 | `gji sync [--all]` | fetch and rebase worktrees onto default branch |
-| `gji clean [--force] [--json]` | interactively prune stale worktrees |
+| `gji clean [--stale] [--force] [--json]` | interactively prune linked worktrees |
 | `gji remove [branch] [--force] [--json]` | remove a worktree and its branch |
 | `gji trigger-hook <hook>` | run a hook in the current worktree |
 | `gji config [get\|set\|unset] [key] [value]` | manage global defaults |
 | `gji init [shell]` | print or install shell integration |
+| `gji completion [shell]` | print shell completion definitions |
 
 ## Configuration
 
@@ -283,6 +384,10 @@ gji new --json feature/dark-mode
 gji pr --json 1234
 # → { "branch": "pr/1234", "path": "/…/worktrees/repo/pr/1234" }
 
+# detailed list
+gji ls --json
+# → [{ "branch": "...", "status": "clean", "upstream": { "kind": "tracked", ... }, ... }]
+
 # remove
 gji remove --json --force feature/dark-mode
 # → { "branch": "feature/dark-mode", "path": "/…", "deleted": true }
@@ -291,10 +396,16 @@ gji remove --json --force feature/dark-mode
 gji clean --json --force
 # → { "removed": [{ "branch": "...", "path": "..." }, …] }
 
+# stale-only clean
+gji clean --stale --json --force
+# → { "removed": [{ "branch": "...", "path": "..." }, …] }
+
 # error shape (any command)
 # stderr → { "error": "branch argument is required" }
 ```
 
+`gji clean --stale` limits cleanup to clean branch worktrees whose upstream is gone and whose branch is already merged into the configured or remote default branch.
+
 `--json` suppresses all interactive prompts. `--force` is required for `remove` and `clean` in JSON mode. `branch` is `null` for detached worktrees.
 
 `gji ls --json` and `gji status --json` also produce structured output — see `gji status --json | jq` for the full schema.
@@ -309,11 +420,13 @@ GJI_NO_TUI=1 gji clean --force
 
 `GJI_NO_TUI=1` disables all prompts. Commands that need confirmation require `--force`. `--json` implies the same behaviour.
 
+Update notifications are also suppressed automatically in non-interactive and `--json` runs. Users can opt out explicitly with `NO_UPDATE_NOTIFIER=1` or `--no-update-notifier`.
+
 ## Notes
 
 - Works from either the main repo root or inside any linked worktree
 - The current worktree is never offered as a `gji clean` candidate
-- `gji pr` parses GitHub, GitLab, and Bitbucket URLs but always fetches via `refs/pull/<number>/head` from `origin`
+- `gji pr` fetches from `origin` using the first matching forge ref namespace: GitHub `refs/pull/<number>/head`, GitLab `refs/merge-requests/<number>/head`, then Bitbucket `refs/pull-requests/<number>/from`
 
 ## License
 

package/dist/back.d.ts

@@ -0,0 +1,13 @@
+import { type HistoryEntry } from './history.js';
+export declare const BACK_OUTPUT_FILE_ENV = "GJI_BACK_OUTPUT_FILE";
+export interface BackCommandOptions {
+    cwd: string;
+    home?: string;
+    n?: number;
+    print?: boolean;
+    stderr: (chunk: string) => void;
+    stdout: (chunk: string) => void;
+}
+export declare function runBackCommand(options: BackCommandOptions): Promise<number>;
+export declare function formatHistoryList(history: HistoryEntry[], cwd: string): string;
+export declare function formatAge(timestamp: number): string;

package/dist/back.js

@@ -0,0 +1,74 @@
+import { access } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { loadEffectiveConfig } from './config.js';
+import { extractHooks, runHook } from './hooks.js';
+import { appendHistory, loadHistory } from './history.js';
+import { detectRepository } from './repo.js';
+import { writeShellOutput } from './shell-handoff.js';
+export const BACK_OUTPUT_FILE_ENV = 'GJI_BACK_OUTPUT_FILE';
+export async function runBackCommand(options) {
+    const history = await loadHistory(options.home);
+    const steps = options.n ?? 1;
+    if (steps < 1) {
+        options.stderr('gji back: step count must be at least 1\n');
+        return 1;
+    }
+    let found = 0;
+    let target;
+    for (const entry of history) {
+        if (entry.path === options.cwd)
+            continue;
+        try {
+            await access(entry.path);
+            found++;
+            if (found === steps) {
+                target = entry;
+                break;
+            }
+        }
+        catch {
+            // Path no longer exists — skip to the next entry
+        }
+    }
+    if (!target) {
+        options.stderr('gji back: no previous worktree in history\n');
+        options.stderr("Hint: Use 'gji go', 'gji new', or 'gji pr' to navigate between worktrees\n");
+        return 1;
+    }
+    try {
+        const repository = await detectRepository(target.path);
+        const config = await loadEffectiveConfig(repository.repoRoot, options.home, options.stderr);
+        const hooks = extractHooks(config);
+        await runHook(hooks.afterEnter, target.path, { branch: target.branch ?? undefined, path: target.path, repo: basename(repository.repoRoot) }, options.stderr);
+    }
+    catch {
+        // Not in a git repo or hooks unavailable — proceed without hook
+    }
+    await appendHistory(target.path, target.branch, options.home);
+    await writeShellOutput(BACK_OUTPUT_FILE_ENV, target.path, options.stdout);
+    return 0;
+}
+export function formatHistoryList(history, cwd) {
+    const branchWidth = Math.max('BRANCH'.length, ...history.map((e) => (e.branch ?? '(detached)').length));
+    const lines = ['  ' + 'BRANCH'.padEnd(branchWidth) + ' WHEN       PATH'];
+    for (const entry of history) {
+        const isCurrent = entry.path === cwd;
+        const branch = (entry.branch ?? '(detached)').padEnd(branchWidth);
+        const when = formatAge(entry.timestamp).padEnd(10);
+        lines.push(`${isCurrent ? '*' : ' '} ${branch} ${when} ${entry.path}`);
+    }
+    return lines.join('\n') + '\n';
+}
+export function formatAge(timestamp) {
+    const seconds = Math.floor((Date.now() - timestamp) / 1000);
+    if (seconds < 60)
+        return 'just now';
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}

package/dist/clean.d.ts

@@ -4,6 +4,7 @@ export interface CleanCommandOptions {
     dryRun?: boolean;
     force?: boolean;
     json?: boolean;
+    stale?: boolean;
     stderr: (chunk: string) => void;
     stdout: (chunk: string) => void;
 }

package/dist/clean.js

@@ -1,6 +1,8 @@
 import { confirm, isCancel, multiselect } from '@clack/prompts';
-import { readWorktreeHealth } from './git.js';
+import { loadEffectiveConfig } from './config.js';
+import { isBranchMergedInto, readWorktreeHealth, resolveRemoteDefaultBranch, runGit } from './git.js';
 import { isHeadless } from './headless.js';
+import { formatLastCommit, formatUpstreamState, formatWorktreeHint, readWorktreeInfos, serializeWorktreeInfo, } from './worktree-info.js';
 import { deleteBranch, forceDeleteBranch, forceRemoveWorktree, isBranchUnmergedError, isWorktreeDirtyError, loadLinkedWorktrees, removeWorktree, } from './worktree-management.js';
 import { defaultConfirmForceDeleteBranch, defaultConfirmForceRemoveWorktree } from './worktree-prompts.js';
 export function createCleanCommand(dependencies = {}) {
@@ -10,8 +12,18 @@ export function createCleanCommand(dependencies = {}) {
     const confirmForceDeleteBranch = dependencies.confirmForceDeleteBranch ?? defaultConfirmForceDeleteBranch;
     return async function runCleanCommand(options) {
         const { linkedWorktrees, repository } = await loadLinkedWorktrees(options.cwd);
-        const cleanupCandidates = linkedWorktrees.filter((worktree) => worktree.path !== repository.currentRoot);
+        const linkedCleanupCandidates = linkedWorktrees.filter((worktree) => worktree.path !== repository.currentRoot);
+        const staleBaseRef = options.stale
+            ? await resolveStaleBaseRef(repository.repoRoot, options.stderr)
+            : null;
+        const cleanupCandidates = options.stale
+            ? await filterStaleCleanupCandidates(repository.repoRoot, linkedCleanupCandidates, staleBaseRef)
+            : linkedCleanupCandidates;
         if (cleanupCandidates.length === 0) {
+            if (options.stale) {
+                emitNoStaleCandidates(options);
+                return 0;
+            }
             emitError(options, 'No linked worktrees to clean');
             return 1;
         }
@@ -25,8 +37,8 @@ export function createCleanCommand(dependencies = {}) {
             }
             return 1;
         }
-        // With --force, or dry-run in headless/json mode, skip selection prompt and target all candidates.
-        const shouldSelectAll = options.force || (options.dryRun && (options.json || isHeadless()));
+        // With --force, or non-interactive dry-runs, skip selection prompt and target all candidates.
+        const shouldSelectAll = options.force || (options.dryRun && (options.stale || options.json || isHeadless()));
         const selections = shouldSelectAll
             ? cleanupCandidates.map((w) => w.path)
             : await promptForWorktrees(cleanupCandidates);
@@ -39,19 +51,20 @@ export function createCleanCommand(dependencies = {}) {
             options.stderr('Selected worktree no longer exists\n');
             return 1;
         }
+        const selectedWorktreeInfos = await readWorktreeInfos(selectedWorktrees);
+        const selectedInfoByPath = new Map(selectedWorktreeInfos.map((info) => [info.path, info]));
         if (!options.dryRun && !options.force && !(await confirmRemoval(selectedWorktrees))) {
             options.stderr('Aborted\n');
             return 1;
         }
         if (options.dryRun) {
             if (options.json) {
-                const removed = selectedWorktrees.map((w) => ({ branch: w.branch, path: w.path }));
+                const removed = selectedWorktreeInfos.map((info) => serializeWorktreeInfo(info));
                 options.stdout(`${JSON.stringify({ removed, dryRun: true }, null, 2)}\n`);
             }
             else {
-                for (const w of selectedWorktrees) {
-                    const desc = w.branch ? `branch: ${w.branch}` : 'detached';
-                    options.stdout(`Would remove worktree at ${w.path} (${desc})\n`);
+                for (const info of selectedWorktreeInfos) {
+                    options.stdout(`Would remove worktree at ${info.path} (${formatCleanInfo(info)})\n`);
                 }
             }
             return 0;
@@ -59,6 +72,10 @@ export function createCleanCommand(dependencies = {}) {
         const removedPaths = [];
         const removedWorktrees = [];
         for (const worktree of selectedWorktrees) {
+            if (options.stale && !(await isStaleCleanupCandidate(repository.repoRoot, worktree, staleBaseRef))) {
+                options.stderr(`Skipped ${worktree.path}: no longer a safe stale cleanup candidate\n`);
+                continue;
+            }
             try {
                 await removeWorktree(repository.repoRoot, worktree.path);
             }
@@ -66,6 +83,10 @@ export function createCleanCommand(dependencies = {}) {
                 if (!isWorktreeDirtyError(error)) {
                     throw error;
                 }
+                if (options.stale) {
+                    options.stderr(`Skipped ${worktree.path}: no longer a safe stale cleanup candidate\n`);
+                    continue;
+                }
                 if (!options.force && !(await confirmForceRemoveWorktree(worktree.path))) {
                     reportRemovedPaths(removedPaths, options.stderr);
                     options.stderr('Aborted\n');
@@ -107,7 +128,12 @@ export function createCleanCommand(dependencies = {}) {
             }
         }
         if (options.json) {
-            const removed = removedWorktrees.map((w) => ({ branch: w.branch, path: w.path }));
+            const removed = removedWorktrees.map((worktree) => {
+                const info = selectedInfoByPath.get(worktree.path);
+                return info === undefined
+                    ? { branch: worktree.branch, path: worktree.path }
+                    : serializeWorktreeInfo(info);
+            });
             options.stdout(`${JSON.stringify({ removed }, null, 2)}\n`);
         }
         else {
@@ -117,6 +143,55 @@ export function createCleanCommand(dependencies = {}) {
     };
 }
 export const runCleanCommand = createCleanCommand();
+async function filterStaleCleanupCandidates(repoRoot, worktrees, baseBranch) {
+    if (baseBranch === null) {
+        return [];
+    }
+    const results = await Promise.all(worktrees.map((worktree) => isStaleCleanupCandidate(repoRoot, worktree, baseBranch)));
+    return worktrees.filter((_, index) => results[index]);
+}
+async function resolveStaleBaseRef(repoRoot, stderr) {
+    const config = await loadEffectiveConfig(repoRoot, undefined, stderr);
+    const remote = resolveConfiguredString(config.syncRemote) ?? 'origin';
+    const configuredDefaultBranch = resolveConfiguredString(config.syncDefaultBranch);
+    if (configuredDefaultBranch) {
+        return await resolveFetchedRemoteRef(repoRoot, remote, configuredDefaultBranch);
+    }
+    try {
+        const remoteDefaultBranch = await resolveRemoteDefaultBranch(repoRoot, remote);
+        return remoteDefaultBranch === null
+            ? null
+            : await resolveFetchedRemoteRef(repoRoot, remote, remoteDefaultBranch);
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveFetchedRemoteRef(repoRoot, remote, branch) {
+    try {
+        await runGit(repoRoot, ['fetch', '--prune', remote]);
+        return `${remote}/${branch}`;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveConfiguredString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+async function isStaleCleanupCandidate(repoRoot, worktree, baseBranch) {
+    if (baseBranch === null) {
+        return false;
+    }
+    if (worktree.branch === null) {
+        return false;
+    }
+    const health = await readWorktreeHealth(worktree.path);
+    if (health.status !== 'clean' || !health.upstreamGone) {
+        return false;
+    }
+    return isBranchMergedInto(repoRoot, worktree.branch, baseBranch);
+}
 function resolveSelectedWorktrees(worktrees, selections) {
     const selectedWorktrees = [];
     const seenPaths = new Set();
@@ -135,6 +210,13 @@ function reportRemovedPaths(paths, stderr) {
         stderr(`Already removed: ${paths.join(', ')}\n`);
     }
 }
+function formatCleanInfo(info) {
+    const branch = info.branch === null ? 'detached' : `branch: ${info.branch}`;
+    const status = `status: ${info.status}`;
+    const upstream = `upstream: ${formatUpstreamState(info.upstream)}`;
+    const last = `last: ${formatLastCommit(info.lastCommitTimestamp)}`;
+    return [branch, status, upstream, last].join(', ');
+}
 function emitError(options, message) {
     if (options.json) {
         options.stderr(`${JSON.stringify({ error: message }, null, 2)}\n`);
@@ -143,18 +225,26 @@ function emitError(options, message) {
         options.stderr(`${message}\n`);
     }
 }
+function emitNoStaleCandidates(options) {
+    if (options.json) {
+        const payload = options.dryRun
+            ? { removed: [], dryRun: true }
+            : { removed: [] };
+        options.stdout(`${JSON.stringify(payload, null, 2)}\n`);
+        return;
+    }
+    options.stdout('No stale linked worktrees to clean\n');
+}
 function toMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 async function defaultPromptForWorktrees(worktrees) {
-    const healthResults = await Promise.allSettled(worktrees.map((w) => readWorktreeHealth(w.path)));
+    const infos = await readWorktreeInfos(worktrees);
     const choice = await multiselect({
         message: 'Choose worktrees to clean',
         options: worktrees.map((worktree, i) => {
-            const health = healthResults[i].status === 'fulfilled' ? healthResults[i].value : null;
-            const isStale = health?.upstreamGone === true;
             return {
-                hint: isStale ? `${worktree.path} (upstream gone)` : worktree.path,
+                hint: formatWorktreeHint(infos[i]),
                 label: worktree.branch ?? '(detached)',
                 value: worktree.path,
             };