fuzgit documentationfuzgit ドキュメント

fuzgit is a git CLI built around picking, searching and tracing with a fuzzy finder. The goal is to let you finish everyday git work without remembering branch names or commit hashes exactly: you narrow the list down and pick.

Every subcommand follows the same model — build the candidate list → filter and pick it in the fuzzy finder (with a preview) → run the git operation. The fuzzy finder is skim embedded as a library, so no external fzf or sk binary is needed.

• Package name: fuzgit
• Command (binary) name: gz

fuzgit speaks English and Japanese, English being the default (see Language). Console excerpts on this page show the default English display.

fuzzy finder で「選ぶ」「探す」「辿る」ことを軸にした git 操作 CLI ツールです。

ブランチ名やコミットハッシュを正確に覚えていなくても、絞り込みと選択だけで日常的な git 操作を完結できることを目指しています。すべてのサブコマンドが 候補一覧の取得 → fuzzy finder で絞り込み・選択（＋プレビュー）→ git 操作の実行という同じ操作モデルに従います。fuzzy finder は skim をライブラリとして組み込んでいるため、 外部の fzf / sk バイナリは不要です。

• パッケージ名: fuzgit
• 実行コマンド名（バイナリ名）: gz

• git on the system (required). fuzgit reads the repository with gix, but every write (switch, cherry-pick, restore, add, stash…) and every coloured diff preview runs the system git. Without it on PATH, fuzgit stops with “git was not found. Install git and make sure it is on your PATH”.
• Git 2.38 or newer — only for the conflict prediction of gz merge. The prediction needs git merge-tree --write-tree. On older git the prediction is skipped and the merge still runs; the confirmation prompt says so.
• Git 2.32 or newer — only for the gz stash preview. It asks git stash show for --include-untracked. Older git shows an error in the preview pane; picking and applying a stash still works. Anything that satisfies the 2.38 above satisfies this too.
• A stable Rust toolchain — only to build from source. Rust 1.85 or newer (the crate uses edition 2024); development is verified with 1.95.0.

• システムの git（必須）
  リポジトリの読み取りには gix を使いますが、書き込み（switch・cherry-pick・ restore・add・stash など）と プレビュー用の色付き差分は、いずれもシステムの git を 実行します。PATH 上に無い場合は「git コマンドが見つかりません」と 表示して停止します。
• Git 2.38 以降 — gz merge のコンフリクト予測にのみ必要
  予測には git merge-tree --write-tree を使います。それより古い git では予測だけを省略し、merge はそのまま実行します （省略した旨は確認プロンプトに表示されます）。
• Git 2.32 以降 — gz stash のプレビューにのみ必要
  git stash show に --include-untracked を渡すためです。 これより古い git ではプレビューにエラーが出ますが、stash の選択と適用は動きます。 上の 2.38 を満たしていれば、こちらも満たされます。
• stable の Rust ツールチェイン — ソースからビルドする場合のみ
  Rust 1.85 以降（edition 2024 のため）。開発時の確認は 1.95.0 です。

macOS — Homebrew

brew install hatohato25/fuzgit/fuzgit

Linux / WSL — install script

curl -fsSL https://raw.githubusercontent.com/hatohato25/fuzgit/main/install.sh | sh

It downloads the release tarball for your machine, verifies its SHA-256 checksum, and puts gz in ~/.local/bin. No sudo, and nothing outside that directory. If that directory is not on PATH, the script prints the line to add — it does not edit your shell profile for you.

curl -fsSL .../install.sh | sh -s -- --bin-dir /usr/local/bin

Only x86_64 is published for Linux today. On aarch64 the script stops and points at the source build rather than installing a binary that cannot run.

From source

fuzgit is not published to crates.io, so clone the repository and install from the local checkout.

git clone https://github.com/hatohato25/fuzgit.git
cd fuzgit
cargo install --path .

This installs ~/.cargo/bin/gz (the package is fuzgit, the command is gz).

To try it without installing:

cargo build --release
./target/release/gz --help

macOS — Homebrew

brew install hatohato25/fuzgit/fuzgit

Linux / WSL — インストールスクリプト

curl -fsSL https://raw.githubusercontent.com/hatohato25/fuzgit/main/install.sh | sh

実行環境に合うリリース資産を取得し、SHA-256 チェックサムを検証した うえで gz を ~/.local/bin へ配置します。 sudo は不要で、そのディレクトリの外には何も書きません。 PATH に無い場合は追加すべき行を表示するだけで、 シェルの設定ファイルは書き換えません。

curl -fsSL .../install.sh | sh -s -- --bin-dir /usr/local/bin

現在 Linux 向けに配布しているのは x86_64 のみです。 aarch64 では動かないバイナリを入れずに停止し、ソースからの ビルドを案内します。

ソースからインストール

crates.io へは未公開のため、リポジトリを取得してローカルからインストールします。

git clone https://github.com/hatohato25/fuzgit.git
cd fuzgit
cargo install --path .

~/.cargo/bin/gz がインストールされます（パッケージ名は fuzgit、コマンド名は gz）。

インストールせずに試す場合:

cargo build --release
./target/release/gz --help

Running gz with no arguments, or gz --help, lists the subcommands.

引数なしの gz および gz --help で サブコマンド一覧を表示します。

An option gets a short form only when git itself spells it the same way — gz restore -S (git restore -S), gz fetch -p (git fetch -p), gz pull -r (git pull -r), gz branch delete -f (git branch -f) and so on. fuzgit-specific options are long-only, and a letter git already uses for something else is never reused: gz worktree add takes no short form because git has no short spelling for it either.

オプションの短縮形は、git 本体に同じ意味の綴りがあるものだけに 付けています（gz restore -S = git restore -S、gz fetch -p = git fetch -p、gz pull -r = git pull -r、gz branch delete -f = git branch -f など）。fuzgit 固有のオプションは長い綴りだけとし、 git が別の意味で使っている文字は流用しません。gz worktree add に 短縮形が無いのは、git 側にも対応する綴りが無いからです。

Each command heading below carries chips for what the section contains. They describe the section as a whole — an option or a subcommand inside it, not necessarily the bare command.

• network talks to a remote.
• y/N asks before something you cannot take back.
• multi-select Tab picks more than one candidate.

以下の各コマンド見出しには、その節に何が含まれるかを示すチップを付けています。 対象は節全体であり、素のコマンドではなく中のオプション・サブコマンドを 指している場合もあります。

• 通信 リモートと通信します。
• y/N 取り消せない操作の前に確認します。
• 複数選択 Tab で複数の候補を選べます。

Every command that lists files — gz restore, gz add, gz commit, gz status — prefixes each line with the same two status characters as git status --short, in the same colours: green for the index (staged) column, red for the working-tree column, and red for both characters of an untracked file (??).

One thing differs: the two characters are left-aligned. A change that exists only in the working tree reads M  where git writes  M. The column stays two characters wide, so the paths still line up.

ファイルを一覧するコマンド（gz restore・ gz add・gz commit・ gz status）は、行頭に git status --short と同じ 2 文字の状態コードを、同じ配色で表示します — index（staged）列は緑、作業ツリー列は赤、未追跡（??）は 2 文字とも赤です。

1 点だけ git と異なり、2 文字を左詰めで表示します。 作業ツリーだけの変更は、git の  M ではなく M  になります。列幅は 2 文字のままなので、パスの開始位置は 揃います。

Every piece of text fuzgit produces — messages, errors, finder headers, confirmation prompts and --help — is available in English and Japanese. The language is detected from your locale, and falls back to English whenever the locale is not Japanese or cannot be interpreted. To pin it explicitly:

git config --global fuzgit.lang ja   # persistent (--local sets it per repository; `en` pins English)
gz --lang ja branch                  # one-off, accepted by every subcommand

fuzgit が表示するすべての文言（メッセージ・エラー・finder のヘッダー・ 確認プロンプト・--help）が日本語と英語に 対応しています。表示言語はロケールから自動的に決まり、 日本語ロケールでない場合や解釈できない場合は英語に なります。明示的に固定するには次のように指定します。

git config --global fuzgit.lang ja   # 永続設定（--local ならリポジトリごと。`en` なら英語に固定）
gz --lang ja branch                  # 単発の上書き。全サブコマンドで指定できる

• Layers 1–3 are strict. They are explicit instructions to fuzgit, so any value other than ja, en or auto stops with an error instead of quietly falling back. An empty value counts as “not set” and resolution moves to the next layer. If reading fuzgit.lang fails altogether, fuzgit stops as well.
• Layer 4 is lenient. Locale variables describe the environment rather than instruct fuzgit, so a value it cannot interpret — C and POSIX included — is not an error; it simply means “not Japanese” and the fallback applies.
• auto means “skip the remaining explicit layers and read the environment”, wherever it appears in layers 1–3.
• There is no fuzgit configuration file. The setting lives in git’s own fuzgit.lang key, read in-process with gix — no git process is started to resolve the language.
• The language resolves outside a repository too, so gz --help and the “not a git repository” error are translated as well; system and global settings still apply there. One exception: a fuzgit.lang written under a conditional include (includeIf) in ~/.gitconfig is not read when resolving outside a repository.

Output that fuzgit parses is a separate matter: those git calls always run with LC_MESSAGES=C, whatever the display language, so parsing never depends on the environment. Debugging shows how the two are told apart in the log.

• 層 1〜3 は厳格です。fuzgit への明示的な指定であるため、 ja / en / auto 以外の値は 黙って既定へ倒さずエラーで停止します。空文字は「未設定」として扱い、 次の層へ進みます。fuzgit.lang の読み取り自体に失敗した場合も 停止します。
• 層 4 は寛容です。ロケール環境変数は fuzgit への指示ではなく 環境の記述であるため、解釈できない値（C / POSIX を 含む）はエラーにせず「日本語ではない」と判定してフォールバックへ進みます。
• auto は層 1〜3 のどこに現れても「以降の明示指定を飛ばして 環境からの自動判定へ進む」という意味です。
• fuzgit 独自の設定ファイルはありません。設定は git config の fuzgit.lang に置き、gix でプロセス内から読みます （言語の解決で git プロセスは起動しません）。
• 言語はリポジトリの外でも解決できます。 gz --help や「git リポジトリではありません」のエラーも 翻訳対象で、system / global の設定はそのまま効きます。ただし ~/.gitconfig の条件付き include（includeIf）配下に 書いた fuzgit.lang は、リポジトリ外での解決では読まれません。

fuzgit がパースする git の出力は別扱いで、表示言語に関わらず 常に LC_MESSAGES=C で実行します（環境によってパースが壊れない ようにするため）。ログ上での見分け方は デバッグを参照してください。

fuzgit has no configuration file of its own. It borrows git’s config, so the usual system / global / local / worktree layers apply, and every key is optional.

fuzgit 独自の設定ファイルはありません。git config を 間借りするため、system / global / local / worktree の階層がそのまま効きます。 いずれのキーも任意です。

gz branch                  # pick a local branch and run git switch (the classic behaviour)
gz branch --all            # also list remote-tracking branches (origin/... and friends)
gz branch create <name>    # pick the starting point and create a new branch
gz branch delete           # pick branches and delete them
gz branch cleanup          # delete every merged branch in one go

With no subcommand, gz branch switches branches — that is the classic behaviour, and --all only widens the candidate list. create / delete / cleanup are separate management operations. Mixing the two is ambiguous, so clap rejects it: gz branch --all create x is an error.

Switching (no subcommand)

