npm - @n-seiji/nuthatch - Versions diffs - 0.2.1 → 0.2.2 - Mend

@n-seiji/nuthatch 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/README.ja.md +59 -183
package/README.md +59 -189
package/dist/{clean-rn2476my.js → clean-6q90wtve.js} +1 -1
package/dist/{cli-hz0r7zw8.js → cli-aj2y82fq.js} +1 -1
package/dist/{cli-sre95k9x.js → cli-mx5n3y1f.js} +1 -1
package/dist/{cli-pick-yjd4qpd9.js → cli-pick-8qtma4v0.js} +3 -3
package/dist/{cli-update-x0r4b4xk.js → cli-update-rjqr81xx.js} +1 -1
package/dist/{cli-9n04gsq1.js → cli-vt5mddc4.js} +1 -1
package/dist/cli.js +8 -8
package/dist/{jump-1zkraat1.js → jump-vrwxwb1f.js} +1 -1
package/dist/{ls-3hyjf60d.js → ls-hvwtaxv8.js} +1 -1
package/dist/{rm-eg3j8ae1.js → rm-a5d1c4mh.js} +1 -1
package/dist/{root-49vcb8x2.js → root-zbrsb9md.js} +1 -1
package/package.json +1 -1
package/dist/{cli-y8vsqre6.js → cli-4f1vz23g.js} +3 -3

package/README.ja.md CHANGED Viewed

