「あのリポジトリどこだっけ？」を完全卒業。VS Code使いがあえて「ghq×fzf」を手放せない理由

公開: 2026/09/09

開発環境ツール・効率化

開閉

日々のWeb開発において、VS Codeはもはや多くのエンジニアにとって標準といえる開発環境です。私自身、日常のコードリーディングや実装作業の大半をVS Code上で過ごしています。

ここで、ひとつの疑問が浮かぶ方も多いと思います。

「VS CodeのGitHub拡張機能や『最近開いたリポジトリ（Cmd/Ctrl + R）』を使っていれば、リポジトリ移動で困ることなんてなくない？」

結論から言うと、「VS Codeを開いて、その中でコードを書くことだけに集中している時間」であれば、確かにエディタ標準の機能や拡張機能だけで十分事足ります。

しかし、実際の現場で開発を進めていると、エディタのGUIだけではどうしてもカバーしきれない「地味で痛い摩擦」がターミナル側に確実に残ります。

今回は、VS Codeをメインエディタとして使いながらも、なぜターミナル上の ghq と fzf を手放せないのか、その本質的な理由と、エディタとCLIをスムーズに繋いで開発体験を向上させる実践レシピをお話しします。

[!NOTE] 検証環境・動作確認バージョン 本記事で紹介するコマンドや設定は、以下の環境で動作確認を行っています。

macOS 15.0 (Sequoia) / zsh 5.9

Windows 11 Pro (23H2) / PowerShell 7.4.5 / WSL2 (Ubuntu 24.04 LTS)

ghq v1.7.1

fzf v0.60.2

Visual Studio Code v1.93.1

「VS Codeの履歴や拡張機能」だけではカバーしきれない実務の壁

Visual Studio Code には、直近で作業したプロジェクトを素早く開くショートカット（Macなら Cmd + R、Windowsなら Ctrl + R）が備わっています。また、GitHubの拡張機能を使えばリモートリポジトリを直接開くことも可能です。

それでもなお、実務の開発現場で私たちが直面する「3つの壁」があります。

graph TD
    A["VS Code中心の開発日常"] --> B{"直面する3つの壁"}
    B --> C["1. 『最近開いた』履歴から消えたリポジトリの遭難"]
    B --> D["2. ターミナルファーストな作業（Docker / CLI）の存在"]
    B --> E["3. シェル側の長文コマンド履歴（Ctrl + R）はエディタ外"]
    C --> F["ghq × fzf で解決"]
    D --> F
    E --> F

1. 「最近開いた」リストから押し出された瞬間の遭難

VS Codeの「最近開いた項目」に常駐しているのは、せいぜい直近1〜2週間に触ったアクティブな数個のリポジトリだけです。

「3ヶ月前に作ったあの検証スクリプト、どこに置いたっけ……？」
「別チームのマイクロサービスのリポジトリ、ローカルのどこにクローンしたっけ……？」

こうして履歴から押し出されたリポジトリを探す時、結局はOSのファイルツリー（Finderやエクスプローラー）をポチポチ辿るか、ターミナルで cd ../../../ を連打して階層迷子になることになります。

2. ターミナルファーストな作業（Docker / DB / インフラ操作）

Webエンジニアの仕事は、コードをエディタで書くだけでは終わりません。

Dockerコンテナのビルドや再起動
DBのマイグレーション実行（migrate や psql）
TerraformやAWS CLIによるインフラ確認
自作のシェルスクリプトやバッチのローカル実行

こうした作業は、ターミナルで直接叩く方がはるかに早い場面が多々あります。その際、「まずターミナル上でそのリポジトリのルート階層に移動していなければコマンドが叩けない」という物理的な制約が立ちはだかります。

3. VS Codeでは絶対に代行できない「コマンド履歴の検索」

先週叩いた複雑な引数付きのDockerコマンドや、滅多に使わないデータベースのダンプコマンド。
これらはエディタの機能ではなく、シェルの履歴から掘り起こす必要があります。bashやzshの標準 Ctrl + R では1件ずつしか遡れず、探している間に思考が途切れてしまいます。

ディレクトリ配置のルールがない現場で起きる「先祖返り」の罠

かつての私は、この問題に対して「その場の気分で適当に git clone して cd で移動する」という運用で乗り切ろうとしていました。