• The current branch is marked with a leading *, just like git branch.
• The preview opens with a summary of the highlighted branch — ↑ commits ahead of its upstream in green, ↓ commits behind in red, then the upstream, the last commit date and its author. A count of zero is left uncoloured, so only real drift catches the eye. Underneath are the 50 most recent commits (git log --oneline --decorate). A branch whose details cannot be read keeps the log and drops the summary.
• Picking a remote-tracking branch (origin/feature) runs git switch with the short name (feature), so git’s DWIM creates the tracking local branch.
• git’s report after the switch is coloured. Uncommitted changes carried across show their status letter in colour — A green, M yellow, D red — while the path stays plain, and Switched to branch 'x' is green. Already on 'x' and the tracking lines that follow are dimmed, since nothing happened there. git splits this report across both streams, so stdout and stderr are judged for colour separately: gz branch > file leaves the file clean. Set NO_COLOR to turn it off.

gz branch create <name> — creating a branch

• What you pick is the starting point: local branches, remote-tracking branches and tags. Each line is prefixed with its kind ([branch] in green, [tag] in yellow) because the two can share a name.
• It runs git branch -- <name> <start point>, then switches to the new branch — the same as git switch -c. --no-switch creates it only, and prints the command to switch.
• The name is a positional argument, because skim has no text input (see Out of scope). Validation is git’s check-ref-format; a name starting with - is protected with -- and then rejected by git.

gz branch delete — deleting branches

• Candidates are local branches except the current branch and branches checked out in another worktree (git refuses to delete either).
• A candidate line is <name> merged|unmerged <relative update time> tracking: <upstream>|no tracking branch. Only information that can be gathered for every branch at once is put on the line; details of the last commit are in the preview (git log --oneline).
• Tab selects several branches.

gz branch cleanup — deleting merged branches in one go

• Candidates are limited to merged branches, and they start out selected — except the trunk (use Tab to select or deselect).
• After the confirmation prompt they are deleted with git branch -d. There is no --force — unmerged branches are gz branch delete --force’s job.

gz branch                  # ローカルブランチから選んで git switch（従来どおりの切替）
gz branch --all            # リモート追跡ブランチ（origin/... 等）も候補に含める
gz branch create <name>    # 作成元を選んで新しいブランチを作る
gz branch delete           # ブランチを選んで削除する
gz branch cleanup          # merged なブランチを一括で削除する

サブコマンドなしの gz branch はブランチ切替です （--all は候補の範囲を広げるだけ）。 create / delete / cleanup は別系統の 管理操作で、両者の併用は意図が曖昧になるため clap が拒否します （gz branch --all create x はエラー）。

切替（サブコマンドなし）

• 現在のブランチは git branch と同じく行頭の * で識別できます。
• プレビューの冒頭には選択中ブランチの要約を表示します。upstream より進んでいる コミット数を ↑（緑）、遅れている数を ↓（赤）で示し、 続けて upstream・最終コミット日時・作者が並びます。0 件の側には色を付けないため、 実際に差があるブランチだけが目に留まります。その下が直近 50 件のコミットログ （git log --oneline --decorate）です。要約を取得できなかった ブランチはログだけを表示します。
• リモート追跡ブランチ（origin/feature）を選ぶと短縮名（feature）で git switch するため、git の DWIM により追跡ローカルブランチが作成されます。
• 切り替え後の git の報告に色が付きます。 持ち越した未コミットの変更は状態コードだけを着色し（A 緑、 M 黄、D 赤）、パスは無色のままにします。 Switched to branch 'x' は緑、 Already on 'x' と後続の追跡状況の行は 何も起きていないため Dim にします。git はこの報告を 2 つのストリームへ 振り分けるため、標準出力と標準エラーの着色は別々に判定します （gz branch > file のファイルに色は混ざりません）。 NO_COLOR で止められます。

gz branch create <name> — ブランチの作成

• 選ぶのは作成元です。候補はローカルブランチ・リモート追跡 ブランチ・タグで、同名が共存しうるため行頭に種別が付きます （ブランチは緑の [branch]、タグは黄の [tag]）。
• 実行するのは git branch -- <name> <作成元> で、続けて 作成したブランチへ切り替えます（git switch -c と同じ）。 --no-switch なら作成のみを行い、切り替えるコマンドを案内します。 annotated tag は解決済みの ID を渡し、git が対象コミットまで peel します。
• 名前は位置引数です（skim にテキスト入力 UI が無いため。 スコープ外・非対応参照）。妥当性検証は git の check-ref-format に委ね、- 始まりの名前は -- で保護したうえで git が拒否します。

gz branch delete — ブランチの削除

• 候補はローカルブランチのうち、現在のブランチと、他の worktree で チェックアウト中のブランチを除いたものです（どちらも git が削除を許可しないため）。
• 候補行は <名前> merged|unmerged <相対更新日時> 追跡: <upstream>|追跡なし です。 いずれも全件を一括取得できる情報に限っており、最終コミットの詳細はプレビュー （git log --oneline）で確認します。
• Tab で複数選択できます。

gz branch cleanup — merged なブランチの一括削除

• 候補を merged のブランチのみに絞り、幹を除いて選択済みの状態で 表示します（Tab で選択・解除できます）。
• 確認プロンプトを経て git branch -d で一括削除します。 --force はありません（unmerged を扱うのは gz branch delete --force の役目です）。

gz log                 # 1000 commits by default
gz log --limit 200     # limit how many commits are listed (-n also works)
git show "$(gz log)"   # use the full hash of the picked commit directly
gz log --action        # pick a commit, then pick what to do with it

• Each candidate is one line, <short hash> <date> <summary> (<author>), and that whole string is what you filter on.
• The preview is git show --color=always (commit details and diff).
• On confirmation only the full hash of the picked commit goes to stdout, for pipes and copying. Messages go to stderr, so $(gz log) is safe.
• --action opens a second menu after the commit is picked: show the commit, switch to it as a detached HEAD, cherry-pick, revert, create a fixup commit, and print the full hash. The cherry-pick, revert, and fixup entries run the same code as gz cherry-pick / gz revert / gz fixup, so their safeguards still apply.

gz log                 # 既定 1000 件を候補にする
gz log --limit 200     # 取得件数を制限する（-n でも可）
git show "$(gz log)"   # 選んだコミットのフルハッシュをそのまま使う
gz log --action        # コミットを選んで、続けて行う操作も選ぶ

• 候補は <短縮ハッシュ> <日付> <サマリ> (<作者>) の 1 行で、この文字列がそのまま絞り込み対象です。
• プレビューは git show --color=always（コミットの詳細と差分）。
• 決定すると選択コミットのフルハッシュだけを標準出力へ出します （パイプ・コピー用途）。メッセージ類は標準エラーへ出すため、$(gz log) で 安全に受け取れます。
• --action を付けると、コミットを選んだあとに 2 つ目のメニューが出ます — 詳細を表示する・detached HEAD で切り替える・ cherry-pick する・revert する・fixup コミットを作る・ フルハッシュを出力する。cherry-pick / revert / fixup は gz cherry-pick / gz revert / gz fixup と 同じ実装を呼ぶため、各コマンドの安全策がそのまま働きます。

gz cherry-pick                     # commits from every branch
gz cherry-pick --branch feature    # restrict to one branch

• Tab selects several commits. Whatever order you picked them in, they are always cherry-picked oldest first (history order).
• The candidate limit is 1000, the same as the default of gz log --limit.
• On a conflict, git’s message is shown as-is and the exit code is non-zero. Continue or abort with git cherry-pick --continue / git cherry-pick --abort.

gz cherry-pick                     # 全ブランチのコミットを候補にする
gz cherry-pick --branch feature    # 対象ブランチを指定する

• Tab で複数選択できます。選んだ順に関わらず、常に古い順（履歴順）に cherry-pick します。
• 候補件数の上限は gz log --limit の既定値と同じ 1000 件です。
• コンフリクト時は git のメッセージをそのまま表示して非ゼロ終了します。 続行・中止は git cherry-pick --continue / git cherry-pick --abort で行ってください。

gz restore                       # discard working tree changes (with confirmation)
gz restore --staged              # unstage staged changes
gz restore --source HEAD~1       # overwrite with the content of a revision (with confirmation)

• Tab selects several files. Candidates carry the same status codes as git status. They are left-aligned and coloured like git’s.
• The preview is the diff of the file (with --staged, the diff between HEAD and the index).

gz restore                       # 作業ツリーの変更を破棄する（確認あり）
gz restore --staged              # ステージ済みの変更をアンステージする
gz restore --source HEAD~1       # 指定リビジョンの内容で上書きする（確認あり）

• Tab で複数選択できます。候補には git status と 同じ状態コードが付きます。表示は git と同じ配色で左詰めです。
• プレビューは対象ファイルの差分（--staged 指定時は HEAD とインデックスの差分）。

• Candidates are unstaged changes and untracked files (files that are already staged with no remaining difference do not appear), each line prefixed with the same status code as git status. They are left-aligned and coloured like git’s.
• Tab selects several files.
• The preview is the diff for tracked files, and the file content (up to the first 64 KiB) for untracked files.

• 候補は未ステージの変更と未追跡ファイル（既にステージ済みで差分の無いファイルは 出ません）で、行頭には git status と同じ状態コードが付きます。表示は git と同じ配色で左詰めです。
• Tab で複数選択できます。
• プレビューは追跡ファイルは差分、未追跡ファイルはファイルの内容（先頭 64KiB まで）。

push picks files; apply / pop / drop pick an existing stash. They are separate subcommands because what you pick differs. Bare gz stash prints the subcommand help rather than assuming one of them.

gz stash push                      # pick from the tracked changes and stash them
gz stash push -m "work in progress"  # add a message
gz stash push -u                   # also list untracked files
gz stash apply                     # apply the picked stash (the stash stays)
gz stash pop                       # apply it and drop that stash
gz stash drop                      # discard the picked stash (with confirmation)

• push supports multi-select with Tab, and only the files you picked are stashed (the rest stay in the working tree). Staged changes are stashed too, so the preview is the diff against HEAD (git diff HEAD). Files you have just created are listed as well — no git add first.
• Candidates for apply / pop / drop are stash@{n}: <message>, so you can filter by message. The preview has two sections: files (which paths the stash holds and how much each changed) and diff underneath. Both ask git for --include-untracked, so a stash made only of brand-new files is not a blank pane.

push が選ぶのは「ファイル」、apply / pop / drop が選ぶのは既存の「stash」です。 選択対象が異なるため、フラグではなくサブコマンドで分けています。 引数なしの gz stash は、どちらかへ暗黙に倒さずヘルプを表示します。

gz stash push                      # 追跡済みの変更から選んで退避する
gz stash push -m "作業中"          # メッセージを付ける
gz stash push -u                   # 未追跡ファイルも候補に含める
gz stash apply                     # 選んだ stash を適用する（stash は残る）
gz stash pop                       # 適用して、その stash を取り除く
gz stash drop                      # 選んだ stash を破棄する（確認あり）

• push は Tab で複数選択でき、選んだファイルだけが 退避されます（選ばなかった変更は作業ツリーに残ります）。ステージ済みの変更も 退避対象になるため、プレビューは HEAD との差分（git diff HEAD）です。 作ったばかりのファイルも候補に並びます（先に git add する必要はありません）。
• apply / pop / drop の候補は stash@{n}: <メッセージ> で、メッセージで絞り込めます。 プレビューは 2 段構成で、上に files（含まれるパスと変更量）、 下に diff が出ます。どちらも --include-untracked 付きで取るため、新規ファイルだけを 退避した stash でも空にはなりません。

gz reflog                            # print the commit hash of the picked entry to stdout
gz reflog --restore recovered        # create a new branch `recovered` from the picked commit
gz reflog --action                   # pick an entry, then pick what to do with it