@@ -1,198 +1,75 @@
-[English](README.md)
-<p align="center">
-  <img src="docs/assets/logo.png" alt="nuthatch — hop between git worktrees" width="560">
-</p>
-<p align="center"><em>ナットハッチが木々を渡るように、git worktree 間を hop する。</em></p>
-`nuthatch` は zero-setup な git worktree manager。単一コマンド **`hop`** が、
-任意の branch の worktree へジャンプする — 存在しなければその場で作成する。
-人間 (対話的 picker) と AI coding agent (非対話、`--json`) の両方に対応。
-## なぜ
-- **Zero setup** — 状態ファイルなし、init コマンドなし。
-  `git worktree list --porcelain` が唯一の正本。任意のリポジトリで即動く。
-- **Convention over config** — worktree は常に
-  `<root の親>/_worktree/<repo>/<branch>` に置かれるため、一覧やパスの推測が
-  速く予測可能。
-- **AI native** — 全コマンドが非対話で完結し、`--json` はどこでも使え、path
-  は stdout・ログは stderr に出て、エラーは次の一手を教えてくれる。
-## 使い方
-```sh
-hop                # worktree/branch を対話的に選んで cd
-hop feat/foo       # feat/foo の worktree へ cd (未作成なら --create でその場で作成)
-hop root           # root clone へ cd
-hop -              # 直前の worktree へ戻る
-hop ls [--json]    # worktree 一覧 (dirty, ahead/behind, kind)
-hop rm <branch>    # worktree を削除 (branch は残す) — managed/external 問わず、dirty には --force が必要
-hop clean          # ゴミ worktree を自動判定して削除 (managed のみ)
-hop root <branch>  # root clone を一時的に切替 (動作確認用) —
-                   # 対象 branch が他所で checkout 済みなら、clean かつ unlocked な holder を swap する
-hop root -         # root clone を元に戻す (root の branch のみ; swap で detach した holder はそのまま)
-hop -- <branch>    # 予約コマンドと被る branch 名をエスケープ
-                   # (`hop` 自体と同名の branch (例: `hop -- hop`) にも必要)
-hop --help         # usage を表示 (-h / hop help でも同じ)
-hop --version          # hop の version を表示
-hop --update           # standalone バイナリを最新リリースへ置換 (それ以外は更新方法を表示)
-hop --update --check   # 更新があるかを報告するだけ — 何も変更しない
-```
-同じ branch が複数の worktree で checkout されている場合、branch だけを指定する
-`hop rm` は削除対象を推測せず拒否する。対話的 picker は選択した path を、lock 内の
-最終安全確認まで保持する。
-### 対話的 picker
-picker は候補を section に分けて表示する — 既存の worktree (root が先頭) と
-未作成の branch — ステータスマーカー・整列した列・短縮パス付きで:
-```
-  WORKTREES
-❯ ● main          root     ~/ghq/.../nuthatch
-  ○ feat/picker   managed  …/_worktree/feat__picker
-  ● codex/fix-x   ext      …/.claude/worktrees/x
-  BRANCHES — Enter creates a worktree
-  + feat/idea     local
-  + origin/hotfix remote
-  (●=dirty ○=clean +=not created)
-```
-candidate が 0 件になった section は (header ごと) 丸ごと消える —
-検索クエリで絞り込んだ結果 0 件になった場合も同様。
-各 section 内の順序は insertion 順ではなく固定: WORKTREES は root が先頭、
-次に managed、その次に external (各グループ内は branch 名昇順、detached
-HEAD の worktree はグループ内最後); BRANCHES は remote より local が先
-(各グループ内は branch 名昇順)。これは検索フィルタ中も保たれる —
-絞り込んでも残った項目の並びは変わらない。BRANCHES の行は dim 表示になり、
-○/●/+ マーカーに加えて「既に worktree」か「まだ未作成」かが一目でわかる。
-picker は terminal の alternate screen buffer (fzf や vim と同じ仕組み) で
-動くため、scrollback 履歴に残らない — 実行のたびに画面を上書きし、
-どう終了しても (選択、Esc/Ctrl-C、割り込み) shell の画面をきれいに復元する。
-### 対話的 picker のキー
-action panel は候補一覧の隣に列として表示される (overlay ではない) ので、
-action を選ぶ間も一覧が見え続ける。横に並べられない幅 (おおよそ 94 列
-未満) の terminal では、一覧の下にスタックする形にフォールバックする。
-| キー | 動作 |
-|---|---|
-| `Enter` | 選択中の候補へ cd |
-| `Tab`, `→`, `Ctrl+L`, `Ctrl+F` | 選択中の候補の action panel を開く (ここで cd / 削除 / root 切替) |
-| `Ctrl+X` | 選択中の worktree を削除 (常に先に y/N を確認) |
-| `Ctrl+R` | root clone を選択中の branch へ切替 (`external` は先に y/N を確認) |
-| `↑`/`↓`, `Ctrl+P`/`Ctrl+N`, `Ctrl+K` | 選択を移動 (矢印・emacs・vim キーがすべて併用可) |
-| `Esc` | 静かにキャンセル — exit 0、stdout は空のまま (shell wrapper は cd しない) |
-| `Ctrl+C` | 割り込みとしてキャンセル — exit 130、実際の SIGINT と同じ |
-action panel 内: 同じ上下移動キー (左右は閉じる操作に予約されており、
-移動としては使われない)、`Enter` でハイライト中の action を実行、
-`c`/`d`/`r` で cd/delete/switch-root を直接実行、`Esc`、`Tab`、`←`、
-`Ctrl+H` で一覧に戻る (`←`/`Ctrl+H` は開く操作の `→`/`Ctrl+L`/`Ctrl+F` と
-対になっている; `Tab` はどちらの状態からでもトグルする — Ghostty のように
-Cmd+K のようなキーの組み合わせを Tab に remap する terminal で便利)。
-`delete` はすでに作成済みの worktree (`managed` / `external`) すべてに
-表示される (panel からの削除は、`external` worktree と、git が作業ツリーを
-見失った prunable な worktree なら先に y/N を確認する。Ctrl+X は常に
-確認する); `switch root here` は root worktree 自身には表示されず、
-`external` worktree に対しては HEAD を detach する可能性があるため
-同じく先に y/N を確認する。削除すると候補一覧が再読み込みされ、picker を
-抜けずに削除を続けられる; cd と switch-root は終了して結果の path を
-出力する (hop の stdout 契約どおり)。
-Shell 統合 (自動 `cd`):
-```sh
-# ~/.zshrc
-eval "$(hop init zsh)"
-```
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+  <img src="docs/assets/logo-light.svg" alt="nuthatch" width="360">
+</picture>
+[English](README.md) · **日本語**
+**git worktree を、作る・移る・消す。ぜんぶ `hop` ひとつで。**
+`nuthatch` は、人間と AI coding agent のための zero-setup な git worktree manager。コマンドは `hop` ひとつで、設定も状態ファイルもいらない。[Web サイト](https://www.sijis.me/projects/nuthatch)
+<table>
+  <tr>
+    <td align="center" valign="top" width="33%">
+      <img src="docs/assets/tile-create.svg" width="200" alt="worktree を作る"><br>
+      <b>作る</b><br>
+      <sub>branch も worktree も、その場で。</sub>
+    </td>
+    <td align="center" valign="top" width="33%">
+      <img src="docs/assets/tile-jump.svg" width="200" alt="worktree へ移る"><br>
+      <b>移る</b><br>
+      <sub><code>hop</code> で選び、<code>hop -</code> で戻る。</sub>
+    </td>
+    <td align="center" valign="top" width="33%">
+      <img src="docs/assets/tile-remove.svg" width="200" alt="worktree を消す"><br>
+      <b>消す</b><br>
+      <sub>1 つずつ、または merge 済みをまとめて。</sub>
+    </td>
+  </tr>
+</table>
 ## Install
-> まだリリースされていない — バージョンは publish も tag もされていない。
-> 最初の `v*` tag が出た後は、以下の選択肢が記載どおりに動く。
-推奨: GitHub Release のバイナリ (bun 製、mise なら
-`mise use github:n-seiji/nuthatch`)。npm 版は Node で動くため git 呼び出しが遅い
-(hop ls ~400ms vs ~60ms) — CI や頻繁な呼び出しにはバイナリを使う。
 ```sh
-# ビルド済みバイナリ (macOS arm64/x64, Linux x64) — Node.js 不要、最速:
 curl -fsSL https://raw.githubusercontent.com/n-seiji/nuthatch/main/install.sh | sh
-mise use github:n-seiji/nuthatch # mise、GitHub Release のバイナリ経由
-# npm (低速: Node 経由で git を呼ぶ — バイナリの hop ls ~60ms に対し ~400ms)
-npm i -g @n-seiji/nuthatch        # または: bunx @n-seiji/nuthatch
-mise use -g npm:@n-seiji/nuthatch # mise、npm 経由
 ```
-install script は `hop` を `~/.local/bin` に置き (`HOP_INSTALL_DIR` で
-上書き可)、常に最新の GitHub Release を取得する; 特定バージョンに固定する
-には `HOP_VERSION=vX.Y.Z` を使う。Linux arm64 はビルド済みバイナリが
-まだないため、npm install を使う。
-v0.2.0 より後のリリースのバイナリにはビルド来歴 (build provenance) の attestation
-が付く。ダウンロードしたバイナリを手動で検証するには:
+続けて `~/.zshrc` に次を足すと、`hop` が `cd` までしてくれる。
 ```sh
-gh attestation verify ./hop-darwin-arm64 --repo n-seiji/nuthatch \
-  --signer-workflow github.com/n-seiji/nuthatch/.github/workflows/release.yml
+eval "$(hop init zsh)"
 ```
-`install.sh` は attestation を確認せず、SHA-256 だけを検証する。
-### 更新
-```sh
-hop --update          # standalone バイナリを最新リリースへ置換
-hop --update --check  # 報告だけ: current / latest / インストール方法 / すべきこと
-hop --version         # 今どの version か
-```
+npm、mise、Linux arm64、バイナリの検証、更新については [ガイド](docs/guide.ja.md#install) を参照。
-`hop --update` が置換するのは `install.sh` で入れたバイナリだけで、置き場の
-ディレクトリに書き込めて (バイナリと checksum のダウンロードの前に確認する)、
-かつリリースに添付された `.sha256` と SHA-256 が一致した場合に限る — 不一致なら
-何も置換しない (確認するのは SHA-256 のみで、attestation は見ない)。それ以外のインストールでは、何も実行せず、リクエストも送らず、
-更新方法を 1 行表示して終了する (exit 1):
+## 使い方
-| インストール方法 | 更新方法 |
+| コマンド | 動作 |
 |---|---|
-| `install.sh` (`~/.local/bin` のバイナリ) | `hop --update`、または `install.sh` を再実行 |
-| mise | `mise upgrade` |
-| npm / bun / pnpm / yarn の global | `npm i -g @n-seiji/nuthatch@latest` (または使っているパッケージマネージャの同等コマンド) |
-| Homebrew・Nix・aqua・proto・ソースチェックアウト・その他のツール | そのツール自身の upgrade コマンド |
+| `hop` | worktree/branch を対話的に選んで `cd` |
+| `hop <branch>` | その branch の worktree へ `cd` |
+| `hop <branch> --create` | 未作成ならその場で worktree を作成 |
+| `hop -` | 直前の worktree へ戻る |
+| `hop root` | root clone へ `cd` |
+| `hop ls [--json]` | worktree 一覧 (dirty, ahead/behind, kind) |
+| `hop rm <branch>` | worktree を削除 (branch は残す) |
+| `hop clean` | ゴミ worktree を自動判定して削除 (既定では managed のみ) |
+| `hop --update` | standalone バイナリを最新リリースへ置換 |
-`hop --update --check` はどのインストール方法でも使え、同じ案内を報告する。
-hop がネットワークに出るのは GitHub の固定アドレスへの HTTPS リクエストだけで、
-タイムアウトとサイズ上限つき。
+picker とそのキー、`hop root <branch>` などは [ガイド](docs/guide.ja.md#使い方) にある。
-## トラブルシューティング
+## 安全がデフォルト
-`hop: git executable not found. Looked in: …` は git のバイナリを見つけられ
-なかったという意味。hop は `PATH` の絶対パスエントリを順に探し、その後
-`/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin` を見る。git が
-それ以外の場所にある場合は、直接指定する:
+- `hop rm` は、`--force` を付けない限り dirty な worktree を拒否する。`hop clean` と `hop root` は dirty な worktree に触れない。
+- git が locked と報告する worktree は、`--force` でも削除しない。
+- `_worktree/<repo>/` の外にある (external) worktree を picker から削除するときは y/N を確認する。Ctrl+X は常に確認する。
+- `hop clean` が既定で対象にするのは、hop が管理する worktree だけ。external は `--ext` を付けたときだけ対象になる。
+- `hop rm` は branch を残す。
-```sh
-export HOP_GIT=/path/to/git
-```
-## Agent skill (Claude Code / Codex plugin)
+## AI coding agent 向け
-このリポジトリは plugin marketplace も兼ねており、
-[`using-hop`](skills/using-hop/SKILL.md) skill を配布する —
-coding agent に `hop` を非対話・安全に扱う方法を教える skill。
+全コマンドが非対話で完結する。`--json` はどこでも使え、path は stdout、ログは stderr に出る。このリポジトリは [`using-hop`](plugins/hop/skills/using-hop/SKILL.md) skill を plugin として配布している。agent が `hop` を安全に使うための skill。
 ```sh
 # Claude Code
@@ -204,11 +81,10 @@ codex plugin marketplace add n-seiji/nuthatch
 codex plugin install hop
 ```
-## Docs
-- [docs/design.md](docs/design.md) — 設計書 (全文)
-- [AGENTS.md](AGENTS.md) — このリポジトリで作業する coding agent 向けガイド
-## License
+## その他
-GPL-3.0 — [LICENSE](LICENSE) 参照。
+- [Web サイト](https://www.sijis.me/projects/nuthatch)
+- [ガイド](docs/guide.ja.md): 使い方、picker、インストール、更新、トラブルシューティング
+- [docs/design.md](docs/design.md): 設計書
+- [AGENTS.md](AGENTS.md): このリポジトリで作業する coding agent 向けガイド
+- [LICENSE](LICENSE): GPL-3.0

package/README.md CHANGED Viewed

@@ -1,204 +1,75 @@
-[日本語](README.ja.md)
-<p align="center">
-  <img src="docs/assets/logo.png" alt="nuthatch — hop between git worktrees" width="560">
-</p>
-<p align="center"><em>Hop between git worktrees like a nuthatch hops between trees.</em></p>
-`nuthatch` is a zero-setup git worktree manager. Its single command, **`hop`**,
-jumps you to the worktree of any branch — creating it on the fly when it
-doesn't exist yet. Built for humans (interactive picker) and AI coding agents
-(non-interactive, `--json`) alike.
-## Why
-- **Zero setup** — no state files, no init. `git worktree list --porcelain` is
-  the single source of truth. Works in any repository immediately.
-- **Convention over config** — worktrees always live at
-  `<parent-of-root>/_worktree/<repo>/<branch>`, so listing and path inference
-  are fast and predictable.
-- **AI native** — every command completes non-interactively, `--json`
-  everywhere, paths on stdout / logs on stderr, and errors that tell you the
-  next step.
-## Usage
-```sh
-hop                # pick a worktree/branch interactively and cd into it
-hop feat/foo       # cd into feat/foo's worktree (add --create to create it if missing)
-hop root           # cd into the root clone
-hop -              # cd back to the previous worktree
-hop ls [--json]    # list worktrees (dirty, ahead/behind, kind)
-hop rm <branch>    # remove a worktree (branch is kept) — managed or external, dirty needs --force
-hop clean          # auto-detect and remove garbage worktrees (managed only)
-hop root <branch>  # temporarily switch the root clone (for verification) —
-                   # swaps out a clean, unlocked holder if the branch is checked out elsewhere
-hop root -         # switch the root clone back (only root's branch; a swapped-out holder stays detached)
-hop -- <branch>    # escape a branch name that collides with a reserved command
-                   # (also required for a branch named the same as your `hop` binary/alias, e.g. `hop -- hop`)
-hop --help         # print usage (also -h / hop help)
-hop --version          # print hop's version
-hop --update           # replace a standalone binary with the latest release (other installs: prints how to update)
-hop --update --check   # only report whether an update is available — changes nothing
-```
-If Git reports the same branch checked out in multiple worktrees, the
-branch-only `hop rm` command refuses rather than guessing which path to
-remove. The interactive picker keeps the selected path through the final
-lock-protected safety check.
-### Interactive picker
-The picker groups candidates into sections — existing worktrees (root first)
-and not-yet-created branches — with a status marker, aligned columns, and
-shortened paths:
-```
-  WORKTREES
-❯ ● main          root     ~/ghq/.../nuthatch
-  ○ feat/picker   managed  …/_worktree/feat__picker
-  ● codex/fix-x   ext      …/.claude/worktrees/x
-  BRANCHES — Enter creates a worktree
-  + feat/idea     local
-  + origin/hotfix remote
-  (●=dirty ○=clean +=not created)
-```
-A section (header included) disappears entirely when it has no candidates —
-including when a search query filters it down to zero.
-Ordering within each section is fixed, not insertion order: WORKTREES puts
-root first, then managed worktrees, then external ones (branch name
-ascending within each group, detached-HEAD worktrees last within theirs);
-BRANCHES puts local branches before remote ones (branch name ascending
-within each group). This holds under search filtering too — narrowing the
-list never reshuffles what's left. BRANCHES rows render dim so "already a
-worktree" vs. "not created yet" reads at a glance, on top of the ○/●/+
-markers.
-The picker runs in the terminal's alternate screen buffer (the same
-mechanism fzf and vim use), so it never gets pushed into your scrollback
-history — each run paints over itself and cleanly restores your shell's
-screen on exit, however it exits (selection, Esc/Ctrl-C, or an interrupt).
-### Interactive picker keys
-The action panel renders as a column beside the candidate list (not an
-overlay), so the list stays visible while you pick an action. On terminals
-too narrow to fit both (under about 94 columns) it falls back to stacking
-below the list instead.
-| Key | Action |
-|---|---|
-| `Enter` | cd into the selected candidate |
-| `Tab`, `→`, `Ctrl+L`, `Ctrl+F` | Open the action panel for the selected candidate (cd / delete / switch root here) |
-| `Ctrl+X` | Delete the selected worktree (always asks y/N first) |
-| `Ctrl+R` | Switch the root clone to the selected branch (asks y/N first for an `external` worktree) |
-| `↑`/`↓`, `Ctrl+P`/`Ctrl+N`, `Ctrl+K` | Move the selection (arrow, emacs, and vim keys all work side by side) |
-| `Esc` | Cancel quietly — exit 0, stdout stays empty (the shell wrapper just doesn't cd) |
-| `Ctrl+C` | Cancel like an interrupt — exit 130, same as a real SIGINT |
-Inside the action panel: the same up/down movement keys (left/right are
-reserved for closing, so they never double as movement), `Enter` to run the
-highlighted action, `c`/`d`/`r` to run cd/delete/switch-root directly, and
-`Esc`, `Tab`, `←`, or `Ctrl+H` to close it back to the list (`←`/`Ctrl+H`
-mirror the `→`/`Ctrl+L`/`Ctrl+F` that open it; `Tab` toggles either way —
-handy on terminals like Ghostty that remap a chord such as Cmd+K to Tab). `delete`
-appears for any already-created worktree (`managed` or `external` — from the
-panel, deleting an `external` worktree, or a prunable one (git can no longer
-find its working tree), asks y/N first; Ctrl+X always asks); `switch
-root here` doesn't appear on the root worktree itself, and also asks y/N
-first for an `external` worktree, since it can detach that worktree's HEAD.
-Deleting reloads the
-candidate list so you can keep deleting without leaving the picker; cd and
-switch-root exit and print the resulting path, per hop's stdout contract.
-Shell integration (auto-`cd`):
-```sh
-# ~/.zshrc
-eval "$(hop init zsh)"
-```
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+  <img src="docs/assets/logo-light.svg" alt="nuthatch" width="360">
+</picture>
+**English** · [日本語](README.ja.md)
+**Create, jump between, and remove git worktrees. All with `hop`.**
+`nuthatch` is a zero-setup git worktree manager for humans and AI coding agents. Its one command, `hop`, needs no config and no state files. [Website](https://www.sijis.me/en/projects/nuthatch)
+<table>
+  <tr>
+    <td align="center" valign="top" width="33%">
+      <img src="docs/assets/tile-create.svg" width="200" alt="Create a worktree"><br>
+      <b>Create</b><br>
+      <sub>The branch and its worktree, on the spot.</sub>
+    </td>
+    <td align="center" valign="top" width="33%">
+      <img src="docs/assets/tile-jump.svg" width="200" alt="Jump between worktrees"><br>
+      <b>Jump</b><br>
+      <sub><code>hop</code> to pick, <code>hop -</code> to go back.</sub>
+    </td>
+    <td align="center" valign="top" width="33%">
+      <img src="docs/assets/tile-remove.svg" width="200" alt="Remove a worktree"><br>
+      <b>Remove</b><br>
+      <sub>One at a time, or clean up what's merged.</sub>
+    </td>
+  </tr>
+</table>
 ## Install
-Recommended: the GitHub Release binary (built with bun; via mise,
-`mise use github:n-seiji/nuthatch`). The npm version runs on Node, so its git
-calls are slower (hop ls ~400ms vs ~60ms) — prefer the binary for CI or
-frequent invocations.
 ```sh
-# Prebuilt binary (macOS arm64/x64, Linux x64) — no Node.js required, fastest:
 curl -fsSL https://raw.githubusercontent.com/n-seiji/nuthatch/main/install.sh | sh
-mise use github:n-seiji/nuthatch # mise, via the GitHub Release binary
-# npm (slower: shells out to git via Node — hop ls ~400ms vs ~60ms for the binary)
-npm i -g @n-seiji/nuthatch        # or: bunx @n-seiji/nuthatch
-mise use -g npm:@n-seiji/nuthatch # mise, via npm
 ```
-The install script places `hop` in `~/.local/bin` (override with
-`HOP_INSTALL_DIR`) and always fetches the latest GitHub Release; pin a
-specific version with `HOP_VERSION=vX.Y.Z`. Linux arm64 has no prebuilt
-binary yet — use the npm install instead.
-Release binaries from releases after v0.2.0 carry a build-provenance
-attestation. To verify a downloaded binary by hand:
+Then add this to `~/.zshrc` so `hop` can `cd` for you:
 ```sh
-gh attestation verify ./hop-darwin-arm64 --repo n-seiji/nuthatch \
-  --signer-workflow github.com/n-seiji/nuthatch/.github/workflows/release.yml
+eval "$(hop init zsh)"
 ```
-`install.sh` does not check it; it verifies the SHA-256 only.
+For npm, mise, Linux arm64, verifying binaries, and updating, see the [guide](docs/guide.md#install).
-### Updating
-```sh
-hop --update          # replace a standalone binary with the latest release
-hop --update --check  # just report: current, latest, how hop was installed, what to do
-hop --version         # which version do I have?
-```
-`hop --update` only replaces the binary that `install.sh` installs, and only if
-its directory is writable (checked before the binary or its checksum is
-downloaded) and its SHA-256 matches the `.sha256` attached to the release; on a
-mismatch nothing is replaced (SHA-256 only; attestations are not checked). For any other install it runs nothing, makes no
-request, and prints one line saying how to update it (exit 1):
+## Usage
-| Installed with | Update with |
+| Command | What it does |
 |---|---|
-| `install.sh` (binary in `~/.local/bin`) | `hop --update`, or re-run `install.sh` |
-| mise | `mise upgrade` |
-| npm / bun / pnpm / yarn global | `npm i -g @n-seiji/nuthatch@latest` (or your package manager's equivalent) |
-| Homebrew, Nix, aqua, proto, a source checkout, any other tool | that tool's own upgrade command |
+| `hop` | Pick a worktree or branch interactively and `cd` into it |
+| `hop <branch>` | `cd` into the branch's worktree |
+| `hop <branch> --create` | Create the worktree if it is missing |
+| `hop -` | `cd` back to the previous worktree |
+| `hop root` | `cd` into the root clone |
+| `hop ls [--json]` | List worktrees (dirty, ahead/behind, kind) |
+| `hop rm <branch>` | Remove a worktree. The branch is kept |
+| `hop clean` | Find and remove garbage worktrees (managed only by default) |
+| `hop --update` | Replace a standalone binary with the latest release |
-`hop --update --check` works for every install and reports the same hint. The
-only network traffic is HTTPS requests to fixed GitHub addresses, each with a
-timeout and a size cap.
+The [guide](docs/guide.md#usage) covers the picker and its keys, `hop root <branch>`, and the rest.
-## Troubleshooting
+## Safe by default
-`hop: git executable not found. Looked in: …` means hop could not find a git
-binary. hop searches every absolute entry in `PATH`, then `/opt/homebrew/bin`,
-`/usr/local/bin`, `/usr/bin` and `/bin`. If your git lives somewhere else,
-point hop straight at it:
+- `hop rm` refuses a dirty worktree unless you pass `--force`. `hop clean` and `hop root` never touch one.
+- A worktree that git reports as locked is never removed, even with `--force`.
+- Deleting an external worktree (one not under `_worktree/<repo>/`) from the picker asks y/N. Ctrl+X always asks.
+- By default, `hop clean` only picks worktrees that hop manages. External ones need `--ext`.
+- `hop rm` keeps the branch.
-```sh
-export HOP_GIT=/path/to/git
-```
-## Agent skill (Claude Code / Codex plugin)
+## For AI coding agents
-This repo doubles as a plugin marketplace that ships the
-[`using-hop`](skills/using-hop/SKILL.md) skill — it teaches coding agents how
-to drive `hop` non-interactively and safely.
+Every command can complete non-interactively. `--json` works everywhere, paths go to stdout, and logs go to stderr. The repo ships the [`using-hop`](plugins/hop/skills/using-hop/SKILL.md) skill as a plugin. It teaches agents to drive `hop` safely.
 ```sh
 # Claude Code
@@ -210,11 +81,10 @@ codex plugin marketplace add n-seiji/nuthatch
 codex plugin install hop
 ```
-## Docs
-- [docs/design.md](docs/design.md) — full design document
-- [AGENTS.md](AGENTS.md) — guide for coding agents working on this repo
-## License
+## More
-GPL-3.0 — see [LICENSE](LICENSE).
+- [Website](https://www.sijis.me/en/projects/nuthatch)
+- [Guide](docs/guide.md): usage, picker, install, updating, troubleshooting
+- [docs/design.md](docs/design.md): the design document
+- [AGENTS.md](AGENTS.md): guide for coding agents working on this repo
+- [LICENSE](LICENSE): GPL-3.0

package/dist/{clean-rn2476my.js → clean-6q90wtve.js} RENAMED Viewed

@@ -12,7 +12,7 @@ import {
   loadRepoContext,
   nestedWorktrees,
   worktreeDirtyState
-} from "./cli-y8vsqre6.js";
+} from "./cli-4f1vz23g.js";
 import {
   EXIT_USAGE_ERROR,
   ok,

package/dist/{cli-hz0r7zw8.js → cli-aj2y82fq.js} RENAMED Viewed

@@ -9,7 +9,7 @@ import {
   loadRepoContext,
   isWorktreeDirty,
   resolveBranchCheckout
-} from "./cli-y8vsqre6.js";
+} from "./cli-4f1vz23g.js";
 import {
   EXIT_SAFE_REJECTION,
   ok,

package/dist/{cli-sre95k9x.js → cli-mx5n3y1f.js} RENAMED Viewed

@@ -37,7 +37,7 @@ var reportFatalError = (command, json, error) => {
 // package.json
 var package_default = {
   name: "@n-seiji/nuthatch",
-  version: "0.2.1",
+  version: "0.2.2",
   description: "git worktree manager (hop)",
   homepage: "https://github.com/n-seiji/nuthatch#readme",
   bugs: {

package/dist/{cli-pick-yjd4qpd9.js → cli-pick-8qtma4v0.js} RENAMED Viewed

@@ -1,10 +1,10 @@
 import"./cli-ph0gp56k.js";
 import {
   rm2
-} from "./cli-9n04gsq1.js";
+} from "./cli-vt5mddc4.js";
 import {
   root2
-} from "./cli-hz0r7zw8.js";
+} from "./cli-aj2y82fq.js";
 import {
   graphemes,
   displayWidth,
@@ -26,7 +26,7 @@ import {
   isOptionLikeRef,
   loadRepoContext,
   worktreeDirtyState
-} from "./cli-y8vsqre6.js";
+} from "./cli-4f1vz23g.js";
 import {
   EXIT_CANCELLED,
   ok

package/dist/{cli-update-x0r4b4xk.js → cli-update-rjqr81xx.js} RENAMED Viewed

@@ -3,7 +3,7 @@ import {
   wantsJson,
   reportFatalError,
   VERSION
-} from "./cli-sre95k9x.js";
+} from "./cli-mx5n3y1f.js";
 import {
   messageOf
 } from "./cli-ph0gp56k.js";

package/dist/{cli-9n04gsq1.js → cli-vt5mddc4.js} RENAMED Viewed

@@ -9,7 +9,7 @@ import {
   loadRepoContext,
   nestedWorktrees,
   worktreeDirtyState
-} from "./cli-y8vsqre6.js";
+} from "./cli-4f1vz23g.js";
 import {
   EXIT_GENERAL_ERROR,
   EXIT_USAGE_ERROR,

package/dist/cli.js CHANGED Viewed

@@ -9,7 +9,7 @@ import {
   wantsJson,
   reportFatalError,
   VERSION
-} from "./cli-sre95k9x.js";
+} from "./cli-mx5n3y1f.js";
 import {
   GIT_EXECUTABLE_OVERRIDE_ENV,
   GIT_NOT_FOUND_ERROR_CODE,
@@ -442,14 +442,14 @@ var getPorts = () => {
 var JSON_FLAG = "json";
 var runLs = async (json) => {
   const [{ ls }, { reportLs }] = await Promise.all([
-    import("./ls-3hyjf60d.js"),
+    import("./ls-hvwtaxv8.js"),
     import("./render-ls-x4hpnsvy.js")
   ]);
   const { git, fs } = getPorts();
   reportLs(await ls(git, fs, { cwd: process.cwd() }), json);
 };
 var runJump = async (target, options) => {
-  const { jump } = await import("./jump-1zkraat1.js");
+  const { jump } = await import("./jump-vrwxwb1f.js");
   const { git, fs } = getPorts();
   const result = await jump(git, fs, {
     cwd: process.cwd(),
@@ -465,7 +465,7 @@ var runInteractivePick = async (json) => {
     loadPickCandidates,
     renderSwitchRootOutcome,
     runInteractivePicker
-  } = await import("./cli-pick-yjd4qpd9.js");
+  } = await import("./cli-pick-8qtma4v0.js");
   const { git, fs } = getPorts();
   const candidates = await loadPickCandidates(git, fs, json);
   if (candidates === null) {
@@ -524,7 +524,7 @@ var runRm = async (tokens) => {
     positionals: [{ name: "branch", required: true }],
     booleans: ["force", JSON_FLAG]
   });
-  const { rm } = await import("./rm-eg3j8ae1.js");
+  const { rm } = await import("./rm-a5d1c4mh.js");
   const { git, fs } = getPorts();
   const result = await rm(git, fs, {
     cwd: process.cwd(),
@@ -537,7 +537,7 @@ var runClean = async (tokens) => {
   const args = parseCliArgs(tokens, {
     booleans: ["ext", "withBranch", "dryRun", "yes", JSON_FLAG]
   });
-  const { clean } = await import("./clean-rn2476my.js");
+  const { clean } = await import("./clean-6q90wtve.js");
   const { git, fs, term } = getPorts();
   const result = await clean(git, fs, term, {
     cwd: process.cwd(),
@@ -554,7 +554,7 @@ var runRoot = async (tokens) => {
     booleans: [JSON_FLAG],
     strings: ["track"]
   });
-  const { root } = await import("./root-49vcb8x2.js");
+  const { root } = await import("./root-zbrsb9md.js");
   const { git, fs } = getPorts();
   const { branch } = args.positionals;
   const { track } = args.strings;
@@ -592,7 +592,7 @@ var dispatchAndRun = async (dispatch) => {
   await (command === undefined ? runJumpFromArgs(dispatch.args) : command(dispatch.args));
 };
 var runUpdate = async (rawArgs) => {
-  const update = await import("./cli-update-x0r4b4xk.js");
+  const update = await import("./cli-update-rjqr81xx.js");
   await update.runUpdate(rawArgs, getPorts().term);
 };
 var main = async () => {

package/dist/{jump-1zkraat1.js → jump-vrwxwb1f.js} RENAMED Viewed

@@ -8,7 +8,7 @@ import {
   refArgumentRejection,
   loadRepoContext,
   resolveBranchCheckout
-} from "./cli-y8vsqre6.js";
+} from "./cli-4f1vz23g.js";
 import {
   EXIT_GENERAL_ERROR,
   EXIT_SAFE_REJECTION,

package/dist/{ls-3hyjf60d.js → ls-hvwtaxv8.js} RENAMED Viewed

@@ -4,7 +4,7 @@ import {
 import {
   loadRepoContext,
   worktreeDirtyState
-} from "./cli-y8vsqre6.js";
+} from "./cli-4f1vz23g.js";
 import {
   ok
 } from "./cli-77yanq37.js";

package/dist/{rm-eg3j8ae1.js → rm-a5d1c4mh.js} RENAMED Viewed

@@ -1,6 +1,6 @@
 import {
   rm2
-} from "./cli-9n04gsq1.js";
+} from "./cli-vt5mddc4.js";
 import"./cli-ph0gp56k.js";
 export {
   rm2 as rm

package/dist/{root-49vcb8x2.js → root-zbrsb9md.js} RENAMED Viewed

@@ -1,6 +1,6 @@
 import {
   root2
-} from "./cli-hz0r7zw8.js";
+} from "./cli-aj2y82fq.js";
 import"./cli-ph0gp56k.js";
 export {
   root2 as root

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@n-seiji/nuthatch",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "git worktree manager (hop)",
   "homepage": "https://github.com/n-seiji/nuthatch#readme",
   "bugs": {

package/dist/{cli-y8vsqre6.js → cli-4f1vz23g.js} RENAMED Viewed

@@ -12,14 +12,14 @@ import {
   classifyWorktreePath
 } from "./cli-a56b2ar0.js";
+// src/infra/repo.ts
+import { basename, dirname, join } from "node:path";
 // src/domain/branch-name.ts
 var isOptionLikeRef = (name) => name.startsWith("-");
 var optionLikeRefRejection = (label, name) => isOptionLikeRef(name) ? fail(EXIT_USAGE_ERROR, `Refusing ${label} "${name}": names starting with "-" would be parsed as git options.`) : null;
 var refArgumentRejection = (branch, track) => optionLikeRefRejection("branch", branch) ?? (track === undefined ? null : optionLikeRefRejection("--track ref", track));
-// src/infra/repo.ts
-import { basename, dirname, join } from "node:path";
 // src/domain/tracking.ts
 var resolveTrackingRef = (branch, remotes) => {
   if (remotes.includes("origin")) {