~/dev/、~/workspace/、ときには検証用の ~/Desktop/tmp/ など、思いつきのディレクトリにクローンを散らかしていた結果、手痛いトラブルを経験したことがあります。

急ぎの不具合修正でプルリクエストを作ろうと、コードを修正してテストを通し、「よし、これでプッシュ！」と意気込んでいたところ、Gitの変更差分が最新ブランチと全く噛み合いませんでした。

原因を調査したところ、数ヶ月前の古い検証で別階層にクローンしていた過去のリポジトリ側で作業してしまっていたのです。

「どこに置いたか分からない」「同じリポジトリが複数存在する」という状態は、単に移動が遅いだけでなく、意図しない古いコードの混入（先祖返り）といったヒューマンエラーの温床になります。

ghq と fzf がもたらす、関心の分離と理想的な役割分担

この問題を根本から解決するのが、ghq と fzf の組み合わせです。

graph TD
    subgraph "ghq（配置のルール化）"
        A["ghq get <URL>"] -->|"自動で階層分類"| B["~/ghq/github.com/org/repo"]
        C["保存先ルールを物理的に強制統一"]
    end

    subgraph "fzf（あいまい即時検索）"
        D["Ctrl + G（リポジトリ検索）"] -->|"2〜3文字入力"| E["一瞬で目的の階層へ cd"]
        F["Ctrl + R（履歴検索）"] -->|"あいまいインクリメンタル"| G["過去の複雑コマンドを一発呼び出し"]
    end

ghq: リポジトリの保存先を ~/ghq/github.com/ユーザー名/リポジトリ名 に強制一本化するツール。「どこにクローンしようか」と悩む余地を物理的になくします。
fzf: ターミナル上で動く超高速な対話型あいまい検索（Fuzzy Finder）。適当なキーワード（site, api, batch 等）を打つだけで候補をリアルタイムに絞り込みます。

実際に ghq get でリポジトリを取得すると、以下のようにURLのホスト名や組織名に基づいたディレクトリツリーが自動的に生成されます。

$ ghq get https://github.com/my-org/frontend-service
     clone https://github.com/my-org/frontend-service -> /Users/username/ghq/github.com/my-org/frontend-service
git clone --recursive https://github.com/my-org/frontend-service /Users/username/ghq/github.com/my-org/frontend-service
Cloning into '/Users/username/ghq/github.com/my-org/frontend-service'...
remote: Enumerating objects: 1240, done.
remote: Counting objects: 100% (312/312), done.
remote: Compressing objects: 100% (180/180), done.
Receiving objects: 100% (1240/1240), 2.15 MiB | 6.42 MiB/s, done.

# ローカルに蓄積されたリポジトリを瞬時に一覧表示
$ ghq list
github.com/junegunn/fzf
github.com/my-org/api-server
github.com/my-org/frontend-service
github.com/x-motemen/ghq

VS Codeと対立しない。「VS Codeを素早く開くランチャー」になる

ここが最大のポイントです。ghqとfzfは、VS Codeと競合するものではありません。むしろVS Codeを素早く立ち上げるための「軽量で無駄のないランチャー」として機能します。

# ターミナルで Ctrl + G を押す
# → 「front」と打って Enter（目的のリポジトリへ即座に移動）
# → そのままVS Codeを起動
code .

たったこれだけで、数ヶ月触っていなくてVS Codeの履歴から消え去っていたリポジトリでも、わずか数秒でVS Codeのエディタ画面へ復帰できます。

5分でできる実践セットアップ

MacでもWindows（WSL2 / PowerShell 7）でも、導入と設定の手順は非常にシンプルです。

1. ツールのインストール

macOS（Homebrew）

brew install ghq fzf

Windows（WSL2 / Ubuntu）

WSL2のUbuntu環境では、fzf はAPTパッケージから、ghq はGitHubのバイナリまたはGo環境から簡単に導入できます。

# fzf のインストール
sudo apt update && sudo apt install -y fzf

# ghq のインストール（Go環境がある場合）
go install github.com/x-motemen/ghq@latest

# または公式バイナリを直接配置する場合
# curl -sL https://github.com/x-motemen/ghq/releases/latest/download/ghq_linux_amd64.zip -o ghq.zip
# unzip ghq.zip && sudo mv ghq_linux_amd64/ghq /usr/local/bin/

