Zsh：補完、プレビュー、起動トラブルシューティング
このページの目次
Tab 補完では、補完関数が候補を生成し、fzf-tab が表示し、プレビューが選択内容を説明する。候補がない、一覧が開かない、プレビューだけ空という問題を分けて調べる。
対話的設定は .zshrc を中心に扱う。ログイン時は .zprofile なども関わり、.zshenv は非対話実行にも影響するため、端末専用の出力やプラグインを置かない。
標準補完を先に確認する
追加補完ディレクトリを fpath に入れてから初期化する。
新しい Zsh で cd <Tab>、Git リポジトリ内で git switch <Tab> を試す。権限警告は compaudit で場所を特定して修正し、検査の恒久的な無効化で隠さない。
通常のユーザー起動設定を除外して試すには：
そのシェルで手動初期化し、動くなら日常の設定とプラグインへ範囲を絞る。exit で元へ戻る。
fzf-tab は候補を選ぶ
fzf とプラグインを導入し、compinit の後に読み込む。パスは実際の導入先へ置き換える。
一覧の表示は既存の補完結果を利用する。分岐候補の生成が間違っている場合、色や表示サイズを変えても直らない。fzf-tab
読み込みは fpath/補完定義、compinit、fzf-tab、履歴候補などの編集プラグイン、構文強調の順を基準にし、使用バージョンの約束を確認する。
一つのプレビューから始める
realpath はファイルやディレクトリの補完文脈で使う。引用符は空白を保ち、-- は先頭のハイフンを引数として扱わせる。全コマンドでこの変数が存在するとは限らない。
動作確認後に Git 分岐を追加する。
word は選択候補である。プレビューは選択の補助であり、実行は Enter 後のコマンドが行う。右側だけ空なら、実在するパスや分岐を使ってプレビューコマンドを単独実行する。
carapace の担当範囲
carapace の初期化は既存の補完定義を上書きする場合がある。コマンドごとに担当を決め、git switch などの文脈依存プレビューを再確認する。
旧設定の compdef 行を除く方法は生成スクリプトの形式に依存し、_carapace と _carapace_completer の適合関数も必要だった。フィルタだけのコピーは不完全である。新規環境では公式設定を基準にする。
履歴候補、プロンプト、別名
autosuggestions は履歴、構文強調は入力中の行、Starship はプロジェクト状態を扱う。どれも補完そのものの代わりではない。
これらは対話操作の別名である。スクリプトは明示的なプログラムと引数を使い、プレビューの依存ツールも確認する。CLI ツール
起動や補完が失敗したら
これは構文検査で、プラグインの存在や初期化動作までは確認しない。標準補完、fzf-tab、一つのプレビュー、他のプラグインの順に戻す。一覧が急に空なら、未対応 fzf 引数や Tab の再割り当てを調べる。
起動が遅い場合は .zshrc の先頭付近に zmodload zsh/zprof、末尾に zprof を一時追加して関数別の時間を見る。確認後は外す。ネットワーク処理や重複初期化など、具体的な待ち時間を探す。
空白入りパス、分岐、候補なし、履歴候補を確認してから見た目を調整する。