• Candidates are <short hash> HEAD@{n}: <message>, so you can filter on messages such as checkout: moving from ....
• By default only the full hash goes to stdout. The result of --restore goes to stderr, leaving stdout free for pipes.
• --action opens a second menu: show the commit, switch to it as a detached HEAD, cherry-pick, reset the current branch back to it, and print the full hash.
• --restore is not deprecated, and the two flags cannot be combined: use --restore when the operation needs a name you have to type — a finder has no text input — and --action for everything else.
• An entry can point at an object git gc has already removed. Those are listed on purpose; acting on one fails with git’s own message and a non-zero exit.

gz reflog                            # 選んだエントリのコミットハッシュを標準出力へ出す
gz reflog --restore recovered        # 選んだコミットから新規ブランチ `recovered` を作成する
gz reflog --action                   # エントリを選んで、続けて行う操作も選ぶ

• 候補は <短縮ハッシュ> HEAD@{n}: <メッセージ> で、checkout: moving from ... 等のメッセージで絞り込めます。
• 既定ではフルハッシュだけを標準出力へ出します。--restore の 実行結果は標準エラーへ出るため、標準出力はパイプ用途のまま空けてあります。
• --action を付けると 2 つ目のメニューが出ます — 詳細を表示する・detached HEAD で切り替える・ cherry-pick する・現在のブランチをこのコミットへ戻す・ フルハッシュを出力する。
• --restore は非推奨ではありません（両者は同時に 指定できません）。finder にテキスト入力が無いため、入力が必要な名前を 渡すなら --restore、名前を要さない操作なら --action と使い分けてください。
• エントリは git gc で実体を失っている場合があります（意図的に候補へ 出しています）。操作を実行すると git 自身のエラーがそのまま出て非ゼロ終了します。

gz commit                      # commit only the files you picked (message via the editor)
gz commit -m "fix authentication"   # give the message directly (no editor)

• Candidates are staged, unstaged and untracked changes in one single list, each line prefixed with the same status code as git status. They are left-aligned and coloured like git’s.
• Files with staged changes start out selected. Tab deselects them, and a deselected entry never comes back when you keep typing a filter.
• It runs a path-limited commit, git commit -- <paths>..., so changes you did not pick are not committed even if they were staged — they simply stay staged. Untracked files you picked are git added first, since a path-limited commit cannot target them.
• The preview is the diff against HEAD, not against the index, because that is what a path-limited commit records (git diff --color=always HEAD -- <path>; file content for untracked files).
• With no changes at all it prints “There are no candidates to select from” and exits.

git config --global core.editor "code --wait"   # example for VS Code

gz commit                      # 選んだファイルだけをコミットする（メッセージはエディタで入力）
gz commit -m "認証を修正する"   # メッセージを直接指定する（エディタを起動しない）

• 候補はステージ済み・未ステージ・未追跡の変更を1 つの一覧にしたもので、 行頭には git status と同じ状態コードが付きます。表示は git と同じ配色で左詰めです。
• ステージ済みの変更があるファイルは起動時から選択済みです。 Tab で選択を外せます（外した選択が絞り込みのたびに復活することはありません）。
• 実行するのは git commit -- <paths>... のパス指定コミットです。 そのため選ばなかった変更はステージ済みであってもコミットされず、 ステージ状態のまま残ります。選んだ未追跡ファイルは、パス指定コミットの対象に できないため先に git add します。
• プレビューは index ではなく HEAD との差分です（パス指定コミットが記録するのは 作業ツリーの内容であるため。git diff --color=always HEAD -- <path>。 未追跡ファイルは内容）。
• 変更が 1 件も無い場合は「選択できる候補がありません」と表示して終了します。

git config --global core.editor "code --wait"   # VS Code の例

gz fixup            # git commit --fixup=<picked commit>
gz fixup --squash   # git commit --squash=<picked commit>

• What gets committed is the staged changes. With nothing staged it exits before the finder even opens, telling you to stage something with gz add first.
• Candidates are commits reachable from HEAD (1000 by default, shared with gz log --limit). The preview is git show --color=always.
• Afterwards the step that folds the commit into history is printed to stderr. The rebase is never run for you — rewriting history stays an explicit action.

  Hint: run the following to fold the new commit into the history:
    git rebase -i --autosquash <full hash of the picked commit>^

  For the very first commit there is no ^ to resolve, so the starting point becomes --root, with the reason printed alongside.
• --squash makes git open the editor to append the message body (--fixup does not).

gz fixup            # git commit --fixup=<選んだコミット>
gz fixup --squash   # git commit --squash=<選んだコミット>

• コミット対象はステージ済みの変更です。ステージ済みの変更が無い場合は、 finder を起動する前に「ステージ済みの変更がありません」と表示して終了します。
• 候補は HEAD からのコミット（既定 1000 件、gz log --limit の既定値と共通）。 プレビューは git show --color=always。
• 実行後、履歴へ取り込む手順を標準エラーへ表示します。 rebase は自動実行しません（履歴改変は明示操作に委ねます）。

  ヒント: 作成したコミットを履歴へ取り込むには次を実行してください。
    git rebase -i --autosquash <選んだコミットのフルハッシュ>^

  最初のコミットには解決できる ^ が無いため、起点は --root になります（理由も併記します）。
• --squash は git がメッセージ本文の追記のためにエディタを起動します（--fixup は起動しません）。

gz merge             # a normal merge (fast-forwards when it can)
gz merge --no-ff     # always create a merge commit
gz merge --squash    # only apply the result to the working tree and index, without committing
gz merge --ff-only   # merge only when it can fast-forward

• The three options are mutually exclusive (combining them is rejected before the selection starts).
• The merge destination is fixed to the current position (HEAD); candidates are local and remote-tracking branches excluding the current branch.
• The preview is the commits that would be pulled in (git log --oneline HEAD..<candidate>, up to 50).
• A confirmation prompt ([y/N]) comes first, listing how many commits will be merged, the exact command that will run, and the conflict prediction.
• On a conflict, git’s message is shown as-is and the exit code is non-zero. Resolve it with the recovery menu (run gz merge again) or with plain git.

gz merge             # 通常の merge（fast-forward できる場合は fast-forward）
gz merge --no-ff     # fast-forward できる場合でもマージコミットを作る
gz merge --squash    # 結果を作業ツリー・index へ反映するだけでコミットしない
gz merge --ff-only   # fast-forward できる場合のみ merge する

• 3 つのオプションは相互排他です（同時に指定すると選択を始める前に拒否されます）。
• merge 先は現在の位置（HEAD）に固定で、候補は現在のブランチを除くローカルブランチとリモート追跡ブランチです。
• プレビューは取り込まれるコミット（git log --oneline HEAD..<候補>、最大 50 件）。
• 実行前に確認プロンプト（[y/N]）を表示します。 取り込まれるコミット数・実際に実行するコマンド・コンフリクト予測を提示します。
• コンフリクトした場合は git のメッセージがそのまま表示され、非ゼロ終了します。 解決は復帰メニュー（gz merge を再実行）または 素の git で行います。

gz rebase   # pick the base and run git rebase <base>

• Candidates are local and remote-tracking branches excluding the current branch (tags and arbitrary commits are not offered).
• The preview is the commits that would be replayed (git log --oneline <candidate>..HEAD, up to 50).
• On a conflict, git’s message is shown as-is and the exit code is non-zero.

gz rebase   # base を選んで git rebase <base>

• 候補は現在のブランチを除くローカルブランチとリモート追跡ブランチです（tag や任意コミットは候補に含めません）。
• プレビューは replay されるコミット（git log --oneline <候補>..HEAD、最大 50 件）。
• コンフリクトした場合は git のメッセージがそのまま表示され、非ゼロ終了します。

Running gz merge / gz rebase / gz pull while a merge or rebase is in progress shows a recovery menu instead of the usual flow. Its contents are decided by the operation that is in progress (running gz merge during a rebase shows the rebase menu).

• Whichever entry is highlighted, the preview shows the current state (git status --short --branch), so you can tell unresolved (UU) from resolved (M ) on the spot.
• Choosing “inspect the conflicted files and mark them resolved” lists the unmerged files. The preview shows the diff including conflict markers (<<<<<<< and friends), and the files you pick with Tab are git added (staged as resolved). Editing the files themselves is up to your own editor — fuzgit never launches one.
• If you choose that entry with no unresolved files left, it tells you that you can resume with continue and exits.
• continue / skip run with inherited stdio, so git opens the editor when a commit message is needed.
• There is no recovery menu for cherry-pick or revert (that is left to git’s own --continue / --abort guidance).

merge / rebase が進行中の状態で gz merge / gz rebase / gz pull を実行すると、通常のフローではなく 復帰メニューが表示されます。メニューの内容は 進行中の操作の種類で決まります（rebase 進行中に gz merge を実行しても rebase のメニューが出ます）。

• どの項目を選んでいても、プレビューには現在の状態 （git status --short --branch）が出ます。未解決（UU 等）と 解決済み（M ）の区別をその場で確認できます。
• 「コンフリクトファイルを確認して解決済みにする」を選ぶと、コンフリクト中（unmerged）の ファイル一覧が出ます。プレビューにはコンフリクトマーカー （<<<<<<< 等）を含む差分が表示され、 Tab で選んだファイルを git add（＝解決済みとして stage）します。 ファイルの編集そのものは各自のエディタで行ってください（fuzgit はエディタを起動しません）。
• 未解決のファイルが 1 件も無い状態でこの項目を選んだ場合は、continue で再開できる旨を表示して終了します。
• continue / skip は継承 stdio で実行するため、コミットメッセージの入力が必要な場合は git がエディタを起動します。
• cherry-pick / revert には復帰メニューを用意していません（git の --continue / --abort の案内に委ねます）。

gz revert             # revert the picked commits (message reviewed in the editor)
gz revert --no-edit   # commit with git's default message, without opening the editor

• Candidates are commits reachable from HEAD (1000 by default, shared with gz log --limit). The preview is git show --color=always.
• Tab selects several commits. Whatever order you picked them in, they are reverted newest first (undoing an old commit first tends to clash with the later changes stacked on top of it — exactly the opposite of gz cherry-pick).
• Picking several commits opens the editor once per commit unless you pass --no-edit.
• On a conflict, git’s message is shown as-is and the exit code is non-zero. Continue or abort with git revert --continue / git revert --abort.

gz revert             # 選んだコミットを revert する（メッセージはエディタで確認）
gz revert --no-edit   # エディタを起動せず git の既定メッセージのままコミットする

• 候補は HEAD からのコミット（既定 1000 件、gz log --limit の既定値と共通）。プレビューは git show --color=always。
• Tab で複数選択できます。選んだ順に関わらず、常に新しい順に revert します（古いコミットを先に打ち消すと、その上に積まれた後続の変更と衝突しやすいため。 gz cherry-pick の古い順とはちょうど逆になります）。
• 複数件を選ぶと --no-edit を付けない限りエディタが件数分だけ開きます。
• コンフリクトした場合は git のメッセージをそのまま表示して非ゼロ終了します。 続行・中止は git revert --continue / git revert --abort で行ってください。

There are no options. It is a two-step flow: pick the files, then pick the action.

1. File selection (multi-select)

• Candidates are staged, unstaged and untracked changes in one list (the same candidate generation as gz commit), each line prefixed with the same status code as git status. They are left-aligned and coloured like git’s.
• The header summarises the current state in one line:

  main  |  ahead 2 / behind 1  |  staged 2 / unstaged 2 / untracked 1 / stash 1

  Without an upstream the whole ahead/behind block is omitted (on a detached HEAD, detached HEAD is shown instead of the branch name). ahead/behind is computed from the local remote-tracking ref, so it uses no network.
• The preview is split into per-state sections: staged (git diff --cached) when there are staged changes and unstaged (git diff) when there are unstaged ones; sections that do not apply do not run git at all. Untracked files show their content as-is.

2. Action menu (single select)

