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 built-in pickers, sorters and previewers.

Built-in Support:

• Vim
• Files
• Git
• LSP
• Treesitter

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

Telescope Table of Contents

• Getting Started
• Usage
• Customization
• Mappings
• Pickers
• Sorters
• Previewers
• Themes
• Extensions
• API
• Media
• Gallery
• FAQ
• Configuration recipes
• Contributing

Getting Started

This section should guide to run your first built-in pickers 😄.

Neovim Nightly (0.5) is required for telescope.nvim to work.

Optional dependences

• sharkdp/bat (preview)
• sharkdp/fd (finder)
• BurntSushi/ripgrep (finder)
• nvim-treesitter/nvim-treesitter (finder/preview)
• neovim LSP (picker)
• devicons (icons)

Installation

Using vim-plug

Plug 'nvim-lua/popup.nvim'
Plug 'nvim-lua/plenary.nvim'
Plug 'nvim-telescope/telescope.nvim'

Using dein

call dein#add('nvim-lua/popup.nvim')
call dein#add('nvim-lua/plenary.nvim')
call dein#add('nvim-telescope/telescope.nvim')

Using packer.nvim

use {
  'nvim-telescope/telescope.nvim',
  requires = {{'nvim-lua/popup.nvim'}, {'nvim-lua/plenary.nvim'}}
}

Usage

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

" Find files using Telescope command-line sugar.
nnoremap <leader>ff <cmd>Telescope find_files<cr>
nnoremap <leader>fg <cmd>Telescope live_grep<cr>
nnoremap <leader>fb <cmd>Telescope buffers<cr>
nnoremap <leader>fh <cmd>Telescope help_tags<cr>

" Using lua functions
nnoremap <leader>ff <cmd>lua require('telescope.builtin').find_files()<cr>
nnoremap <leader>fg <cmd>lua require('telescope.builtin').live_grep()<cr>
nnoremap <leader>fb <cmd>lua require('telescope.builtin').buffers()<cr>
nnoremap <leader>fh <cmd>lua require('telescope.builtin').help_tags()<cr>

See built-in pickers for the list of all built-in 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 either by applying customizations globally or individual pre picker.

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

Telescope Defaults

As an example of using the setup() method, the following code configures telescope.nvim to its default settings.

require('telescope').setup{
  defaults = {
    vimgrep_arguments = {
      'rg',
      '--color=never',
      '--no-heading',
      '--with-filename',
      '--line-number',
      '--column',
      '--smart-case'
    },
    prompt_position = "bottom",
    prompt_prefix = "> ",
    selection_caret = "> ",
    entry_prefix = "  ",
    initial_mode = "insert",
    selection_strategy = "reset",
    sorting_strategy = "descending",
    layout_strategy = "horizontal",
    layout_defaults = {
      horizontal = {
        mirror = false,
      },
      vertical = {
        mirror = false,
      },
    },
    file_sorter =  require'telescope.sorters'.get_fuzzy_file,
    file_ignore_patterns = {},
    generic_sorter =  require'telescope.sorters'.get_generic_fuzzy_sorter,
    shorten_path = true,
    winblend = 0,
    width = 0.75,
    preview_cutoff = 120,
    results_height = 1,
    results_width = 0.8,
    border = {},
    borderchars = { '─', '│', '─', '│', '╭', '╮', '╯', '╰' },
    color_devicons = true,
    use_less = true,
    set_env = { ['COLORTERM'] = 'truecolor' }, -- default = nil,
    file_previewer = require'telescope.previewers'.vim_buffer_cat.new,
    grep_previewer = require'telescope.previewers'.vim_buffer_vimgrep.new,
    qflist_previewer = require'telescope.previewers'.vim_buffer_qflist.new,

    -- Developer configurations: Not meant for general override
    buffer_previewer_maker = require'telescope.previewers'.buffer_previewer_maker
  }
}

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

Options affecting Presentation

Options for extension developers

Options affecting Sorting

Mappings

Mappings are fully customizable. Many familiar mapping patterns are setup as defaults.

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

Much like built-in 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()
    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 and make them apply to all pickers:

