【Neovim】 telescope.nvimのインストール方法と使い方

本記事では、Neovimのファジーファインダー・プラグインである Telescope のインストール方法と使い方を紹介します。

ファジーファインダーとは、日本語にすると「あいまい検索」のことです。難しい正規表現を使わなくても、検索文字列に似たものから候補リストを表示してくれます。

Telescopeを使うと、以下のような強力な検索機能をNeovim内で利用できます。

ターミナルコマンドの find のようなファイル名検索
grep のようなファイル内の文字列検索
検索結果に表示されたファイルをそのままNeovim内で開く機能

また、LSP（Language Server Protocol）やGitとも連携でき、変数やメソッドの定義箇所へ移動したり、Gitブランチ内のコミット一覧を検索したりすることも可能です。

インストール方法

Telescope本体をインストールする前に、事前準備としてTelescopeの依存関係（dependency）である ripgrep と fd をインストールします。

ripgrepのインストール

ripgrep は grep を高速化・強化したコマンドで、Telescopeの live_grep コマンドを使うために必要です。 Ubuntuでは以下のようにインストールします。

# Ubuntu及びDebian系
sudo apt install ripgrep

fdのインストール

fd は find コマンドをより使いやすく改良したコマンドで、Telescopeの find_files で使われます。

Ubuntuおよび他のDebianベースのLinuxディストリビューションでは fd-find というパッケージ名で提供されています（fd というコマンド名が別のパッケージですでに存在するため）。

# Ubuntu及びDebian系
sudo apt install fd-find

このままでもTelescopeで使えますが、CLI（ターミナル）でも通常の find の代わりに使いたい場合は、シンボリックリンクを作成しておくと fd という本来のコマンド名で使えます。

# ~/.local/bin ディレクトリを作成（存在しない場合）
mkdir -p ~/.local/bin
# シンボリックリンクを作成
ln -s $(which fdfind) ~/.local/bin/fd

注）~/.local/bin にパスが通っている必要があります。

Telescopeのインストール

本記事では例としてNeovimプラグインマネージャーの Packer を使ってインストールします。（※現在、Packerはメンテナンスが停止しており、新規導入には lazy.nvim が推奨されていますが、既存の設定への追加例としてPackerで解説します）

Packerのプラグインファイル（例: ~/.config/nvim/lua/user/plugins.lua）をNeovimで開き、以下のように記述します。

-- ~/.config/nvim/lua/user/plugins.lua
return require('packer').startup(function(use)
  -- Treesitter（シンタックスハイライト等のために推奨）  　　
  use "nvim-treesitter/nvim-treesitter"

  -- Telescope
  use {
    'nvim-telescope/telescope.nvim',
    branch = '0.1.x',
    requires = { {'nvim-lua/plenary.nvim'} }
  }
end)

Treesitter: パーサー機能を提供するプラグインです。Telescopeのプレビュー画面で見やすく色付けするために一緒にインストールすることをお勧めします。
branch: バージョンを 0.1.x とすることで、安定版ブランチの最新パッチが同期されるようになります。
requires: Telescopeは plenary.nvim に依存しますが、上記のように記述しておくと自動でインストールしてくれます。

ファイルを保存したら、Neovimで以下のコマンドを入力し、インストールを実行します。

:PackerSync

インストール後、以下のコマンドを実行して「Health Check」を行い、依存関係（ripgrepとfd）が正しく認識されているか確認しましょう。

:checkhealth telescope

Telescopeの使い方と代表的なコマンド

Telescopeのコマンドは、Neovimのコマンドラインモードで :Telescope command_name と入力して実行します。実行するとウィンドウが開き、検索結果を表示してくれます。

起動直後: 「挿入モード」になっており、すぐに検索文字列を入力できます。
移動:
- ノーマルモード: Esc キーを押すと移行し、j / k キーでリストを移動できます。i キーを押すと挿入モードに戻ります。
- 挿入モード: そのまま Ctrl+n（下）や Ctrl+p（上）で移動できます。
閉じる: ノーマルモードで Esc キーを押します（挿入モードからは Esc を2回）。
ヘルプ: キーマップ一覧は、挿入モードなら <Ctrl-/>、ノーマルモードなら ? で確認できます。

挿入モードのキーマップ一覧

ノーマルモードのキーマップ一覧

それでは、代表的なコマンドを見ていきましょう。

Builtinコマンド検索

引数なしで実行すると、Telescopeに組み込まれているコマンド一覧を検索・実行できます。

:Telescope

ファイル名検索 (`find_files`)

現在のディレクトリ以下のファイル名をインタラクティブに検索します。

:Telescope find_files

例：Neovim設定ディレクトリ以下で lua という文字列にファイル名がマッチする一覧を表示。

上記のように、ファイルの中身もプレビュー表示されるので、目的のファイルかどうかがひと目でわかります。

ファイル内の文字列検索 (`live_grep`)

ファイルの中身（コンテンツ）を対象に検索し、該当するファイル一覧を表示します。

:Telescope live_grep

例：Neovim設定ディレクトリ以下で、lsp という文字列をコンテンツに含むファイル一覧を表示。

プレビュー画面では、該当する行をハイライトしてくれます。通常の :grep コマンドとは異なり、一文字入力するごとにリアルタイムで結果が絞り込まれ、プレビューも表示されるため非常に便利です。

バッファ検索 (`buffers`)

現在開いている「バッファ」の中からファイル名で検索します（※バッファ内の文字列検索ではありません）。

:Telescope buffers

例：バッファで開いているファイルで、luaという文字列に該当するファイル名の一覧