• Each action is literally the same implementation as the corresponding command, so its safeguards (restore’s confirmation prompt, commit’s pre-add of untracked files) keep working.
• The menu preview shows the current state (git status --short --branch).
• Every message except “print the paths to stdout” goes to stderr, so stdout stays free for pipes.
• With no changes at all it is not an error: it exits with code 0 (checking that the tree is clean is a legitimate use of status). In that case the header-equivalent information goes to stderr.

  $ gz status
  There are no changes (the working tree is clean)
  main  |  staged 0 / unstaged 0 / untracked 0 / stash 0

オプションはありません。ファイルを選ぶ → アクションを選ぶの 2 段構成です。

1. ファイル選択（複数選択）

• 候補はステージ済み・未ステージ・未追跡の変更を 1 つの一覧にしたもの （gz commit と同じ候補生成）で、行頭には git status と 同じ状態コードが付きます。表示は git と同じ配色で左詰めです。
• ヘッダーに現在の状態を 1 行で表示します。

  main  |  ahead 2 / behind 1  |  staged 2 / unstaged 2 / untracked 1 / stash 1

  upstream が設定されていない場合、ahead / behind の区画ごと省略します （detached HEAD ではブランチ名の代わりに detached HEAD と表示します）。 ahead / behind はローカルのリモート追跡参照から算出するため ネットワークを使いません。
• プレビューは状態別のセクションに分かれます。ステージ済みの変更があれば staged（git diff --cached）、未ステージの変更があれば unstaged（git diff）を表示し、該当しないセクションは git を実行しません。未追跡ファイルは内容をそのまま表示します。

2. アクションメニュー（単一選択）

• 各アクションの実体は対応する既存コマンドと同じ実装であり、安全策 （restore の確認プロンプト、commit の未追跡ファイルの事前 add など）も そのまま働きます。
• メニューのプレビューには現在の状態（git status --short --branch）を表示します。
• 「パスを標準出力へ出力する」以外のメッセージ類はすべて標準エラーへ出すため、標準出力はパイプ用途に空いています。
• 変更が 1 件も無い場合はエラーにせず、終了コード 0 で終わります （クリーンな状態の確認も status の用途のため）。この場合はヘッダー相当の情報を 標準エラーへ出します。

  $ gz status
  変更はありません（作業ツリーはクリーンです）
  main  |  staged 0 / unstaged 0 / untracked 0 / stash 0

gz diff              # unstaged changes (same as git diff)
gz diff --staged     # staged changes (same as git diff --staged)
gz diff --head       # HEAD against the working tree (including staged changes)
gz diff --upstream   # HEAD against the upstream (the remote-tracking ref)
gz diff --branch     # pick two branches and compare them
gz diff --commit     # pick two commits and compare them

• The comparison modes are mutually exclusive. The flag names follow git’s own vocabulary.
• --branch / --commit open the fuzzy finder twice, for the left then the right side. The header tells you which one you are picking (1/2 branch to compare from, then 2/2 branch to compare to). Candidates and previews are shared with gz branch and gz log.
• Once the range is fixed, the list of changed files appears so you can narrow it down with Tab. The header shows the chosen range, and the preview is the coloured diff limited to the highlighted file.
• On confirmation it runs git diff <range> -- <pathspec>... with inherited stdio (pager and colour are left to git). Revision comparisons are passed as two arguments, git diff <a> <b>, not as <a>..<b>.
• --upstream stops with a dedicated error when there is no upstream or on a detached HEAD. The right-hand side is the local remote-tracking ref (refs/remotes/<remote>/<branch>), so it uses no network. Run gz fetch first if you want to compare against the latest state.
• When the range contains no changed files it is not an error: it exits with code 0.

  $ gz diff
  There is no difference (Unstaged changes: index and work tree)

gz diff              # 未ステージの変更（git diff と同じ）
gz diff --staged     # ステージ済みの変更（git diff --staged と同じ）
gz diff --head       # HEAD と作業ツリー（ステージ済みの変更も含む）
gz diff --upstream   # HEAD と upstream（リモート追跡参照）
gz diff --branch     # ブランチを 2 回選んで比較する
gz diff --commit     # コミットを 2 回選んで比較する

• 比較モードは相互排他です。フラグ名は git 本体の語彙に合わせています。
• --branch / --commit は比較元・比較先の順に fuzzy finder を 2 回起動します。どちらを選んでいるかはヘッダー （1/2 比較元のブランチ / 2/2 比較先のブランチ）で分かります。 候補・プレビューはそれぞれ gz branch / gz log と共通です。
• 比較範囲が確定すると変更ファイル一覧が出るので、Tab で表示したいファイルを 絞り込めます。ヘッダーには確定した比較範囲を表示し、プレビューは選択中ファイルに 限定した色付き差分です。
• 決定すると git diff <範囲> -- <pathspec>... を継承 stdio で 実行します（ページャ・色は git に委ねます）。リビジョン同士の比較は <a>..<b> ではなく git diff <a> <b> の 2 引数で渡します。
• --upstream は upstream が設定されていない場合・detached HEAD の場合に 専用エラーで停止します。比較先はローカルのリモート追跡参照 （refs/remotes/<remote>/<branch>）であり、 ネットワークを使いません。最新の状態と比べたい場合は先に gz fetch を実行してください。
• 比較範囲に変更ファイルが 1 件も無い場合はエラーにせず、終了コード 0 で終わります。

  $ gz diff
  差分はありません（未ステージの変更: index と作業ツリー）

gz fetch               # decide what (which remote) to fetch and run git fetch
gz fetch --prune       # also clean up tracking refs for branches deleted on the remote
gz fetch --siblings    # pick repositories sitting next to this one and fetch them all

The point of this command is not “pick a remote” but “decide what to fetch”. The fuzzy finder only opens when there is actually a choice.

Default (the current repository)

• The finder only opens when there is more than one remote. Candidates are the registered remote names plus a fixed entry, all remotes, which runs git fetch --all.
• With exactly one remote the finder does not open and the fetch runs immediately, because choosing between the only remote and “all remotes” would contact the same place either way. So that you can still tell what was contacted, one line naming the target is printed to stderr before running (git fetch can print nothing at all when there are no updates).

  $ gz fetch
  Fetching from the remote `origin` (only one remote is registered, so the selection was skipped)

• The preview only shows local information (two sections: the remote URL and the known remote-tracking branches). A remote that has never been fetched has no tracking refs, so that section is omitted entirely. Not using the network in previews is a design rule — see Network operations.
• With no remotes registered at all it suggests git remote add and exits.

--siblings — fetching the repositories next door

Every other fuzgit command touches only the current repository. --siblings is the single exception. Given the flag, it scans the parent directory of the current worktree root, one level deep (never recursively) and offers the directories that contain a .git.

$ gz fetch --siblings
The current repository is preselected. Tab: toggle the selection / Enter: fetch  |  1 excluded (no remote / bare)
>> mike   origin/main
   alpha  origin/main
   zulu   origin/main

The candidate list

• A line is <directory name> <remote>/<current branch>, one pair per remote. A repository whose HEAD points at no branch reads <directory name> <remotes> detached HEAD instead. Columns are padded to the widest value, so the next column starts in the same place on every line.
• The current repository starts selected (Tab deselects it); the others start unselected.
• No remote registered and bare repositories cannot be fetched, so they are excluded — and the header says how many, never silently.
• Linked worktrees of one repository are deduplicated into a single entry, so the same remote is not contacted twice. Symlinked directories are not followed.
• When the current repository is the only target the finder does not open. The reason is printed and the fetch runs.

  $ gz fetch --siblings
  The current repository is the only target, so the selection was skipped
  [1/1] only
  1 succeeded / 0 failed

• The preview is local information only: each remote’s URL, and each local branch’s tracking state from git for-each-ref refs/heads. It runs with --no-optional-locks, so it never takes a lock in somebody else’s repository.

  ── origin ──
  git@github.com:example/big-repo.git
  ── Branch tracking status ──
    develop → origin/develop [ahead 2]
  * main → origin/main [behind 4]

The run

• Each repository runs git fetch [--prune] --all, in parallel. Output is captured and written out as one block per repository when it finishes, headed by [<done>/<total>] <directory name>, so update tables never interleave.
• How many run at once comes from git config fuzgit.fetchJobs — an integer of 1 or more, 4 when unset, and 1 for the fully serial behaviour. An invalid value stops the run before anything is fetched instead of quietly falling back. There is no CLI flag for it.

  git config fuzgit.fetchJobs 8   # or --global

• --prune applies to every selected repository. The finder header says so.
• git config fuzgit.notify true posts a desktop notification when the run finishes (see Completion notifications).
• A failing repository does not stop the run. The rest still execute, and the summary at the end names the ones that failed. If even one fails the exit code is 1; git has already shown the reason, so fuzgit does not repeat it.

  $ gz fetch --siblings
  [1/3] mike
  [2/3] alpha
  [3/3] zulu
  fatal: '/path/to/does-not-exist.git' does not appear to be a git repository
  fatal: Could not read from remote repository.
  2 succeeded / 1 failed (failed: zulu)
  error: Fetching failed for some repositories

• If launching git itself fails (git not installed, say) the run stops there — that is an environment problem, not a per-repository failure.
• With nothing fetchable at all it stops with a dedicated error. So does a bare current repository, or one whose worktree root has no parent directory to scan. It never falls back to just the current repository, so the range you asked for and the place it contacts can never diverge.

  $ gz fetch --siblings
  error: There is no repository to fetch (a repository without a remote and a bare repository are not offered)

Common to both

• git fetch runs with inherited stdio, so the list of updated refs, authentication prompts and progress output are git’s own.
• Network and authentication failures are shown with git’s message as-is and exit non-zero (fuzgit adds no timeout and no retry).

gz fetch               # fetch 対象（リモート）を決めて git fetch する
gz fetch --prune       # リモートで削除されたブランチの追跡参照も掃除する
gz fetch --siblings    # 隣に並ぶリポジトリを選んでまとめて fetch する

このコマンドの主機能は「リモートを選ぶ」ことではなく 「fetch 対象の決定」です。 選択の余地がある場合にだけ fuzzy finder を起動します。

既定（現在のリポジトリ）

• リモートが複数ある場合だけ finder を起動します。候補は登録済みの リモート名に、固定候補「すべてのリモート」を加えたものです。「すべてのリモート」を 選ぶと git fetch --all を実行します。
• リモートが 1 つだけの場合は finder を起動せず、そのまま fetch します。 唯一のリモートと「すべてのリモート」の 2 択は、どちらを選んでも通信先が同じためです。 何に対して通信したのかが分かるよう、実行前に対象を 1 行だけ標準エラーへ示します （git fetch は更新が無ければ何も出力しないことがあるため）。

  $ gz fetch
  リモート `origin` から取得します（登録されているリモートが 1 つのため、選択を省略しました）

• プレビューはローカル情報だけを表示します （「リモート URL」と「既知のリモート追跡ブランチ」の 2 セクション）。一度も fetch して いないリモートは追跡参照が無いため、そのセクションごと省略されます。 プレビューでネットワークを使わないのは設計上の原則です （ネットワーク操作について参照）。
• リモートが 1 つも登録されていない場合は git remote add を促して終了します。

--siblings — 隣のリポジトリもまとめて取得

fuzgit の他のコマンドは現在のリポジトリだけを操作します。 --siblings はその唯一の例外で、フラグを明示したときに限り、 ワークツリー root の親ディレクトリ直下のみを走査し（再帰しません）、 .git を持つディレクトリを候補にします。

$ gz fetch --siblings
現在のリポジトリを選択済みにしています。Tab: 選択の切替 / Enter: 取得  |  除外 1 件（リモート未登録 / bare）
>> mike   origin/main
   alpha  origin/main
   zulu   origin/main

