telescope.nvim

Gaze deeply into unknown regions using the power of the moon.

What Is Telescope?

telescope.nvim is a highly extendable fuzzy finder over lists. Built on the latest awesome features from neovim core. Telescope is centered around modularity, allowing for easy customization.

Community driven builtin pickers, sorters and previewers.

_{For more showcases of Telescope, please visit the Showcase section in the Telescope Wiki}

Telescope Table of Contents

• Getting Started
• Usage
• Customization
• Default Mappings
• Pickers
• Previewers
• Sorters
• Layout
• Themes
• Commands
• Autocmds
• Extensions
• API
• Media
• Contributing
• Changelog

Getting Started

This section should guide you to run your first builtin pickers.

Neovim (>v0.10.4) or the latest neovim nightly commit is required for telescope.nvim to work. The neovim version also needs to be compiled with LuaJIT; PUC Lua is not fully supported, both for performance reasons and because extensions may rely on FFI.

Required dependencies

• nvim-lua/plenary.nvim is required.

Suggested dependencies

• BurntSushi/ripgrep is required for live_grep and grep_string and is the first priority for find_files.

We also strongly suggest installing a native telescope sorter to significantly improve sorting performance:

• telescope-fzf-native.nvim or
• telescope-fzy-native.nvim. For more information and a performance benchmark take a look at the Extensions wiki.

Optional dependencies

• sharkdp/fd (finder)
• devicons (icons)

Installation

We recommend pinning to the latest release tag, e.g. using lazy.nvim

{
    'nvim-telescope/telescope.nvim', version = '*',
    dependencies = {
        'nvim-lua/plenary.nvim',
        -- optional but recommended
        { 'nvim-telescope/telescope-fzf-native.nvim', build = 'make' },
    }
}

Checkhealth

Make sure you call :checkhealth telescope after installing telescope to ensure everything is set up correctly.

After this setup you can continue reading here or switch to :help telescope to get an understanding of how to use Telescope and how to configure it.

Usage

Try the command :Telescope find_files to see if telescope.nvim is installed correctly.

local builtin = require('telescope.builtin')
vim.keymap.set('n', '<leader>ff', builtin.find_files, { desc = 'Telescope find files' })
vim.keymap.set('n', '<leader>fg', builtin.live_grep, { desc = 'Telescope live grep' })
vim.keymap.set('n', '<leader>fb', builtin.buffers, { desc = 'Telescope buffers' })
vim.keymap.set('n', '<leader>fh', builtin.help_tags, { desc = 'Telescope help tags' })

See builtin pickers for a list of all builtin functions.

Customization

This section should help you explore available options to configure and customize your telescope.nvim.

Unlike most vim plugins, telescope.nvim can be customized by either applying customizations globally, or individually per picker.

• Global Customization affecting all pickers can be done through the main setup() method (see defaults below)
• Individual Customization affecting a single picker by passing opts to builtin pickers (e.g. builtin.find_files(opts)) see Configuration recipes wiki page for ideas.

Telescope setup structure

require('telescope').setup{
  defaults = {
    -- Default configuration for telescope goes here:
    -- config_key = value,
    mappings = {
      i = {
        -- map actions.which_key to <C-h> (default: <C-/>)
        -- actions.which_key shows the mappings for your picker,
        -- e.g. git_{create, delete, ...}_branch for the git_branches picker
        ["<C-h>"] = "which_key"
      }
    }
  },
  pickers = {
    -- Default configuration for builtin pickers goes here:
    -- picker_name = {
    --   picker_config_key = value,
    --   ...
    -- }
    -- Now the picker_config_key will be applied every time you call this
    -- builtin picker
  },
  extensions = {
    -- Your extension configuration goes here:
    -- extension_name = {
    --   extension_config_key = value,
    -- }
    -- please take a look at the readme of the extension you want to configure
  }
}

To look at what default configuration options exist please read: :help telescope.setup(). For picker specific opts please read: :help telescope.builtin.

To embed the above code snippet in a .vim file (for example in after/plugin/telescope.nvim.vim), wrap it in lua << EOF code-snippet EOF:

lua << EOF
require('telescope').setup{
  -- ...
}
EOF

Default Mappings

Mappings are fully customizable. Many familiar mapping patterns are set up as defaults.

| Mappings | Action | | -------------- | --------------------------------------------------------- | | <C-n>/<Down> | Next item | | <C-p>/<Up> | Previous item | | j/k | Next/previous (in normal mode) | | H/M/L | Select High/Middle/Low (in normal mode) | | gg/G | Select the first/last item (in normal mode) | | <CR> | Confirm selection | | <C-x> | Go to file selection as a split | | <C-v> | Go to file selection as a vsplit | | <C-t> | Go to a file in a new tab | | <C-u> | Scroll up in preview window | | <C-d> | Scroll down in preview window | | <C-f> | Scroll left in preview window | | <C-k> | Scroll right in preview window | | <M-f> | Scroll left in results window | | <M-k> | Scroll right in results window | | <C-/> | Show mappings for picker actions (insert mode) | | ? | Show mappings for picker actions (normal mode) | | <C-c> | Close telescope (insert mode) | | <Esc> | Close telescope (in normal mode) | | <Tab> | Toggle selection and move to next selection | | <S-Tab> | Toggle selection and move to prev selection | | <C-q> | Send all items not filtered to quickfixlist (qflist) | | <M-q> | Send all selected items to qflist | | <C-r><C-w> | Insert cword in original window into prompt (insert mode) | | <C-r><C-a> | Insert cWORD in original window into prompt (insert mode) | | <C-r><C-f> | Insert cfile in original window into prompt (insert mode) | | <C-r><C-l> | Insert cline in original window into prompt (insert mode) |

To see the full list of mappings, check out lua/telescope/mappings.lua and the default_mappings table.

Tip: you can use <C-/> and ? in insert and normal mode, respectively, to show the actions mapped to your picker.

Much like builtin pickers, there are a number of actions you can pick from to remap your telescope buffer mappings, or create a new custom action:

-- Built-in actions
local transform_mod = require('telescope.actions.mt').transform_mod

-- or create your custom action
local my_cool_custom_action = transform_mod({
  x = function(prompt_bufnr)
    print("This function ran after another action. Prompt_bufnr: " .. prompt_bufnr)
    -- Enter your function logic here. You can take inspiration from lua/telescope/actions.lua
  end,
})

To remap telescope mappings, please read :help telescope.defaults.mappings. To do picker specific mappings, its suggested to do this with the pickers table in telescope.setup. Each picker accepts a mappings table like its explained in :help telescope.defaults.mappings.

Pickers

Built-in functions. Ready to be bound to any key you like.

File Pickers

| Functions | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | builtin.find_files | Lists files in your current working directory, respects .gitignore