大量のファイルをバッファで開いている際、:ls で番号を調べて :b <番号> で開くよりも遥かに高速に切り替えられます。

LSP定義検索 (`lsp_definitions`)

Neovimで設定したLSPサーバーと連携し、カーソル下のクラス名、メソッド名、変数名が定義されている場所へ移動します。

:Telescope lsp_definitions

候補が複数の場合のみTelescopeのウィンドウが開き、選択できます。LSPの標準機能（gd など）と同様ですが、候補一覧が見やすいのが特徴です。

例：RubyのLSPを使い、Railsという名前空間が定義されているファイル候補を表示

LSPリファレンス検索 (`lsp_references`)

カーソル下のキーワードが参照されている箇所（使われている場所）を検索します。

:Telescope lsp_references

例：RubyのLSPと連携し、Rails という定数を参照しているファイルと該当行をリスト表示。

Telescope上でさらに文字を入力し、ファイル名などで絞り込むことも可能です。

例：iniという文字列を含むファイル名で絞り込み

Gitブランチ検索 (`git_branches`)

Gitのブランチ名を検索し、候補ブランチのコミットログ等をプレビューできます。

:Telescope git_branches

例：Telescopeレポジトリーのブランチ検索

選択したブランチで Enter キーを押すと、実際にそのブランチへチェックアウト（切り替え）します。

キーマップ設定

毎回 :Telescope ... と入力するのは手間なので、よく使うコマンドにはキーマップ（ショートカット）を設定しましょう。

以下は、推奨される vim.keymap.set を使用した設定例です（~/.config/nvim/lua/user/keymaps.lua 等に記述）。

設定したいショートカット例:

<Space>ff: ファイル名検索 (find_files)
<Space>fg: 文字列検索 (live_grep)
<Space>fb: バッファ検索 (buffers)
<Space>fd: 定義ジャンプ (lsp_definitions)
<Space>fr: 参照検索 (lsp_references)
<Space>fgb: Gitブランチ (git_branches)

-- キーマップ設定
local keymap = vim.api.nvim_set_keymap
local opts = { noremap = true, silent = true }

-- SpaceキーをLeaderキーに設定
vim.g.mapleader = " "

-- Telescope用のキーマップ
-- ファイル名検索
keymap(
  'n',
  '<leader>ff',
  "<cmd>Telescope find_files<cr>",
  opts)

-- 文字列検索 (grep)
keymap(
  'n',
  '<leader>fg',
  "<cmd>Telescope live_grep<cr>",
  opts)

-- バッファ検索
keymap(
  'n',
  '<leader>fb',
  "<cmd>Telescope buffers<cr>",
  opts)

-- LSP 定義ジャンプ
keymap(
  'n',
  '<leader>fd',
  "<cmd>Telescope lsp_definitions<cr>",
  opts)

-- LSP 参照検索
keymap(
  'n',
  '<leader>fr',
  "<cmd>Telescope lsp_references<cr>",
  opts)

-- Gitブランチ検索
keymap(
  'n',
  '<leader>fgb',
  "<cmd>Telescope git_branches<cr>",
  opts)

'n' はノーマルモードを指します。
<leader> は、vim.g.mapleader で設定したキー（ここではスペース）を表します。

まとめ

Telescopeを使いこなせるようになると、ファイル移動やコード調査のスピードが劇的に向上します。ぜひ導入して、快適なNeovimライフを送ってください！

また、Telescopeだけでなく、Vim/Neovimの編集スピードを全般的に向上させたい場合は、「実践Vim 思考のスピードで編集しよう！」がおすすめです。

リンク

【Neovim】 telescope.nvimのインストール方法と使い方

目次

インストール方法

ripgrepのインストール

fdのインストール

Telescopeのインストール

Telescopeの使い方と代表的なコマンド

Builtinコマンド検索

ファイル名検索 (`find_files`)

ファイル内の文字列検索 (`live_grep`)

バッファ検索 (`buffers`)

LSP定義検索 (`lsp_definitions`)

LSPリファレンス検索 (`lsp_references`)

Gitブランチ検索 (`git_branches`)

キーマップ設定

まとめ

Dopesplayモバイルモニター10.5インチのレビュー

【Ruby】Middlemanのバージョンを3から4に更新する方法

Rails組み込み認証とDeviseの比較

Nginx 499ステータスコードの原因、再現方法と対策

Bashのcommコマンドの使い方

Gitマージのキャンセルと再マージの方法

【Neovim】 telescope.nvimのインストール方法と使い方

目次

インストール方法

ripgrepのインストール

fdのインストール

Telescopeのインストール

Telescopeの使い方と代表的なコマンド

Builtinコマンド検索

ファイル名検索 (find_files)

ファイル内の文字列検索 (live_grep)

バッファ検索 (buffers)

LSP定義検索 (lsp_definitions)

LSPリファレンス検索 (lsp_references)

Gitブランチ検索 (git_branches)

キーマップ設定

まとめ

関連記事:

Dopesplayモバイルモニター10.5インチのレビュー

【Ruby】Middlemanのバージョンを3から4に更新する方法

Rails組み込み認証とDeviseの比較

Nginx 499ステータスコードの原因、再現方法と対策

Bashのcommコマンドの使い方

Gitマージのキャンセルと再マージの方法

ファイル名検索 (`find_files`)

ファイル内の文字列検索 (`live_grep`)

バッファ検索 (`buffers`)

LSP定義検索 (`lsp_definitions`)

LSPリファレンス検索 (`lsp_references`)

Gitブランチ検索 (`git_branches`)