候補一覧

• 候補行は ディレクトリ名 リモート/現在のブランチ で、リモートの数だけ 並びます。HEAD がブランチを指していないリポジトリは ディレクトリ名 リモート detached HEAD と表示します。各列は一覧中で 最も長い値に合わせて空白で埋めるため、右の列の開始位置はすべての行で揃います。
• 現在のリポジトリは起動時から選択済みです （Tab で外せます）。他は未選択です。
• リモート未登録のリポジトリと bare リポジトリは fetch できないため除外し、除外件数をヘッダーに示します（黙って消しません）。
• 同じリポジトリの linked worktree が隣に並んでいる場合は1 件に重複排除します （同じリモートへ二重に通信しないため）。シンボリックリンクのディレクトリは辿りません。
• 対象が現在のリポジトリ 1 件だけの場合は finder を起動せず、 理由を示してそのまま実行します。

  $ gz fetch --siblings
  対象が現在のリポジトリ 1 件のため、選択を省略しました
  [1/1] only
  成功 1 件 / 失敗 0 件

• プレビューはローカル情報だけです（リモートごとの URL と、 git for-each-ref refs/heads によるローカルブランチごとの追跡状況）。 他人のリポジトリでロックを取らないよう --no-optional-locks を付けます。

  ── origin ──
  git@github.com:example/big-repo.git
  ── ブランチの追跡状況 ──
    develop → origin/develop [ahead 2]
  * main → origin/main [behind 4]

実行

• 各リポジトリで git fetch [--prune] --all を並列に 実行します。出力はキャプチャし、完了した順に [<完了件数>/<全体>] <ディレクトリ名> を頭に付けて ひとまとまりで書き出すため、複数リポジトリの更新表が混ざりません。
• 同時実行数は git config fuzgit.fetchJobs で決まります （1 以上の整数。未設定なら 4、1 で完全な直列実行）。 不正な値のときは既定値へ暗黙に倒さず、1 件も fetch しないまま停止 します。CLI のフラグは設けていません。

  git config fuzgit.fetchJobs 8   # --global も可

• --prune は選択したすべてのリポジトリに適用されます （その旨は finder のヘッダーに表示します）。
• git config fuzgit.notify true を設定すると、 完了をデスクトップ通知で知らせます （完了通知参照）。
• 途中で失敗しても中断せず残りを実行し、最後に成功・失敗件数と 失敗したリポジトリ名を集計します。1 件でも失敗すれば終了コード 1 です（失敗理由は git が表示済みのため再掲しません）。

  $ gz fetch --siblings
  [1/3] mike
  [2/3] alpha
  [3/3] zulu
  fatal: '/path/to/does-not-exist.git' does not appear to be a git repository
  fatal: Could not read from remote repository.
  成功 2 件 / 失敗 1 件（失敗: zulu）
  エラー: 一部のリポジトリで取得に失敗しました

• git の起動そのものに失敗した場合（git 未インストール等）は その場で中断します。環境の問題であり、リポジトリごとの失敗ではないためです。
• fetch できるリポジトリが 1 件も無い場合、現在のリポジトリが bare の場合、 ワークツリー root の親ディレクトリを取得できない場合は、いずれも専用エラーで 停止します。暗黙に現在のリポジトリだけへ倒すことはしません （指定した範囲と通信先が食い違わないようにするため）。

  $ gz fetch --siblings
  エラー: fetch できるリポジトリがありません（リモートが登録されていないリポジトリと bare リポジトリは対象になりません）

共通

• git fetch は継承 stdio で実行するため、更新された参照の一覧・認証プロンプト・進捗表示は git のものがそのまま出ます。
• ネットワーク・認証の失敗は git のメッセージをそのまま表示して非ゼロ終了します（fuzgit 側でのタイムアウト・リトライは行いません）。

gz pull            # pick branches and fast-forward them onto their upstream
gz pull --rebase   # rebase the current branch onto its upstream
gz pull --merge    # merge the upstream into the current branch

Without a flag, the only thing you pick is which branches should follow their upstream — several local branches of the current repository. You never pick a remote × branch combination, because the destination is fixed to each branch’s own upstream. There is no --prune and no positional branch name. --rebase and --merge are a different shape entirely; see Two shapes below.

• Candidates are local branches that have an upstream whose branch.<name>.remote is a registered remote name. Branches without an upstream, with an unregistered remote, or checked out in another worktree have no determinable destination, so they are excluded — and the number excluded is shown in the header (never dropped silently).
• The current branch is put first, marked with a leading *  (as in gz branch), and starts selected (Tab deselects it). On a detached HEAD there is simply no current branch, and the other branches are offered as usual (unlike gz pull --rebase / --merge, this is not an error).

  $ gz pull
  The current branch is preselected. Tab: toggle the selection / Enter: integrate with a fast-forward only  |  2 excluded (no upstream / remote not registered / in use by another worktree)
  >> * main       →  origin/main
       feature-a  →  origin/feature-a

• A candidate line is <mark><branch> → <short upstream name>. ahead / behind is deliberately not shown: at that moment fuzgit only knows the last fetch’s tracking refs, which is not how much is about to arrive, and a stale “not behind” would mislead. The real figure appears in git’s own update table at run time.
• The preview is headed ── Commits not integrated yet (as of the last fetch) ── and shows the commits between the branch and its locally stored tracking ref (git log --oneline <branch>..<tracking ref>). The heading states that the information is as of the last fetch: the preview uses no network (see Network operations).
• With only one candidate the finder does not open; the target and the reason are printed in one line and the run starts.

  $ gz pull
  Integrating `main` (there is only one candidate, so the selection was skipped)
  [1/1] main
  1 succeeded / 0 failed

• With no candidates at all it stops and explains how to set an upstream (git push -u <remote> <branch> / git branch --set-upstream-to=<remote>/<branch>).
• Execution starts with git fetch <remote> once per remote that the selected upstreams belong to (never once per branch). If one remote fails to fetch, every branch whose upstream lives on that remote is recorded as failed and skipped, while branches on other remotes continue — so nothing is ever integrated implicitly from a stale tracking ref.
• Integration then happens one branch at a time, serially, in candidate order (never in parallel). Before each one, [<n>/<total>] <branch> is printed to stderr (same format as gz fetch --siblings), because git’s update tables and rejection reasons also go to stderr.
• The currently checked out branch is integrated with git merge --ff-only <tracking ref> (the working tree and index have to be updated), while every other branch uses git fetch . <tracking ref>:refs/heads/<branch> (updating only the ref, never touching the working tree). The latter refspec deliberately omits the forcing +: with it, non-fast-forward updates would go through and commits that exist only on that branch would be lost.
• A failing branch does not stop the run; the rest still execute and successes, failures and the failed branch names are summarised at the end. If even one fails the exit code is 1 (git already printed the reason, so fuzgit does not repeat it). Only when at least one branch could not fast-forward is a one-line pointer to the next step added.

  $ gz pull
  [1/4] main
  [2/4] alpha
  [3/4] diverged
  [4/4] zeta
  3 succeeded / 1 failed (failed: diverged)
  A branch that could not fast-forward can be integrated with `gz pull --rebase` or `gz pull --merge` after switching to it
  error: Integrating failed for some branches

  It only points at it — a rebase or merge is never started automatically. How history is integrated (rebase or merge) stays an explicit user choice.
• If launching git itself fails (git not installed, for example) the run stops there, because that is an environment problem rather than a per-branch failure.
• No [y/N] prompt in this shape. Multi-selecting and pressing Enter is already an explicit decision, and a fast-forward loses neither existing commits nor working tree changes — the same judgement as gz fetch --siblings. --rebase / --merge do confirm.
• Run while a merge or rebase is in progress, it shows the recovery menu instead of the branch selection.

Two shapes: fast-forward in bulk, or one branch your way

A branch that plain gz pull could not fast-forward is integrated by switching to it and running gz pull --rebase or gz pull --merge.

The reason --rebase / --merge cover only the current branch is mechanical: a branch that is not checked out can be moved along by copying a ref (git fetch . <tracking>:refs/heads/<branch>), which is fast-forward by definition. Rebasing or merging it would mean switching the working tree, or creating a temporary worktree — both of which put work you have in progress at risk.

gz pull            # 取り込むブランチを選んで、upstream へ fast-forward で追随させる
gz pull --rebase   # 現在のブランチを upstream へ rebase して取り込む
gz pull --merge    # 現在のブランチへ upstream を merge して取り込む

フラグ無しで選ばせるのは「どのブランチを upstream へ追随させるか」だけ です。対象は現在のリポジトリの複数のローカルブランチで、リモート × ブランチの 組み合わせは選ばせません（追随先は各ブランチの upstream に固定）。 --prune やブランチ名の位置引数はありません。 --rebase / --merge は形そのものが異なります — 下の2 つの形を参照してください。

• 候補は upstream が設定され、その branch.<name>.remote が 登録済みのリモート名であるローカルブランチです。upstream が無いもの・ リモートが登録されていないもの・他の worktree でチェックアウト中のものは 取り込み先を決められないため候補から除外し、除外した件数をヘッダーに 示します（黙って消しません）。
• 現在のブランチは一覧の先頭に置き、行頭を *  （gz branch と同じ）でマークして、起動時から選択済みにします （Tab で外せます）。detached HEAD の場合は現在のブランチが無いだけで、 他のブランチは通常どおり候補になります（gz pull --rebase / --merge と 違いエラーにはしません）。

  $ gz pull
  現在のブランチを選択済みにしています。Tab: 選択の切替 / Enter: fast-forward のみで取り込み  |  除外 2 件（upstream 未設定 / リモート未登録 / 他の worktree で使用中）
  >> * main       →  origin/main
       feature-a  →  origin/feature-a

• 候補行は <マーク><ブランチ名> → <upstream の短縮名> です。 ahead / behind は意図的に表示しません。この時点で分かるのは 前回 fetch した追跡参照との差であり、これから取り込む本数とは一致せず、 古い「遅れていない」は誤解を招くためです。実際の本数は実行時に git 自身が出す 更新表で分かります。
• プレビューは ── 未取り込みのコミット（前回の fetch 時点） ── の見出しを 付けて、ローカルに保存済みの追跡参照との差分コミット （git log --oneline <ブランチ>..<追跡参照>）を表示します。 それが前回の fetch 時点の情報であることを見出しで示しており、 プレビューではネットワークを使いません（ネットワーク操作について参照）。
• 候補が 1 件だけの場合は finder を起動せず、対象と省略の理由を 1 行示してそのまま実行します。

  $ gz pull
  `main` を取り込みます（候補が 1 件のため、選択を省略しました）
  [1/1] main
  成功 1 件 / 失敗 0 件

