Telescope

As projects grow, the biggest bottleneck often isn't editing code -- it's finding it. Navigating a tree of hundreds or thousands of files by hand is slow and breaks your flow. Fuzzy finding solves this by letting you type a few characters and instantly narrow down files, symbols, grep results, or really anything in your project. It's one of those features that, once you have it, you can't imagine working without.

Telescope.nvim is Neovim's premier fuzzy finder. It replaces FZF.vim with a fully Lua-native, extensible picker system for finding files, searching text, browsing buffers, and much more.

What you'll learn in this chapter:

• Install and configure Telescope with the fzf-native extension for optimal performance

• Use essential pickers to find files, search text, navigate buffers, and browse LSP symbols

• Customize Telescope keybindings and picker behavior to match your workflow

• Extend Telescope with community extensions and integrate it with LSP and Git

• Migrate from FZF.vim to Telescope equivalents

Setup

-- lua/plugins/telescope.lua
return {
    'nvim-telescope/telescope.nvim',
    branch = '0.1.x',
    dependencies = {
        'nvim-lua/plenary.nvim',
        -- Optional but recommended: native FZF sorter for performance
        {
            'nvim-telescope/telescope-fzf-native.nvim',
            build = 'make',
        },
        'nvim-tree/nvim-web-devicons',
    },
    cmd = 'Telescope',
    keys = {
        { '<leader>ff', '<cmd>Telescope find_files<CR>', desc = 'Find files' },
        { '<leader>fg', '<cmd>Telescope live_grep<CR>', desc = 'Live grep' },
        { '<leader>fb', '<cmd>Telescope buffers<CR>', desc = 'Buffers' },
        { '<leader>fh', '<cmd>Telescope help_tags<CR>', desc = 'Help tags' },
        { '<leader>fo', '<cmd>Telescope oldfiles<CR>', desc = 'Recent files' },
        { '<leader>fw', '<cmd>Telescope grep_string<CR>', desc = 'Grep word under cursor' },
        { '<leader>fd', '<cmd>Telescope diagnostics<CR>', desc = 'Diagnostics' },
        { '<leader>fr', '<cmd>Telescope resume<CR>', desc = 'Resume last search' },
        { '<leader>/', '<cmd>Telescope current_buffer_fuzzy_find<CR>', desc = 'Fuzzy find in buffer' },
    },
    config = function()
        local telescope = require('telescope')
        local actions = require('telescope.actions')

        telescope.setup({
            defaults = {
                mappings = {
                    i = {
                        ['<C-j>'] = actions.move_selection_next,
                        ['<C-k>'] = actions.move_selection_previous,
                        ['<C-q>'] = actions.send_to_qflist + actions.open_qflist,
                        ['<Esc>'] = actions.close,
                    },
                },
                file_ignore_patterns = {
                    'node_modules',
                    '.git/',
                    'dist/',
                    'build/',
                },
                layout_config = {
                    horizontal = { preview_width = 0.55 },
                    vertical = { mirror = false },
                    width = 0.87,
                    height = 0.80,
                },
            },
            pickers = {
                find_files = {
                    hidden = true,  -- Show hidden files
                },
                buffers = {
                    sort_mru = true,  -- Most recently used first
                },
            },
        })

        -- Load fzf-native extension for better performance
        pcall(telescope.load_extension, 'fzf')
    end,
}

Essential Pickers

File Finding

Picker	Description	Shortcut
find_files	Find files by name	<leader>ff
oldfiles	Recently opened files	<leader>fo
git_files	Git tracked files	<leader>gf

Tip: find_files uses fd if available, which is much faster than find. Install it: sudo apt install fd-find or brew install fd.

Text Searching

While Vim has powerful built-in search capabilities (see Search, Replace & Regular Expressions), Telescope takes project-wide searching to another level with real-time fuzzy matching.

Picker	Description	Shortcut
live_grep	Search text across files	<leader>fg
grep_string	Search word under cursor	<leader>fw
current_buffer_fuzzy_find	Search in current file	<leader>/

Tip: live_grep uses ripgrep. Install it: sudo apt install ripgrep or brew install ripgrep.

Buffer & Navigation