local actions = require('telescope.actions')
-- Global remapping
------------------------------
require('telescope').setup{
  defaults = {
    mappings = {
      i = {
        -- To disable a keymap, put [map] = false
        -- So, to not map "<C-n>", just put
        ["<c-x>"] = false,

        -- Otherwise, just set the mapping to the function that you want it to be.
        ["<C-i>"] = actions.select_horizontal,

        -- Add up multiple actions
        ["<CR>"] = actions.select_default + actions.center,

        -- You can perform as many actions in a row as you like
        ["<CR>"] = actions.select_default + actions.center + my_cool_custom_action,
      },
      n = {
        ["<esc>"] = actions.close,
        ["<C-i>"] = my_cool_custom_action,
      },
    },
  }
}

For a picker specific remapping, it can be done by setting its attach_mappings key to a function, like this

local actions = require('telescope.actions')
local action_set = require('telescope.actions.set')
-- Picker specific remapping
------------------------------
require('telescope.builtin').fd({ -- or new custom picker's attach_mappings field:
  attach_mappings = function(prompt_bufnr)
    -- This will replace select no mather on which key it is mapped by default
    action_set.select:replace(function(prompt_bufnr, type)
      local entry = action_state.get_selected_entry()
      actions.close(prompt_bufnr)
      print(vim.inspect(entry))
      -- Code here
    end)

    -- You can also enhance an action with pre and post action which will run before of after an action
    action_set.select:enhance({
      pre = function()
          -- Will run before actions.select_default
      end,
      post = function()
          -- Will run after actions.select_default
      end,
    })

    -- Or replace for all commands: default, horizontal, vertical, tab
    action_set.select:replace(function(_, type)
      print(cmd) -- Will print edit, new, vnew or tab depending on your keystroke
    end)

    return true
  end,
})
------------------------------
-- More practical example of adding a new mapping
require'telescope.builtin'.git_branches({ attach_mappings = function(_, map)
  map('i', '<c-d>', actions.git_delete_branch) -- this action already exist
  map('n', '<c-d>', actions.git_delete_branch) -- this action already exist
  -- for more actions look at lua/telescope/actions/init.lua
  return true
end})

For more info, see ./developers.md

Pickers

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

:lua require'telescope.builtin'.planets{}

:nnoremap <Leader>pp :lua require'telescope.builtin'.planets{}

File Pickers

Vim Pickers

LSP Pickers

Git Pickers

Treesitter Picker

Lists Picker

Previewers

The default previewers are from now on vim_buffer_ previewers. They use vim buffers for displaying files and use tree-sitter or regex for file highlighting. These previewers are guessing the filetype of the selected file, so there might be cases where it misses, thus leading to wrong highlights. This is because we can't determine the filetype in the traditional way (we don't do bufload. We read the file async with vim.loop.fs_ and attach only a highlighter), because we can't execute autocommands, otherwise the speed of the previewer would slow down considerably. If you want to configure more filetypes take a look at plenary wiki.

If you want to configure the vim_buffer_ previewer, e.g. you want the line to wrap do this:

autocmd User TelescopePreviewerLoaded setlocal wrap

Sorters

A Sorter is called by the Picker on each item returned by the Finder. It return a number, which is equivalent to the "distance" between the current prompt and the entry returned by a finder.

Themes

Common groups of settings can be set up to allow for themes. We have some built in themes but are looking for more cool options.

To use a theme, simply append it to a built-in function:

nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({}))<cr>
" Change an option
nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({ winblend = 10 }))<cr>

or use with command:

Telescope find_files theme=get_dropdown

Themes should work with every telescope.builtin function. If you wish to make a theme, check out lua/telescope/themes.lua.

Autocmds

Telescope user autocmds:

Extensions

Telescope provides the capabilties to create & register extensions, which improve telescope in a variety of ways.

Some extensions provide integration with external tools, outside of the scope of builtins. Others provide performance enhancements by using compiled C and interfacing directly with Lua.

Loading extensions

To load an extension, use the load_extension function as shown in the example below:

-- This will load fzy_native and have it override the default file sorter
require('telescope').load_extension('fzy_native')

You may skip explicitly loading extensions (they will then be lazy-loaded), but tab completions will not be available right away.

Accessing pickers from extensions

Pickers from extensions are added to the :Telescope command under their respective name. For example:

" Run the `configurations` picker from nvim-dap
:Telescope dap configurations

They can also be called directly from lua:

-- Run the `configurations` picker from nvim-dap
require('telescope').extensions.dap.configurations()

Community Extensions

For a list of community extensions, please consult the wiki: Extensions

API

Finders

