症状

telescope.nvimで :Telescope find_files を実行してもファイルが表示されない、または特定のファイルが検索結果に出てこない。

結論：まずこれを確認

  1. rg（ripgrep）または fd がインストールされているか確認
  2. .gitignore や telescope の file_ignore_patterns で除外されていないか確認
  3. :checkhealth telescope でエラーがないか確認

操作フロー

    flowchart TD
    A[ファイルが見つからない] --> B{:checkhealth telescope}
    B -->|エラーあり| C[依存ツールを確認]
    B -->|エラーなし| D{hidden files?}
    C --> E[rg/fd をインストール]
    D -->|隠しファイル| F[hidden=true を設定]
    D -->|通常ファイル| G{.gitignore確認}
    G -->|除外されている| H[no_ignore設定]
    G -->|除外されていない| I[file_ignore_patterns確認]
    E --> J[再度検索]
    F --> J
    H --> J
    I --> J

よくある原因

  • ripgrep/fd 未インストール - telescope の find_files は外部ツールに依存する
  • .gitignore による除外 - Git管理下のファイルはデフォルトで .gitignore を尊重する
  • file_ignore_patterns 設定 - telescope 設定で特定パターンを除外している
  • 隠しファイル（dotfiles） - デフォルトでは . で始まるファイルは非表示
  • cwd の指定ミス - 検索対象ディレクトリが意図と異なる
  • プラグイン未読み込み - lazy loading で telescope が読み込まれていない
  • キャッシュの問題 - 古いキャッシュが残っている

操作手順

ステップ1: 依存ツールの確認

    # ripgrep の確認
which rg
rg --version

# fd の確認
which fd
fd --version

🔍 チェックポイント: バージョン番号が表示されればインストール済み

インストールされていない場合：

    # Ubuntu/Debian
sudo apt install ripgrep fd-find

# macOS
brew install ripgrep fd

# Arch Linux
sudo pacman -S ripgrep fd

ステップ2: checkhealth の実行

Neovim で以下を実行：

    :checkhealth telescope

🔍 チェックポイント: OK 表示のみであれば依存関係は正常

ステップ3: 基本動作の確認

    " カレントディレクトリを確認
:pwd

" telescope でファイル検索
:Telescope find_files

🔍 チェックポイント: カレントディレクトリが検索したい場所と一致しているか

ステップ4: 隠しファイルの検索設定

~/.config/nvim/init.lua に以下を追加：

    require('telescope').setup {
  defaults = {
    -- 隠しファイルを表示
    hidden = true,
  },
  pickers = {
    find_files = {
      hidden = true,
    },
  },
}

または一時的に隠しファイルを含めて検索：

    :Telescope find_files hidden=true

🔍 チェックポイント: .env や .gitignore などが表示されるか

ステップ5: .gitignore の除外を無効化

.gitignore で除外されたファイルも検索対象にする場合：

~/.config/nvim/init.lua:

    require('telescope').setup {
  pickers = {
    find_files = {
      no_ignore = true,        -- .gitignore を無視
      no_ignore_parent = true, -- 親ディレクトリの .gitignore も無視
    },
  },
}

一時的に実行：

    :Telescope find_files no_ignore=true

🔍 チェックポイント: node_modules 内のファイルなども表示されるか

ステップ6: file_ignore_patterns の確認

現在の設定を確認：

    :lua print(vim.inspect(require('telescope.config').values.file_ignore_patterns))

除外パターンをカスタマイズ：

    require('telescope').setup {
  defaults = {
    file_ignore_patterns = {
      "node_modules",
      ".git/",
      "%.lock",
    },
  },
}

🔍 チェックポイント: 探しているファイルがパターンに該当していないか

ステップ7: find_command のカスタマイズ

特定のツールを明示的に指定：

    require('telescope').setup {
  pickers = {
    find_files = {
      find_command = { "rg", "--files", "--hidden", "--glob", "!.git/*" },
    },
  },
}

fd を使用する場合：

    require('telescope').setup {
  pickers = {
    find_files = {
      find_command = { "fd", "--type", "f", "--hidden", "--exclude", ".git" },
    },
  },
}

🔍 チェックポイント: コマンドを直接ターミナルで実行して結果を確認

    rg --files --hidden | head -20

NG行動（やってはいけないこと）

  • find_command に存在しないコマンドを指定 - エラーが出ずに空の結果になる
  • no_ignore=true を常時有効にする - 大量のファイルで検索が遅くなる
  • 設定変更後に Neovim を再起動しない - Lua 設定は再読み込みが必要
  • file_ignore_patterns で . を指定 - すべてのファイルが除外される

よくある質問（FAQ）

Q1: live_grep でもファイルが見つからない場合は？

A: live_grep は ripgrep 必須。:Telescope live_grep 実行前に rg がインストールされているか確認する。設定は vimgrep_arguments で変更可能：

    defaults = {
  vimgrep_arguments = {
    "rg",
    "--hidden",
    "--color=never",
    "--no-heading",
    "--with-filename",
    "--line-number",
    "--column",
    "--smart-case",
  },
}

Q2: 特定のディレクトリだけ検索したい場合は？

A: cwd オプションを指定：

    :Telescope find_files cwd=~/projects/myapp

Lua から呼び出す場合：

    require('telescope.builtin').find_files({ cwd = "~/projects/myapp" })

Q3: Windows で動作しない場合は？

A: パス区切りの問題が多い。find_command を明示的に指定し、パスは / を使用：

    find_command = { "rg", "--files", "--path-separator", "/" }

関連するトラブル

準備中

解決しない場合

  • telescope.nvim 公式リポジトリ: https://github.com/nvim-telescope/telescope.nvim
  • :help telescope.setup() でオプション一覧を確認
  • :Telescope で利用可能な picker 一覧を確認
  • 次に調べるキーワード: telescope plenary, telescope extensions, telescope fzf-native