/telescope.nvim

Find, Filter, Preview, Pick. All lua, all the time.

Primary LanguageLua

Telescope.nvim

Gitter

Telescope An arrangement of lenses or mirrors or both that gathers light, permitting direct observation or photographic recording of distant objects.

— thefreedictionary

Telescope.nvim is a next generation library for creating floating pickers with advanced features. It is written in lua and is built on top of latest awesome features from neovim core. Telescope.nvim is centered around modularity so much so that each picker is its own world, (meaning it can be configured in isolation from other pickers, such presentation, algorithm, mappings ... etc).

Telescope.nvim was built with the intention of becoming a library, but it has long grown to be much bigger than that. In addition to extensions Telescope.nvim comes with a growing number of community driven built-in pickers, covering a wide range of use cases and tools, and offers a customizable user interface.

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

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>ff <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_strategy = "reset",
    sorting_strategy = "descending",
    layout_strategy = "horizontal",
    layout_defaults = {
      -- TODO add builtin options.
    },
    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 { }, currently unsupported for shells like cmd.exe / powershell.exe
  }
}

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

Keys Description Options
prompt_position Where the prompt should be located. top/bottom
prompt_prefix What should the prompt prefix be. string
sorting_strategy Where first selection should be located. descending/ascending
layout_strategy How the telescope is drawn. supported layouts
winblend How transparent is the telescope window should be. NUM
layout_defaults Layout specific configuration ........ TODO TODO
width TODO NUM
preview_cutoff TODO NUM
results_height TODO NUM
results_width TODO NUM
borderchars The border chars, it gives border telescope window dict
color_devicons Whether to color devicons or not boolean
use_less Whether to use less with bat or less/cat if bat not installed boolean
set_env Set environment variables for previewer dict
scroll_strategy How to behave when the when there are no more item next/prev cycle, nil

Options affecting Sorting

Keys Description Options
file_sorter The sorter for file lists. Sorters
generic_sorter The sorter for everything else. Sorters
vimgrep_arguments The command line argument for grep search ... TODO. dict
selection_strategy What happens to the selection if the list changes. follow/reset/row
file_ignore_patterns Pattern to be ignored { "scratch/.*", "%.env"} dict
shorten_path Whether to shorten paths or not. boolean

Mappings

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

Mappings Action
<C-n>/<Down> Next item
<C-p>/<Up> Previous item
j/k Next/previous (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-c> close telescope
<Esc> close telescope (in normal mode)

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 built-in 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.goto_file_selection_split,
        -- Add up multiple actions
        ["<CR>"] = actions.goto_file_selection_edit + actions.center,
        -- You can perform as many actions in a row as you like
        ["<CR>"] = actions.goto_file_selection_edit + 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')
-- Picker specific remapping
------------------------------
require('telescope.builtin').fd({ -- or new custom picker's attach_mappings field:
  attach_mappings = function(prompt_bufnr)
    -- This will replace goto_file_selection_edit no mather on which key it is mapped by default
    actions.goto_file_selection_edit:replace(function()
      local entry = actions.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
    actions.goto_file_selection_split:enhance ({
      pre = function()
      -- Will run before actions.goto_file_selection_split
      end,
      post = function()
      -- Will run after actions.goto_file_selection_split
      end,
    })

    -- Or replace for all commands: edit, new, vnew and tab
    actions._goto_file_selection:replace(function(_, cmd)
      print(cmd) -- Will print edit, new, vnew or tab depending on your keystroke
    end)

    return true
    end,
})

Built-in Pickers

Built-in function ready to be bound to any key you like 😄.

Functions Description
builtin.planets Demo showcasing how simple to create pickers with telescope.
builtin.builtin Lists Built-in pickers and run them on enter.
builtin.find_files Lists Files in current directory.
builtin.git_files Lists Git files in current directory.
builtin.buffers Lists Open buffers in the current vim instance.
builtin.oldfiles Lists Previously open files.
builtin.commands Lists Available plugin/user commands and run it.
builtin.tags Lists Tags in current directory with preview (ctags -R)
builtin.command_history Lists Commands previously ran and run it on enter.
builtin.help_tags Lists Available help tags and open help document.
builtin.man_pages Lists Man entries.
builtin.marks Lists Markers and their value.
builtin.colorscheme Lists Colorscheme and switch to it on enter.
builtin.treesitter Lists Function names, variables, from Treesitter!
builtin.live_grep Searches in current directory files. (respecting .gitignore)
builtin.current_buffer_fuzzy_find Searches in current buffer lines.
builtin.current_buffer_tags Lists Tags in current buffer.
builtin.grep_string Searches for a string under the cursor in current directory.
builtin.lsp_references Searches in LSP references.
builtin.lsp_document_symbols Searches in LSP Document Symbols in the current document.
builtin.lsp_workspace_symbols Searches in LSP all workspace symbols.
builtin.lsp_code_actions Lists LSP action to be trigged on enter.
builtin.quickfix Lists items from quickfix.
builtin.loclist Lists items from current window's location list.
builtin.reloader Lists lua modules and reload them on enter.
builtin.vim_options Lists vim options and on enter edit the options value.
builtin.registers Lists vim registers and edit or paste selection.
builtin.keymaps Lists normal-mode mappings.
builtin.filetypes Lists all filetypes.
builtin.highlights Lists all highlights.
builtin.git_commits Lists git commits with diff preview and on enter checkout the commit.
builtin.git_bcommits Lists buffer's git commits with diff preview and checkouts it out on enter.
builtin.git_branches Lists all branches with log preview and checkout action.
builtin.git_status Lists current changes per file with diff preview and add action. (Multiselection still WIP)
.................................. Your next awesome finder function here :D

Built-in Sorters

Sorters Description
sorters.get_fuzzy_file Telescope's default sorter for files
sorters.get_generic_fuzzy_sorter Telescope's default sorter for everything else
sorters.get_levenshtein_sorter Using Levenshtein distance algorithm (don't use :D)
sorters.get_fzy_sorter Using fzy algorithm
sorters.fuzzy_with_index_bias Used to list stuff with consideration to when the item is added
.................................. Your next awesome sorter here :D

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.

Built-in 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.

Themes Description
themes.get_dropdown A list like centered list. example
... Your next awesome theme here :D

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>

Themes should work with every telescope.builtin function. If you wish to make theme, check out lua/telescope/themes.lua. If you need more features, make an issue :).

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.

For example:

Extensions can be refenced by doing the following:

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

To pre-load an extension (so that it will override default configurations), you can do:

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

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 funciton, actions.set_command_line
      map('i', '<CR>', actions.set_command_line)

      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

Command-line

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

" 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
:Telecope find_files find_command=rg,--ignore,--hidden,--files prompt_prefix=🔍

Media

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.

When approved, changes in the user interface and new built-in functions will need to be reflected in the documentation and in README.md.