Picker	Description	Shortcut
buffers	List open buffers	<leader>fb
help_tags	Search Vim help	<leader>fh
resume	Resume last picker	<leader>fr
jumplist	Browse jumplist	—
marks	Browse marks	—
registers	Browse registers	—
keymaps	Browse keymaps	—

LSP Pickers

Telescope integrates tightly with Neovim's built-in LSP client (see LSP -- Language Server Protocol) to provide fuzzy-searchable views of definitions, references, and symbols.

-- Add these keymaps in your LspAttach callback:
vim.keymap.set('n', 'gd', '<cmd>Telescope lsp_definitions<CR>')
vim.keymap.set('n', 'gr', '<cmd>Telescope lsp_references<CR>')
vim.keymap.set('n', 'gi', '<cmd>Telescope lsp_implementations<CR>')
vim.keymap.set('n', '<leader>ds', '<cmd>Telescope lsp_document_symbols<CR>')
vim.keymap.set('n', '<leader>ws', '<cmd>Telescope lsp_workspace_symbols<CR>')

Git Pickers

vim.keymap.set('n', '<leader>gc', '<cmd>Telescope git_commits<CR>')
vim.keymap.set('n', '<leader>gb', '<cmd>Telescope git_branches<CR>')
vim.keymap.set('n', '<leader>gs', '<cmd>Telescope git_status<CR>')

Telescope Keybindings (Inside the Picker)

Insert Mode (while typing)

Key	Action
Ctrl+j/k	Move selection up/down
Ctrl+n/p	Move selection up/down (alternative)
Enter	Open selected file
Ctrl+x	Open in horizontal split
Ctrl+v	Open in vertical split
Ctrl+t	Open in new tab
Ctrl+u/d	Scroll preview up/down
Ctrl+q	Send results to quickfix list
Esc	Close picker

Normal Mode (press Esc first)

Key	Action
j/k	Move selection
gg/G	Go to top/bottom
?	Show keybinding help

Extensions

Telescope is highly extensible. Popular extensions:

Extension	Description
telescope-fzf-native.nvim	FZF algorithm for faster sorting
telescope-file-browser.nvim	File browser picker
telescope-ui-select.nvim	Use Telescope for vim.ui.select

Note: Telescope is installed and managed through a plugin manager like lazy.nvim (see Plugin Management). Make sure your plugin manager is configured before adding Telescope.

Migrating from FZF.vim

If you were using FZF.vim, here's the Telescope equivalent:

FZF.vim	Telescope
:Files	:Telescope find_files
:Rg or :Ag	:Telescope live_grep
:Buffers	:Telescope buffers
:Lines	:Telescope current_buffer_fuzzy_find
:History	:Telescope oldfiles
:Commits	:Telescope git_commits
:BCommits	:Telescope git_bcommits
:GFiles?	:Telescope git_status
:Helptags	:Telescope help_tags
:Maps	:Telescope keymaps

Summary

Telescope is Neovim's most versatile navigation tool, turning file finding, text searching, buffer management, and LSP browsing into a unified fuzzy-finding experience. With its extensible picker system and tight integration with ripgrep, fd, and LSP, Telescope eliminates the friction of navigating large codebases.

Key takeaways:

• Use <leader>ff for file finding and <leader>fg for project-wide text search as your primary navigation tools.

• Telescope pickers work with LSP, Git, and many other Neovim subsystems, making it a central hub for navigation.

• The fzf-native extension significantly improves sorting performance and should always be installed alongside Telescope.

• Sending results to the quickfix list with <C-q> bridges Telescope with Vim's built-in quickfix workflow.

Exercises

1. Find and open a file by partial name -- Use Telescope to find a file in your project by typing only a few characters of its name. Try opening the result in a vertical split.

2. Search for a string across your project -- Use live_grep to search for a function name across all files, then send all matches to the quickfix list.

3. Browse and switch buffers -- Open several files, then use the Telescope buffer picker to switch between them. Notice how the most recently used buffer appears first.

4. Search for a word under the cursor -- Place your cursor on a variable or function name and use grep_string to find all occurrences across the project.

5. Customize Telescope layout -- Modify your Telescope configuration to use a vertical layout with the preview at the top and adjust the width and height.