-- lua/telescope/finders.lua
Finder:new{
  entry_maker     = function(line) end,
  fn_command      = function() { command = "", args  = { "ls-files" } } end,
  static          = false,
  maximum_results = false
}

Picker

This section is an overview of how custom pickers can be created any configured.

-- lua/telescope/pickers.lua
Picker:new{
  prompt_title            = "", -- REQUIRED
  finder                  = FUNCTION, -- see lua/telescope/finder.lua
  sorter                  = FUNCTION, -- see lua/telescope/sorter.lua
  previewer               = FUNCTION, -- see lua/telescope/previewer.lua
  selection_strategy      = "reset", -- follow, reset, row
  border                  = {},
  borderchars             = {"─", "│", "─", "│", "┌", "┐", "┘", "└"},
  preview_cutoff          = 120,
  default_selection_index = 1, -- Change the index of the initial selection row
}

To override only some of the default mappings, you can use the attach_mappings key in the setup table. For example:

function my_custom_picker(results)
  pickers.new(opts, {
    prompt_title = 'Custom Picker',
    finder = finders.new_table(results),
    sorter = sorters.fuzzy_with_index_bias(),
    attach_mappings = function(_, map)
      -- Map "<CR>" in insert mode to the function, actions.set_command_line
      map('i', '<CR>', actions.set_command_line)

      -- If the return value of `attach_mappings` is true, then the other
      -- default mappings are still applies.
      --
      -- Return false if you don't want any other mappings applied.
      --
      -- A return value _must_ be returned. It is an error to not return anything.
      return true
    end,
  }):find()
end

Layout (display)

Resolvable:

1. 0 <= number < 1:
   • This means total height as a percentage
2. 1 <= number:
   • This means total height as a fixed number
3. function(picker, columns, lines):
   • returns one of the above options
   • return max.min(110, max_rows * .5)

layout_strategies.horizontal = function(self, max_columns, max_lines)
  local layout_config = validate_layout_config(self.layout_config or {}, {
    width_padding = "How many cells to pad the width",
    height_padding = "How many cells to pad the height",
    preview_width = "(Resolvable): Determine preview width",
  })
  ...
end

Vim Commands

All telescope.nvim functions are wrapped in vim commands for easy access, its supports tab completions and settings options.

" Show all builtin pickers
:Telescope

" Tab completion
:Telescope |<tab>
:Telescope find_files

" Setting options
:Telescope find_files prompt_prefix=🔍

" If option is table type in lua code ,you can use `,` connect each command string eg:
" find_command,vimgrep_arguments they are both table type. so config it in commandline like
:Telescope find_files find_command=rg,--ignore,--hidden,--files prompt_prefix=🔍

Media

• What is Telescope? (Video)
• More advanced configuration (Video)
• Example video

FAQ

How to change some defaults in built-in functions?

All options available from the setup function (see Configuration options) and some other functions can be easily changed in custom pickers or built-in functions.

-- Disable preview for find files
nnoremap <leader>ff :lua require('telescope.builtin').find_files({previewer = false})<CR>

-- Change change prompt prefix for find_files builtin function:
nnoremap <leader>fg :lua require('telescope.builtin').live_grep({ prompt_prefix=🔍 })<CR>
nnoremap <leader>fg :Telescope live_grep prompt_prefix=🔍<CR>

How to change Telescope Highlights group?

There are 10 highlights group you can play around with in order to meet your needs:

highlight TelescopeSelection      guifg=#D79921 gui=bold " selected item
highlight TelescopeSelectionCaret guifg=#CC241D " selection caret
highlight TelescopeMultiSelection guifg=#928374 " multisections
highlight TelescopeNormal         guibg=#00000  " floating windows created by telescope.

" Border highlight groups.
highlight TelescopeBorder         guifg=#ffffff
highlight TelescopePromptBorder   guifg=#ffffff
highlight TelescopeResultsBorder  guifg=#ffffff
highlight TelescopePreviewBorder  guifg=#ffffff

" Used for highlighting characters that you match.
highlight TelescopeMatching       guifg=blue

" Used for the prompt prefix
highlight TelescopePromptPrefix   guifg=red

To checkout the default values of the highlight groups, checkout plugin/telescope.vim

How to add autocmds to telescope prompt ?

TelescopePrompt is the prompt Filetype. You can customize the Filetype as you would normally.

Contributing

All contributions are welcome! Just open a pull request. Please read CONTRIBUTING.md