Windowsネイティブ（PowerShell 7 + winget）

Windowsネイティブ環境で動かす場合は、winget で両ツールをインストールできます。

winget install -e --id x-motemen.ghq
winget install -e --id junegunn.fzf

2. シェルの設定

macOS / Linux（zsh / bash）

ghq の一覧を fzf に渡し、選択したディレクトリへ移動する関数をシェルに定義します。以下を ~/.zshrc（または ~/.bashrc）に追記してください。

# ==============================================================================
# ghq + fzf によるリポジトリジャンプ（Ctrl + G）
# ==============================================================================
function ghq-fzf-repo() {
  local selected_dir
  # ghq list の結果を fzf に流し込み、選択されたパスを取得
  selected_dir=$(ghq list --full-path | fzf --reverse --height 40% --query "$LBUFFER")

  if [ -n "$selected_dir" ]; then
    BUFFER="cd ${selected_dir}"
    zle accept-line
  fi
  zle reset-prompt
}

# ウィジェットとして登録し、Ctrl + G にキーバインドを割り当て
zle -N ghq-fzf-repo
bindkey '^G' ghq-fzf-repo

# ==============================================================================
# fzf 標準の履歴検索（Ctrl + R）の有効化
# ==============================================================================
# fzf のキーバインドと自動補完を読み込む（brew インストールの場合の標準パス）
if [ -f "$(brew --prefix)/opt/fzf/shell/key-bindings.zsh" ]; then
  source "$(brew --prefix)/opt/fzf/shell/key-bindings.zsh"
  source "$(brew --prefix)/opt/fzf/shell/completion.zsh"
fi

設定を保存したら、source ~/.zshrc で反映させます。

Windows（PowerShell 7）

PowerShell環境でも、PSReadLine を活用することで同様に Ctrl + G によるジャンプが可能です。 PowerShellプロファイル（$PROFILE）に以下を追記してください。

# ==============================================================================
# ghq + fzf によるリポジトリジャンプ（Ctrl + G）for PowerShell 7
# ==============================================================================
function Invoke-GhqFzf {
    $selectedDir = ghq list --full-path | fzf --reverse --height 40%
    if ($selectedDir) {
        Set-Location $selectedDir
        [Microsoft.PowerShell.PSConsoleReadLine]::InvokePrompt()
    }
}

# Ctrl + G にキーハンドラを登録
Set-PSReadLineKeyHandler -Chord 'Ctrl+g' -ScriptBlock {
    Invoke-GhqFzf
}

[!TIP] Windows環境でのポイント Windowsでは ghq.root の保存先が C:\Users\<ユーザー名>\ghq となります。WSL2側とWindows側で別々にリポジトリを持つか、WSL2側を主戦場にするか運用をあらかじめ決めておくと、パーミッションや改行コード（CRLF / LF）に悩まされることがなくなります。

実務で長く使い続けるための設計判断：あえて「プレビュー機能を凝りすぎない」理由

fzf には、右側にファイルのプレビュー（bat や cat で中身を表示する）を出す強力なオプションがあります。

私も一時期、「どうせならリッチにしよう」とリポジトリ移動時に README.md を右側にプレビュー表示させたり、Gitログをグラフィカルに出す設定を盛り込んでいた時期がありました。

しかし、実務で数ヶ月使い続けた結果、行き着いた結論は「リポジトリ移動と履歴検索に、豪華なプレビューは不要だった」ということでした。

プレビューを盛りすぎた際に感じた課題:
1. ノートPCの画面（13〜14インチ）でターミナルを2分割すると、横幅が狭くなりパスの視認性が落ちる
2. プレビュー生成プロセスの呼び出しにより、キー入力に対する追従がわずかに遅延する
3. そもそもリポジトリを移動したい場面で見たいのは「リポジトリ名」だけであり、ドキュメントの中身ではない

開発において最も大切なのは、「思考のスピードを落とさないこと」（低レイテンシ）です。
装飾は最低限にとどめ、純粋にパスだけを高速にフィルタリングするシンプルな設定こそが、何年経っても飽きずに使い続けられる秘訣だと実感しています。