• 候補が 1 件も無い場合は、upstream の設定方法（git push -u <remote> <branch> / git branch --set-upstream-to=<remote>/<branch>）を案内して停止します。
• 実行はまず、選択したブランチの upstream が属するリモートごとに 1 回だけ git fetch <remote> します（ブランチごとに通信しません）。 あるリモートの取得に失敗した場合は、そのリモートを upstream に持つブランチをすべて 失敗として記録して飛ばし、他のリモートのブランチは続行します（古い追跡参照のまま 暗黙に取り込まないためです）。
• 取り込みは候補一覧の順序で 1 ブランチずつ直列に実行します （並列にしません）。実行前に [<何番目>/<全体>] <ブランチ名> を 標準エラーへ表示します（gz fetch --siblings と同形式）。git 自身の更新表や 拒否の理由も標準エラーに出るため、この 1 行が無いとどのブランチの出力なのか 読み取れなくなります。
• 現在チェックアウト中のブランチは git merge --ff-only <追跡参照>（作業ツリーと index を 更新する必要があるため）、それ以外のブランチは git fetch . <追跡参照>:refs/heads/<ブランチ> （参照だけを更新し作業ツリーに触れない）で取り込みます。後者の refspec に強制更新の + は付けません。付けると非 fast-forward の更新が通り、 そのブランチにしか無いコミットを失わせるためです。
• 途中のブランチが失敗しても中断せず残りを実行し、最後に成功件数・ 失敗件数と失敗したブランチ名を集計表示します。1 件でも失敗した場合は 終了コード 1 で終わります（失敗理由は git のメッセージがその場で 表示済みのため、fuzgit は再掲しません）。fast-forward できなかったブランチが 1 件以上あるときだけ、次の手段を 1 行案内します。

  $ gz pull
  [1/4] main
  [2/4] alpha
  [3/4] diverged
  [4/4] zeta
  成功 3 件 / 失敗 1 件（失敗: diverged）
  fast-forward できなかったブランチは、そのブランチへ切り替えてから `gz pull --rebase` または `gz pull --merge` で取り込めます
  エラー: 一部のブランチで取り込みに失敗しました

  案内するだけで、rebase や merge を自動で始めることはありません。 履歴の統合方法（rebase か merge か）はユーザーの明示指定に限ります。
• git の起動そのものに失敗した場合（git 未インストール等）は、 その場で中断します。環境の問題でありブランチごとの失敗ではないためです。
• この形では [y/N] の確認プロンプトはありません。 複数選択して Enter を押すこと自体が明示的な決定であり、fast-forward は 既存のコミットも作業ツリーの変更も失わせないためです （gz fetch --siblings と同じ判断）。--rebase / --merge では確認します。
• merge / rebase が進行中の状態で実行した場合は、ブランチ選択ではなく 復帰メニューが表示されます。

2 つの形 — まとめて fast-forward か、1 本を方式を選んで取り込むか

フラグ無しの gz pull で fast-forward できなかったブランチは、 そのブランチへ切り替えてから gz pull --rebase または gz pull --merge で取り込みます。

--rebase / --merge が現在のブランチだけを対象に するのは機構上の理由です。チェックアウトしていないブランチは参照のコピー （git fetch . <tracking>:refs/heads/<branch>）でしか 追随させられず、これは定義上 fast-forward です。rebase や merge を行うには 作業ツリーを切り替えるか一時 worktree を作る必要があり、いずれも進行中の作業を 危険に晒します。

gz worktree                  # pick from the list and print the path to stdout
cd "$(gz worktree)"          # shell integration (move to the picked worktree)
gz worktree add <name>       # pick a branch and create a new worktree next to the repository
gz worktree add -a <name>    # offer remote-tracking branches as well
gz worktree add -b <branch> <name>   # create a new branch for it, picking its starting point
gz worktree remove           # pick a worktree and remove it (with confirmation)
gz worktree remove --force   # same, discarding modified and untracked files inside it (with a warning)
gz worktree prune            # tidy up bookkeeping for worktrees whose directory is gone (with confirmation)

No arguments (list, then print the path)

• A candidate line is <path> main|linked <branch|detached|bare>[ locked][ prunable].
• The preview shows the commit log of the highlighted worktree’s HEAD (bare worktrees and worktrees without a single commit get no preview).
• On confirmation only the path of the picked worktree goes to stdout; messages go to stderr.

gz worktree add <name>

• What you pick in the fuzzy finder is the branch to check out. Candidates are limited to branches not in use by another worktree (git cannot check out the same branch in two worktrees at once).
• -a adds remote-tracking branches, exactly as gz branch -a does. Picking origin/feature hands git the short name (feature) and git’s DWIM creates the local branch that tracks it. The “in use elsewhere” filter is applied to that short name, so origin/feature disappears from the list while a local feature is checked out in another worktree — picking it could only ever fail. A local branch and its remote counterpart are both listed, as in gz branch -a.
• The worktree is always created next to the repository root, whatever directory you run the command from. Given a repository at product/infrastructure/, gz worktree add sample creates product/sample/. A worktree holds the whole tree below .git, so placing it beside the repository reads more naturally than nesting it inside — and a worktree inside the repository shows up as an untracked embedded repository that you then have to gitignore.
• Because that is not where you ran the command, the resulting path is printed to stderr once the worktree exists. (Not stdout: git worktree add writes HEAD is now at ... there itself, so stdout could never carry the path alone.)
• The argument is a name. Anything containing a path separator (../sample, a/b, an absolute path), as well as . and .., is refused with an explanation rather than being reinterpreted.
• It runs git worktree add -- <resolved path> <branch>. Names are never suggested automatically.
• For a name starting with -, write gz worktree add -- -dashy (that -- is clap’s; fuzgit adds its own -- when calling git).

-b <branch> — when there is no branch left to pick

With one local branch (main) checked out by the main worktree, the candidate list is empty and gz worktree add is a dead end. -b is the way out: it creates a new branch and puts that in the worktree.

• The starting point is not fixed to HEAD. Cutting a work branch from main is the common case, but the main worktree is often on something else — HEAD would give you the wrong parent. main / master are sorted first, so Enter alone usually lands where you meant.
• A name already taken by a local branch stops the command before the finder opens, and says that dropping -b would put that branch in the worktree instead.
• The upstream is left to git’s own default: it is set only when the starting point is a remote-tracking branch, matching what gz branch create produces.
• -b and --no-install are independent. The dependency install and the .claude/ copy run for -b too.

Installing dependencies

After the worktree exists, fuzgit looks for lockfiles and installs the dependencies. What it searches is the tracked files — it asks git ls-files rather than walking the filesystem, so node_modules/ and target/ are never in the way and there is no depth limit.

• With more than one directory to install into, you pick them. A line is <path> <the commands that would run>, and the preview is the lockfile itself. Tab selects several; they run in order with [<n>/<total>] in front.
• The directory you ran the command in starts selected, so pressing Enter installs exactly what it would have installed before this was a choice.
• With only one directory the finder does not open — a single-project repository behaves as it always did.
• Cargo and Go are not offered. Their dependencies live in a global cache and are fetched at build time, so a fresh worktree has nothing to install.
• --no-install skips all of this, finder included.

gz worktree remove

• Candidates are linked worktrees only — the main worktree is not offered (git does not allow removing it).
• Locked worktrees, and worktrees with modified or untracked files when --force is not given, fail with git’s message as-is and a non-zero exit code.
• -f / --force passes --force to git worktree remove (once — a locked worktree is still refused), and the confirmation prompt then warns that modified and untracked files inside the worktree are discarded as well.

gz worktree prune

• It first runs git worktree prune --dry-run --verbose and puts the worktrees that would be pruned, with the reason, into the confirmation prompt. git worktree prune runs only if you approve.
• With nothing to prune it reports so and exits with code 0.

gz worktree                  # 一覧から選んでパスを標準出力へ出す
cd "$(gz worktree)"          # シェル連携（選んだ worktree へ移動する）
gz worktree add <name>       # ブランチを選び、リポジトリの兄弟として worktree を作る
gz worktree add -a <name>    # リモート追跡ブランチも候補に含める
gz worktree add -b <branch> <name>   # 新しいブランチを作って入れる（作成元を選ぶ）
gz worktree remove           # worktree を選んで削除する（確認あり）
gz worktree remove --force   # 変更済み・未追跡のファイルごと削除する（警告つきの確認あり）
gz worktree prune            # 実体を失った worktree の管理情報を整理する（確認あり）

引数なし（一覧 → パス出力）

• 候補行は <パス> main|linked <ブランチ|detached|bare>[ locked][ prunable] です。
• プレビューには選択中 worktree の HEAD のコミットログを表示します（bare とコミットが 1 件も無い worktree はプレビューを出しません）。
• 決定すると選んだ worktree のパスだけを標準出力へ出します。メッセージ類は標準エラーです。

gz worktree add <name>

• fuzzy finder で選ぶのはチェックアウトするブランチです。候補は 他の worktree で使用中でないブランチに限ります （git は同じブランチを複数の worktree で同時にチェックアウトできないため）。
• -a でリモート追跡ブランチも候補に含めます（gz branch -a とまったく同じ規則）。origin/feature を選ぶと git へは短縮名 （feature）を渡し、git の DWIM が追跡するローカルブランチを作ります。 「使用中」の判定はその短縮名に対して行うため、ローカルの feature が別の worktree でチェックアウト中なら origin/feature も候補から消えます（選んでも必ず失敗するため）。 ローカルブランチとそのリモート側は gz branch -a と同じく両方並びます。
• worktree は必ずリポジトリルートの兄弟に作成します。どのディレクトリで コマンドを叩いても変わりません。リポジトリが product/infrastructure/ に あるとき、gz worktree add sample は product/sample/ を作ります。 worktree の中身は .git のある階層まるごとなので、リポジトリと並べたほうが 素直に読めるためです（内側に作ると、本体からは未追跡の埋め込みリポジトリとして見え、 .gitignore の手当てが必要になります）。
• 叩いた場所とは違うところに作られるため、作成後にそのパスを標準エラーへ表示します。 （標準出力は使いません。git worktree add 自身が HEAD is now at ... をそちらへ書くため、パスだけを取り出せる状態には ならないからです。）
• 引数は名前です。パス区切りを含むもの（../sample / a/b / 絶対パス）と . / .. は、読み替えずに理由を示して拒否します。
• 実行するのは git worktree add -- <解決後のパス> <branch> です。名前の自動提案は行いません。
• - で始まる名前を指定する場合は gz worktree add -- -dashy の ように書きます（clap 側の -- であり、fuzgit は git へ渡す際にも別途 -- で保護します）。

-b <branch> — 選べるブランチが無いとき

ローカルブランチが main 1 本で、それを本体が使用中——という ごく普通の状態では候補がゼロになり、gz worktree add はそこで行き止まりになります。-b はその抜け道で、新しいブランチを 作ってそれを worktree に入れます。

• 作成元は HEAD 固定ではありません。main から 作業ブランチを切るのが典型ですが、本体が別のブランチをチェックアウト中である ことは珍しくなく、HEAD 固定では望まない親から切ってしまいます。 main / master を先頭へ寄せているため、 多くの場合は Enter 1 回で意図した作成元になります。
• 既存のローカルブランチと同名の場合は、finder を開く前に停止します。 -b を外せばそのブランチを worktree に入れられることも案内します。
• upstream は git の既定に委ねます。作成元がリモート追跡ブランチのときだけ 設定され、gz branch create の結果と一致します。
• -b と --no-install は独立です。 依存インストールと .claude/ の複写は -b でも走ります。

依存インストール

worktree ができたあと、fuzgit は lockfile を探して依存をインストールします。 探すのは追跡ファイルです — ファイルシステムを走査せず git ls-files に引かせるため、node_modules/ や target/ を踏むことがなく、深さの制限もありません。

• 対象が複数あるときは選べます。候補行は <パス> <実行されるコマンド> で、プレビューは lockfile そのものです。Tab で複数選択でき、 [<n>/<全体>] を頭に付けて順に実行します。
• コマンドを叩いたディレクトリは選択済みで開くため、 そのまま Enter を押せば、選べるようになる前と同じものが入ります。
• 対象が 1 件のときは finder を開きません — 単一プロジェクトのリポジトリでは従来どおりの挙動です。
• Cargo と Go は候補になりません。依存がグローバルキャッシュに置かれ、 ビルド時に取得されるため、新しい worktree に入れるものがありません。
• --no-install を付けると、finder を含めて一切行いません。

gz worktree remove

• 候補は linked worktree のみで、main worktree は候補に含めません（git が削除を許可しないため）。
• locked な worktree、および --force 無しでの変更済み・未追跡ファイルを含む worktree は、git のエラーをそのまま表示して非ゼロ終了します。
• -f / --force は git worktree remove に --force を（1 回だけ — locked な worktree は引き続き拒否されます）渡し、確認プロンプトに「worktree 内の変更済み・未追跡のファイルも破棄される」旨の警告を追記します。

