Skip to main content

Telescope — Fuzzy Finder

Telescope is the most powerful file/content finder for Neovim. It provides a unified fuzzy-find interface for files, buffers, grep, git, LSP symbols, diagnostics, and more — all in a floating window.

Core Idea

Telescope replaces the file manager mental model. Instead of navigating a tree, you search: type a few characters and Telescope finds what you need instantly.

Installation​

lua/plugins/telescope.lua
return {
  {
    "nvim-telescope/telescope.nvim",
    cmd = "Telescope",
    version = false,
    dependencies = {
      "nvim-lua/plenary.nvim",
      -- FZF native extension (much faster)
      {
        "nvim-telescope/telescope-fzf-native.nvim",
        build = "make",
        cond = function()
          return vim.fn.executable("make") == 1
        end,
      },
      -- UI select integration
      "nvim-telescope/telescope-ui-select.nvim",
    },
    config = function()
      local telescope = require("telescope")
      local actions = require("telescope.actions")

      telescope.setup({
        defaults = {
          prompt_prefix = " ",
          selection_caret = " ",
          path_display = { "smart" },

          mappings = {
            i = {
              ["<C-n>"] = actions.cycle_history_next,
              ["<C-p>"] = actions.cycle_history_prev,
              ["<C-j>"] = actions.move_selection_next,
              ["<C-k>"] = actions.move_selection_previous,
              ["<C-c>"] = actions.close,
              ["<C-u>"] = false,   -- clear prompt
              ["<C-d>"] = actions.delete_buffer,
              ["<C-x>"] = actions.select_horizontal,
              ["<C-v>"] = actions.select_vertical,
              ["<CR>"]  = actions.select_default,
            },
            n = {
              ["<esc>"] = actions.close,
              ["j"]     = actions.move_selection_next,
              ["k"]     = actions.move_selection_previous,
              ["q"]     = actions.close,
            },
          },

          file_ignore_patterns = {
            "node_modules", ".git/", "%.lock",
            "dist/", "build/", ".cache/",
          },

          layout_config = {
            horizontal = {
              preview_width = 0.55,
              results_width = 0.8,
            },
            width = 0.87,
            height = 0.80,
          },
        },

        pickers = {
          find_files = {
            hidden = true,   -- include dotfiles
          },
          live_grep = {
            additional_args = { "--hidden" },
          },
          buffers = {
            sort_mru = true,
            mappings = {
              i = { ["<C-d>"] = actions.delete_buffer },
            },
          },
        },

        extensions = {
          fzf = {
            fuzzy = true,
            override_generic_sorter = true,
            override_file_sorter = true,
            case_mode = "smart_case",
          },
          ["ui-select"] = {
            require("telescope.themes").get_dropdown(),
          },
        },
      })

      -- Load extensions
      telescope.load_extension("fzf")
      telescope.load_extension("ui-select")
    end,
  },
}

Key Bindings​

lua/config/keymaps.lua
local builtin = require("telescope.builtin")
local map = vim.keymap.set

-- Files
map("n", "<leader>ff", builtin.find_files, { desc = "Find files" })
map("n", "<leader>fg", builtin.live_grep, { desc = "Grep in project" })
map("n", "<leader>fw", builtin.grep_string, { desc = "Find word under cursor" })
map("n", "<leader>fr", builtin.oldfiles, { desc = "Recent files" })

-- Neovim internals
map("n", "<leader>fb", builtin.buffers, { desc = "Find buffers" })
map("n", "<leader>fh", builtin.help_tags, { desc = "Help tags" })
map("n", "<leader>fk", builtin.keymaps, { desc = "Key maps" })
map("n", "<leader>fc", builtin.commands, { desc = "Commands" })

-- LSP
map("n", "<leader>fs", builtin.lsp_document_symbols, { desc = "Document symbols" })
map("n", "<leader>fS", builtin.lsp_workspace_symbols, { desc = "Workspace symbols" })
map("n", "<leader>fd", builtin.diagnostics, { desc = "Diagnostics" })

-- Git
map("n", "<leader>gc", builtin.git_commits, { desc = "Git commits" })
map("n", "<leader>gb", builtin.git_branches, { desc = "Git branches" })
map("n", "<leader>gs", builtin.git_status, { desc = "Git status" })

-- Misc
map("n", "<leader>ft", "<cmd>TodoTelescope<cr>", { desc = "Find TODOs" })
map("n", "<leader>f.", builtin.resume, { desc = "Resume last search" })

Inside Telescope​

Key (Insert)Action
<C-j> / <C-k>Navigate results
<CR>Open selected
<C-x>Open in horizontal split
<C-v>Open in vertical split
<C-t>Open in new tab
<C-u>Clear query
<Esc>Close
Key (Normal)Action
j / kNavigate
<CR>Open
qClose

Telescope Pickers Reference​

:Telescope find_files          " fuzzy file finder
:Telescope live_grep           " grep across project
:Telescope buffers             " open buffers
:Telescope oldfiles            " recently opened files
:Telescope help_tags           " Neovim help
:Telescope keymaps             " view all keymaps
:Telescope git_commits         " git log
:Telescope git_branches        " git branches
:Telescope lsp_references      " LSP references
:Telescope lsp_definitions     " LSP definitions
:Telescope diagnostics         " all diagnostics
:Telescope colorscheme         " preview colorschemes
:Telescope marks               " vim marks
:Telescope registers           " vim registers
:Telescope quickfix            " quickfix list

Tips for Performance​

  • Install fzf-native for 10x faster filtering
  • Install ripgrep (rg) for faster live_grep
  • Install fd for faster file finding
# Install performance tools
sudo apt install -y ripgrep fd-find
ln -s $(which fdfind) ~/.local/bin/fd   # Debian/Ubuntu alias

What's Next​