@n-seiji/nuthatch 0.1.3 → 0.1.5

package/README.ja.md

@@ -24,7 +24,7 @@
 
 ```sh
 hop                # worktree/branch を対話的に選んで cd
-hop feat/foo       # feat/foo の worktree へ cd — 未作成ならその場で作成
+hop feat/foo       # feat/foo の worktree へ cd (未作成なら --create でその場で作成)
 hop root           # root clone へ cd
 hop -              # 直前の worktree へ戻る
 
@@ -38,6 +38,10 @@ hop root -         # root clone を元に戻す (root の branch のみ; swap
 hop -- <branch>    # 予約コマンドと被る branch 名をエスケープ
                    # (`hop` 自体と同名の branch (例: `hop -- hop`) にも必要)
 hop --help         # usage を表示 (-h / hop help でも同じ)
+
+hop --version          # hop の version を表示
+hop --update           # 最新リリースへ、インストールした方法のまま更新
+hop --update --check   # --update が何をするかを報告するだけ — 何も変更しない
 ```
 
 同じ branch が複数の worktree で checkout されている場合、branch だけを指定する
@@ -79,14 +83,14 @@ picker は terminal の alternate screen buffer (fzf や vim と同じ仕組み)
 ### 対話的 picker のキー
 
 action panel は候補一覧の隣に列として表示される (overlay ではない) ので、
-action を選ぶ間も一覧が見え続ける。60 列未満の terminal では横に並べられ
-ないため、一覧の下にスタックする形にフォールバックする。
+action を選ぶ間も一覧が見え続ける。横に並べられない幅 (おおよそ 94 列
+未満) の terminal では、一覧の下にスタックする形にフォールバックする。
 
 | キー | 動作 |
 |---|---|
 | `Enter` | 選択中の候補へ cd |
 | `Tab`, `→`, `Ctrl+L`, `Ctrl+F` | 選択中の候補の action panel を開く (ここで cd / 削除 / root 切替) |
-| `Ctrl+X` | 選択中の worktree を削除 (`external` は先に y/N を確認) |
+| `Ctrl+X` | 選択中の worktree を削除 (常に先に y/N を確認) |
 | `Ctrl+R` | root clone を選択中の branch へ切替 (`external` は先に y/N を確認) |
 | `↑`/`↓`, `Ctrl+P`/`Ctrl+N`, `Ctrl+K`/`Ctrl+J` | 選択を移動 (矢印・emacs・vim キーがすべて併用可) |
 | `Esc` | 静かにキャンセル — exit 0、stdout は空のまま (shell wrapper は cd しない) |
@@ -99,8 +103,9 @@ action panel 内: 同じ上下移動キー (左右は閉じる操作に予約さ
 対になっている; `Tab` はどちらの状態からでもトグルする — Ghostty のように
 Cmd+K のようなキーの組み合わせを Tab に remap する terminal で便利)。
 `delete` はすでに作成済みの worktree (`managed` / `external`) すべてに