gz worktree prune

• 先に git worktree prune --dry-run --verbose を実行し、整理される worktree と 理由を確認プロンプトに提示します。承認された場合のみ git worktree prune を 実行します。
• 対象が 1 件も無い場合は「整理する worktree はありません」と表示して終了コード 0 で終わります。

gz pr                            # pick an open pull request and check it out
gz pr --checks                   # also show the review decision and the CI status (slower)
gz pr --action                   # pick a pull request, then pick what to do with it
gz pr --worktree review-142      # check it out into a new worktree next to the repository
gz pr --worktree review-142 --no-install   # …without installing dependencies

• Candidates are the open pull requests of the current repository. A line is #<number> <author> <title>, with a [draft] marker in its own column so the columns stay aligned whether or not a pull request is a draft. The head branch name is deliberately not on the line — it is often long enough to push the title off the screen, and the title is what you scan. It appears at the right edge of the preview’s summary instead.
• On confirmation it runs gh pr checkout <number>. What you end up with is ordinary local git state — a branch, its tracking config, and a checkout.
• --action opens a second menu: check the pull request out, show it (gh pr view), show the diff (gh pr diff), print the number, and print the URL. Only the last two write to stdout, so $(…) stays usable.
• Everything gh prints comes straight from gh. fuzgit never repeats it and never guesses at a cause.

Why the preview never waits

Every other fuzgit command builds its candidate list and previews from local data only, because a preview is regenerated on every cursor move and a network round trip there would block the display (see Network operations). gz pr is the single exception — and it breaks the rule exactly once.

The candidate list is fetched with the pull request body riding along in the same call. By the time the finder opens, every preview is already in memory, so moving the cursor is a local string draw. Measured against a repository with 30 open pull requests, adding the body costs about 0.2 seconds.

--worktree <name> — reviewing without disturbing your tree

• The argument is a name, not a path. The worktree is created next to the repository root, exactly like gz worktree add. Anything containing a path separator is refused.
• Afterwards fuzgit does what gz worktree add does: copies your gitignored .claude/ across (FR-33) and installs dependencies from the lockfile it finds. --no-install skips only the install; the .claude/ copy still happens.
• A name already taken by another worktree stops the command before the finder opens — you are never asked to pick and then told it will not work.

gz pr                            # open な PR を選んで checkout する
gz pr --checks                   # レビュー判定と CI の状況も表示する（遅くなる）
gz pr --action                   # PR を選んだあと、続けて行う操作も選ぶ
gz pr --worktree review-142      # リポジトリの隣に新しい worktree を作って checkout する
gz pr --worktree review-142 --no-install   # …依存インストールは行わない

• 候補は現在のリポジトリの open な PR です。候補行は #<番号> <作者> <タイトル> で、 [draft] の印は独立した列に置くため、draft の有無で桁がずれません。 head ブランチ名は意図的に載せていません — 長くなりがちでタイトルを画面外へ押し出してしまう一方、目で追うのは タイトルだからです。ブランチ名はプレビュー枠の右端に出ます。
• 決定すると gh pr checkout <番号> を実行します。得られるのは ローカルの git 状態（ブランチ・追跡設定・チェックアウト）そのものです。
• --action を付けると 2 つ目のメニューが出ます — checkout する・詳細を表示する（gh pr view）・ 差分を表示する（gh pr diff）・番号を出力する・ URL を出力する。標準出力へ書くのは後ろの 2 つだけなので、 $(…) はそのまま使えます。
• gh の出力はそのまま流します。fuzgit は再掲もしませんし、 原因を推測することもしません。

プレビューが待たされない理由

fuzgit の他のコマンドは、候補一覧もプレビューもローカルの情報だけで作ります。 プレビューはカーソル移動のたびに作り直されるため、そこで ネットワーク往復が起きると描画が止まるからです （ネットワーク操作について参照）。 gz pr はその唯一の例外ですが、破るのは候補生成の 1 回だけです。

候補の取得では、PR の本文を同じ 1 回に相乗りさせています。 finder が開いた時点で全プレビューが手元にあるため、カーソル移動はローカルの 文字列描画で済みます。open な PR が 30 件のリポジトリでの実測で、本文の追加分は 約 0.2 秒です。

--worktree <name> — 手元を汚さずにレビューする

• 引数はパスではなく名前です。作成先は gz worktree add と同じくリポジトリルートの 兄弟に固定で、パス区切りを含むものは拒否します。
• 作成後は gz worktree add と同じことをします — gitignore された .claude/ を複写し（FR-33）、 見つけた lockfile から依存をインストールします。--no-install が 止めるのはインストールだけで、.claude/ の複写は行われます。
• 他の worktree が既に使っている名前は、finder を開く前に停止します。 選ばせたあとで「使えません」と告げることはありません。

• The only commands that use the network are gz fetch, gz pull and gz pr. Every other command works purely from local repository data (pushing is left to plain git push). gz pr is also the only one that runs something other than git — it needs the gh CLI, which is not a required dependency.
• Previews never use the network, and candidate generation does so in exactly one place. A preview is regenerated every time the highlighted entry changes, so a network round trip there (latency, timeouts, authentication prompts) would block the display — that rule has no exceptions. Candidate generation has one: gz pr lists pull requests from GitHub, and it fetches their bodies in the same call so its previews stay a local draw. Accordingly the gz fetch preview is limited to local data (git remote get-url / git for-each-ref refs/remotes/<remote>) and never runs git fetch --dry-run inside a preview; the list of updated refs is printed by git fetch itself when it runs. The gz pull preview (commits not yet integrated) likewise comes from reading locally stored tracking refs and is therefore as of the last fetch.
• The only thing gz pull sends over the network is the git fetch <remote> per remote, run after the targets are fixed. Branches sharing an upstream remote are handled together, so there is one round trip per remote and never one per branch. Updating a branch that is not checked out (git fetch . <tracking ref>:refs/heads/<branch>) fetches from the repository itself and never goes out to the network.
• The ahead/behind in gz status and the right-hand side of gz diff --upstream both come from reading local remote-tracking refs. Run gz fetch first if you want to compare against the latest state.
• Authentication is left to git. git fetch runs with inherited stdio, so credential entry, credential helpers and progress output are all git’s own. fuzgit performs no timeouts, no retries and no direct socket handling whatsoever.
• gz fetch --siblings runs its repositories in parallel; gz pull stays serial. The repositories are independent and the wait is network round trips, so they parallelise. gz pull does not: its per-remote fetch is effectively one call, and integrating branches writes to a single repository where the index and ref locks would collide.
• Without --siblings, neighbouring repositories are not even offered as candidates. So that a mere change of directory cannot fire traffic at many repositories, the scan origin is always derived from the current repository and can never be given as a path.
• Ctrl-C during a run is not handled specially: the SIGINT delivered to the foreground process group terminates fuzgit with it, and targets not yet started never run.

• ネットワークを使うのは gz fetch・ gz pull・gz pr だけです。ほかのコマンドはすべてローカルのリポジトリ情報だけで 動作します（push は素の git push に委ねます）。 gz pr は git 以外の外部コマンドを起動する 唯一のコマンドでもあります — gh CLI を使いますが、 これは必須依存ではありません。
• プレビューはネットワークを使いません。候補生成も 1 か所を除いて 使いません。プレビューは選択項目が変わるたびに生成されるため、 そこでネットワーク往復（遅延・タイムアウト・認証プロンプト）が発生すると描画が ブロックされます — こちらに例外はありません。候補生成には 1 つだけ例外が あり、gz pr は GitHub から PR を一覧します。 ただし本文を同じ 1 回で取り切るため、プレビューは ローカルの描画に閉じます。したがって gz fetch のプレビューは ローカル情報（git remote get-url / git for-each-ref refs/remotes/<remote>）に限定しており、 git fetch --dry-run をプレビュー内で実行することはしません。 更新される参照の一覧は git fetch 自身が実行時に表示します。 gz pull のプレビュー（未取り込みのコミット）も同様に、ローカルに 保存済みの追跡参照を読んだ結果であり、前回の fetch 時点の情報です。
• gz pull が通信するのは、対象を確定したあとに実行する リモートごとの git fetch <remote> だけです。 同じリモートを upstream に持つブランチをまとめて扱うため、通信は 1 リモートにつき 1 回で、ブランチごとには通信しません。チェックアウトしていないブランチの更新 （git fetch . <追跡参照>:refs/heads/<ブランチ>）は取得元が 自分自身のリポジトリであり、ネットワークへは出ません。
• gz status の ahead / behind と gz diff --upstream の比較先は、いずれもローカルのリモート追跡参照を 読んだ結果です。最新の状態と比べたい場合は先に gz fetch を実行してください。
• 認証は git に委ねます。git fetch は継承 stdio で 実行するため、認証情報の入力・credential helper・進捗表示はすべて git のものが そのまま動きます。fuzgit 側でのタイムアウト・リトライ・ ソケットの直接操作は一切行いません。
• gz fetch --siblings は並列、gz pull は直列 です。前者は対象が互いに独立した別リポジトリで、待ちの実体がネットワークの 往復であるため並列化できます。後者はリモートごとの fetch が実質 1 件であり、 ブランチの取り込みは同一リポジトリへの書き込みで index や参照の lock が 競合するため直列のままです。
• --siblings を指定しない限り、隣のリポジトリは候補にすら なりません。ディレクトリを移動しただけで多数のリポジトリへ通信が飛ぶことを 防ぐため、探索の起点は常に現在のリポジトリから導出し、パスでは指定できません。
• 実行中の Ctrl-C は独自に処理せず、前面プロセスグループへ届いた SIGINT で fuzgit ごと終了します（まだ着手していない対象は実行されません）。

• gz fetch --siblings and gz pull can post a desktop notification when they finish, which helps when you have stepped away from a long run. It is off unless you turn it on:

  git config --global fuzgit.notify true

• Nothing is posted for runs shorter than ten seconds — below that you are still looking at the terminal. The threshold is fixed; there is no setting for it.
• The body is the count only (3 succeeded / 1 failed). No repository, branch or path name is included: on macOS the text is handed to osascript, which interprets its argument as AppleScript, so user-derived strings are kept out of it by construction.
• Whether a banner actually appears depends on your environment. macOS uses osascript and needs notifications allowed for your terminal application; Linux uses notify-send, which may not be installed. fuzgit never treats that as a failure — the exit code is unchanged, and the reason is only written to the debug log (FUZGIT_DEBUG=1).
• The tally is always written to stderr whether or not a notification appears, so the notification is a convenience and never the only way you learn the result.

• gz fetch --siblings と gz pull は、完了時に デスクトップ通知を出せます。長い実行の間に席を外しているときに役立ちます。 明示的に有効化しない限り出ません。

  git config --global fuzgit.notify true

• 10 秒未満で終わった実行では通知しません。それより短ければ ユーザーはまだ端末を見ているためです。閾値は固定で、設定項目は設けていません。
• 本文は件数だけです（成功 3 件 / 失敗 1 件）。 リポジトリ名・ブランチ名・パスは含めません。macOS では本文を osascript へ渡しますが、これは引数を AppleScript として解釈するため、 ユーザー由来の文字列を構造的に混ぜないようにしています。
• 実際にバナーが表示されるかは環境によります。macOS は osascript を 使うため端末アプリへの通知許可が必要で、Linux は notify-send を 使うため未導入だと出ません。fuzgit はこれを失敗として扱いません。 終了コードは変わらず、理由はデバッグログ（FUZGIT_DEBUG=1）にだけ出ます。
• 通知が出るかどうかに関わらず集計は必ず標準エラーへ出します。 通知はあくまで補助であり、結果を知る唯一の経路にはなりません。