-表示される (`external` の削除は panel からでも Ctrl+X からでも必ず y/N
-を確認する); `switch root here` は root worktree 自身には表示されず、
+表示される (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 を
@@ -137,6 +142,42 @@ install script は `hop` を `~/.local/bin` に置き (`HOP_INSTALL_DIR` で
 には `HOP_VERSION=vX.Y.Z` を使う。Linux arm64 はビルド済みバイナリが
 まだないため、npm install を使う。
 
+### 更新
+
+```sh
+hop --update          # 最新リリースへ、インストールした方法のまま更新
+hop --update --check  # 報告だけ: current / latest / method / 実行されるコマンド
+hop --version         # 今どの version か
+```
+
+`hop --update` は hop のインストール方法を判定する。`install.sh` で入れた
+バイナリは、置き場のディレクトリに書き込めて (バイナリと checksum の
+ダウンロードの前に確認する)、かつリリースに添付された `.sha256` と SHA-256 が
+一致した場合にだけその場で差し替える — 不一致なら何も置換しない。
+mise / npm / bun 経由の install は、そのツール自身の upgrade コマンド
+(`mise upgrade …`、
+`npm install -g --prefix <hop が入っている prefix> @n-seiji/nuthatch@latest`、
+`bun add -g @n-seiji/nuthatch@latest`) をホームディレクトリで実行して更新する
+ので、グローバルの mise 設定で固定した version が優先され (hop は先に mise へ
+問い合わせ、upgrade するものが無ければ警告する)、プロジェクトの `mise.toml`
+には左右されず、npm の更新は hop が今入っている prefix に入る。`npx` / `bunx`、
+ソースチェックアウト、Homebrew・Nix・aqua・proto など他のバージョン管理ツール
+が自分用にコピーを持っているバイナリ、hop が扱わない配置 (pnpm・yarn の
+global、プロジェクトの依存) は、代わりにどうすればよいかを示して拒否する。
+hop がネットワークに出るのはこれだけで、GitHub と npm の固定アドレスへの
+HTTPS リクエストのみ (タイムアウトとサイズ上限つき)。
+
+## トラブルシューティング
+
+`hop: git executable not found. Looked in: …` は git のバイナリを見つけられ
+なかったという意味。hop は `PATH` の絶対パスエントリを順に探し、その後
+`/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin` を見る。git が
+それ以外の場所にある場合は、直接指定する:
+
+```sh
+export HOP_GIT=/path/to/git
+```
+
 ## Agent skill (Claude Code / Codex plugin)
 
 このリポジトリは plugin marketplace も兼ねており、

package/README.md

@@ -26,7 +26,7 @@ doesn't exist yet. Built for humans (interactive picker) and AI coding agents
 
 ```sh
 hop                # pick a worktree/branch interactively and cd into it
-hop feat/foo       # cd into feat/foo's worktree — created on demand
+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
 
@@ -40,6 +40,10 @@ hop root -         # switch the root clone back (only root's branch; a swapped-o
 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           # update hop to the latest release, the way it was installed
+hop --update --check   # only report what --update would do — changes nothing
 ```
 
 If Git reports the same branch checked out in multiple worktrees, the
@@ -87,14 +91,14 @@ screen on exit, however it exits (selection, Esc/Ctrl-C, or an interrupt).
 
 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
-narrower than 60 columns it falls back to stacking below the list instead,
-since the two can't fit side by side.
+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 (asks y/N first for an `external` worktree) |
+| `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`/`Ctrl+J` | 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) |
@@ -106,8 +110,9 @@ 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` — deleting
-an `external` one always asks y/N, whether from the panel or Ctrl+X); `switch
+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
@@ -123,9 +128,6 @@ eval "$(hop init zsh)"
 
 ## Install
 
-> Not released yet — no version has been published or tagged. Once the first
-> `v*` tag ships, the options below will work as described.
-
 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
@@ -146,6 +148,42 @@ The install script places `hop` in `~/.local/bin` (override with
 specific version with `HOP_VERSION=vX.Y.Z`. Linux arm64 has no prebuilt
 binary yet — use the npm install instead.
 
+### Updating
+
+```sh
+hop --update          # update to the latest release, the way hop was installed
+hop --update --check  # just report: current, latest, method, and the command it would run
+hop --version         # which version do I have?
+```
+
+`hop --update` detects how hop was installed. A binary from `install.sh` is
+replaced in place, but only if its directory is writable (checked before the
+binary or its checksum is downloaded) and only after its SHA-256 matches the
+`.sha256` attached to the release — on a mismatch nothing is replaced. A mise /
+npm / bun install is updated by running that tool's own upgrade command from
+your home directory (`mise upgrade …`,
+`npm install -g --prefix <the prefix hop lives in> @n-seiji/nuthatch@latest`,
+`bun add -g @n-seiji/nuthatch@latest`), so a version pinned in your global mise
+config still wins (hop asks mise first and warns when it has nothing to
+upgrade), a project's own `mise.toml` cannot interfere, and an npm update lands
+in the prefix hop is already in. `npx` / `bunx`, a source checkout, a binary
+that Homebrew, Nix, aqua, proto or another version manager keeps its own copy
+of, and layouts hop does not drive (a pnpm or yarn global, a project
+dependency) are refused with a note on what to do instead. This is the only
+thing hop does over the network: HTTPS requests to fixed GitHub and npm
+addresses, each with a timeout and a size cap.
+
+## Troubleshooting
+
+`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:
+
+```sh
+export HOP_GIT=/path/to/git
+```
+
 ## Agent skill (Claude Code / Codex plugin)
 
 This repo doubles as a plugin marketplace that ships the