The fuzzy finder uses skim’s default key bindings as they are.

• Multi-select is available in cherry-pick / restore / add / stash push / commit / revert / status (file selection) / diff (file selection) / branch delete / branch cleanup / fetch --siblings / pull, and in the “inspect the conflicted files and mark them resolved” entry of the recovery menu. Pressing Enter without selecting anything with Tab targets the candidate under the cursor.
• Entries that start out selected: gz commit (staged files), gz branch cleanup (every merged branch), gz fetch --siblings (the current repository) and gz pull (the current branch). All of them can be deselected with Tab.
• The selection is always reordered to follow the candidate list before it is handed to git (the order skim returns is the order you picked, which is not necessarily the list order). Commands where the order matters each get their own direction: gz cherry-pick oldest first, gz revert newest first.
• Aborting with Esc / Ctrl-C performs no git operation at all and exits with code 130.

fuzzy finder は skim の既定キーバインドをそのまま使います。

• 複数選択に対応するのは cherry-pick / restore / add / stash push / commit / revert / status（ファイル選択）/ diff（ファイル選択）/ branch delete / branch cleanup / fetch --siblings / pull、および復帰メニューの 「コンフリクトファイルを確認して解決済みにする」です。Tab で 1 件も 選ばずに Enter を押した場合は、カーソル位置の候補が対象になります。
• 起動時から選択済みになるのは gz commit（ステージ済みのファイル）、 gz branch cleanup（merged なブランチ全件）、 gz fetch --siblings（現在のリポジトリ）、gz pull （現在のブランチ）です。いずれも Tab で外せます。
• 選択結果は常に候補一覧を基準に並べ直してから git へ渡します （skim が返す順序は選んだ順であり、候補の並び順とは限らないため）。 gz cherry-pick は古い順、gz revert は新しい順というように、 順序が意味を持つコマンドはそれぞれの向きへ揃えます。
• Esc / Ctrl-C で中断した場合、git 操作は一切実行せず 終了コード 130 で終了します。

Run outside a git repository, fuzgit prints “Not a git repository. Run this command inside a git repository” and exits non-zero.

git リポジトリ外で実行した場合は「git リポジトリではありません」と表示して非ゼロ終了します。

Features deliberately left unimplemented. All of them can be done with plain git.

意図的に実装していない機能です。いずれも素の git で実行できます。

Setting the environment variable FUZGIT_DEBUG=1 prints every git command fuzgit runs to stderr.

• It is enabled only when the value is exactly 1. Unset, empty, 0, true and anything else are all disabled.
• The destination is always stderr (stdout is kept free for piping hashes, tag names and paths).
• The log lists the argument array as-is. Because it is printed on every preview generation, it can visibly mix with the drawing while the fuzzy finder is on screen.
• Commands that target another directory are printed as [fuzgit] (A|B) (cwd: <directory>) git ....
• (A) marks a call whose output fuzgit parses: it always runs with LC_MESSAGES=C so parsing cannot depend on the environment. (B) marks a call whose output you read (inherited stdio, previews, reports passed through): the resolved display language is propagated as LANGUAGE=<ja|en>. The variables that were set or removed are listed in brackets at the end of the line, so the log answers “which language did this git speak?” directly. See Language.

環境変数 FUZGIT_DEBUG=1 を指定すると、fuzgit が実行した git コマンドを 標準エラーへ出力します。

• 有効になるのは値が厳密に 1 の場合だけです。未設定・空文字・0・true などはすべて無効です。
• 出力先は必ず標準エラーです（標準出力はハッシュ・タグ名・パスのパイプ用途のために空けてあります）。
• ログにはコマンドの引数配列がそのまま並びます。プレビュー生成のたびに出力されるため、fuzzy finder の表示中は画面の描画と混ざって見えることがあります。
• 別ディレクトリを対象に実行するコマンドは [fuzgit] (A|B) (cwd: <ディレクトリ>) git ... の形式で出力します。
• (A) はfuzgit が出力をパースする呼び出しで、実行環境に よってパースが壊れないよう常に LC_MESSAGES=C で実行します。 (B) はユーザーが出力を読む呼び出し（継承 stdio・プレビュー・ そのまま提示する報告）で、解決された表示言語を LANGUAGE=<ja|en> として伝播します。設定・削除した環境変数は 行末の角括弧に併記されるため、「この git は何語で話したのか」がログから直接 分かります。表示言語も参照してください。

Confirm that all of these succeed, in this order, on every change.

以下の順にすべて成功することを、変更のたびに確認してください。

• Interactive paths that take over the terminal (the TUI) are outside the scope of automated tests and are verified manually.
• Automated tests cover pure logic (formatting candidates, assembling git arguments, parsing git status / git stash list / git worktree list) as unit tests, and non-interactive paths (--help, running outside a repository, zero candidates) as integration tests with assert_cmd.
• Paths involving the network (gz fetch / gz pull) are not automated; only their non-interactive paths (no remotes, no upstream, zero candidates and similar errors) are verified. Real-world checks use a local bare repository as the remote and never connect to an external network.

• 端末（TUI）を占有する対話パスは自動テストの対象外とし、手動確認とします。
• 自動テストの対象は、候補の整形・git 引数の組み立て・git status / git stash list / git worktree list のパースなどの純ロジック （単体テスト）と、--help・リポジトリ外実行・候補 0 件などの非対話パス （assert_cmd による統合テスト）です。
• ネットワークを伴う経路（gz fetch / gz pull）は 自動テスト化せず、非対話パス（リモートゼロ・upstream 未設定・ 候補ゼロなどのエラー）のみを検証します。実機確認はローカルの bare リポジトリを remote に設定して行い、外部ネットワークへは接続しません。

• Read with gix, write by shelling out to git. gix does not provide the write operations for switch / cherry-pick / restore / add / stash, so they are delegated to the system git in order to keep behavioural compatibility. The worktree listing is read with git worktree list --porcelain -z rather than gix (gix cannot handle the main worktree or the checked-out branch).
• External commands always run as Command::new("git").args([...]), i.e. with an argument array, never through a shell. Paths that come from the user are passed after -- as the pathspec :(top,literal)<path>, removing any room for them to be interpreted as options or wildcards.
• Previews do not hand skim a shell command string; git is executed from Rust and the result is displayed, which structurally prevents injection through candidate strings.
• Positional arguments that cannot be protected with --, such as branch names and commit hashes (switch / merge / rebase / fixup / revert / diff), are passed to git only after checking that the selection is present in the candidate list. The only values that get through originate from real refs enumerated by gix. gz pull verifies that branch.<name>.remote is a registered remote name before running git fetch (the configuration can hold a URL directly, so without the check it could connect to something that was never enumerated). The refspec gz pull uses for branches that are not checked out carries no forcing +, so git rejects non-fast-forward updates and local commits cannot be lost.
• No network access during candidate generation or previews.
• The only command that touches anything outside the current repository is gz fetch --siblings. The scan origin is always derived from the current repository’s worktree root (no path argument is accepted) and is limited to one level under the parent directory. Sibling repositories are opened with gix::open, not gix::discover (discover walks upwards, so a directory without a .git would grab a repository above the scan range). The selection is checked for an exact match against the candidate list, using normalised absolute paths, before it becomes a target.
• Destructive operations (discarding changes with restore, stash drop, branch delete / cleanup, history rewriting with rebase, the integration performed by pull --rebase / --merge, worktree remove / prune, and aborting a merge / rebase) are confirmed first. merge is confirmed too, showing how many commits will come in and the conflict prediction.
• History rewriting is never run automatically (gz fixup only prints the autosquash steps; it does not rebase).
• Pushing is not provided at all, so neither is force push. Use plain git push.

• 読み取りは gix、書き込みは git へのシェルアウト。 gix は switch / cherry-pick / restore / add / stash の書き込み操作を提供していないため、 挙動互換性を優先してシステムの git に委譲しています。worktree の一覧だけは gix ではなく git worktree list --porcelain -z を読みます（gix は main worktree と チェックアウト中のブランチを扱えないため）。
• 外部コマンドは常に Command::new("git").args([...]) の引数配列渡しで 実行し、シェルを一切経由しません。ユーザー由来のパスは -- の後ろに :(top,literal)<path> のパススペックとして渡し、オプションや ワイルドカードとして解釈される余地を排除しています。
• プレビューは skim にシェルコマンド文字列を渡す方式ではなく、Rust 側で git を実行した 結果を表示する方式を採り、候補文字列由来のインジェクションを構造的に防いでいます。
• ブランチ名・コミットハッシュのように -- で保護できない位置引数 （switch / merge / rebase / fixup / revert / diff）は、 選択結果が候補一覧に含まれることを確かめてから git へ渡します。 渡る値は gix が列挙した実在の参照に由来するものだけです。gz pull は branch.<name>.remote が登録済みのリモート名であることを検証して から git fetch します（設定には URL を直接書けるため、検証しないと 列挙していない対象へ接続することになります）。gz pull が チェックアウトしていないブランチを更新する refspec には、強制更新の + を 付けません（非 fast-forward の更新を git に拒否させ、ローカルのコミットを 失わせないためです）。
• 候補生成・プレビューでネットワークアクセスを行いません。
• 現在のリポジトリ以外に触れるのは gz fetch --siblings だけです。 走査の起点は常に現在のリポジトリのワークツリー root から導出し（パス引数を受け取りません）、 親ディレクトリ直下の 1 階層に限定します。兄弟のリポジトリを開くのは gix::open であり gix::discover ではありません （discover は上位へ遡るため、.git を持たないディレクトリから 走査範囲より上のリポジトリを掴んでしまいます）。選択結果は正規化済みの絶対パスで 候補一覧と完全一致することを確かめてから実行対象にします。
• 破壊的操作（restore による変更破棄、stash drop、 branch delete / cleanup、rebase による履歴改変、 pull --rebase / --merge の取り込み、 worktree remove / prune、 merge / rebase の abort）は実行前に確認を挟みます。merge にも 確認を設け、取り込まれるコミット数とコンフリクト予測を提示します。
• 履歴改変の自動実行は行いません（gz fixup は autosquash の手順を表示するだけで rebase しません）。
• push 自体を提供しないため、force push も提供しません。素の git push を使ってください。

src/
├── main.rs          # entry point (parse the CLI, dispatch, exit code)
├── lib.rs
├── cli.rs           # command definitions via clap derive
├── error.rs         # domain errors via thiserror
├── finder.rs        # skim wrapper (candidates, preview, abort detection)
├── git/
│   ├── repo.rs      # opening the repository with gix
│   ├── read.rs      # reading candidate data via gix / git
│   ├── siblings.rs  # scanning repositories under the parent directory (gz fetch --siblings only)
│   └── exec.rs      # running git (run_git / capture_git) and the debug log
└── commands/        # the use case implementation of each subcommand

src/
├── main.rs          # エントリポイント（CLI パース → dispatch → 終了コード）
├── lib.rs
├── cli.rs           # clap derive によるコマンド定義
├── error.rs         # thiserror によるドメインエラー
├── finder.rs        # skim ラッパー（候補・プレビュー・中断判定）
├── git/
│   ├── repo.rs      # gix によるリポジトリのオープン
│   ├── read.rs      # gix / git による候補データの読み取り
│   ├── siblings.rs  # 親ディレクトリ直下のリポジトリ探索（gz fetch --siblings 専用）
│   └── exec.rs      # git の実行（run_git / capture_git）とデバッグログ
└── commands/        # 各サブコマンドのユースケース実装

MIT License. The full text is in LICENSE.

MIT License. 全文は LICENSE を参照してください。