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

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

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

Neovim (v0.9.0) or the latest neovim nightly commit is required for telescope.nvim to work. The neovim version also needs to be compiled with LuaJIT, we currently do not support Lua5.1 because of some ongoing issues.

We also suggest you install one native telescope sorter to significantly improve sorting performance. Take a look at either telescope-fzf-native.nvim or telescope-fzy-native.nvim. For more information and a performance benchmark take a look at the Extensions wiki.

It is suggested to either use the latest release tag or our release branch (which will get consistent updates) 0.1.x.

It is not suggested to run latest master.

Using vim-plug

Using Lua:

See builtin pickers for a list of all builtin functions.

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.

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 :lua require'telescope.builtin'.planets{} :nnoremap pp :lua require'telescope.builtin'.planets{} File Pickers Functions Description builtin.find_files Lists files in your current working directory, respects .gitignore builtin.git_files Fuzzy search through the output of git ls-files command, respects .gitignore builtin.grep_string Searches for the string under your cursor or selection in your current working directory builtin.live_grep Search for a string in your current working directory and get results live as you type, respects .gitignore. (Requires ripgrep) Vim Pickers Functions Description builtin.buffers Lists open buffers in current neovim instance builtin.oldfiles Lists previously open files builtin.commands Lists available plugin/user commands and runs them on builtin.tags Lists tags in current directory with tag location file preview (users are required to run ctags -R to generate tags or update when introducing new changes) builtin.command_history Lists commands that were executed recently, and reruns them on builtin.search_history Lists searches that were executed recently, and reruns them on builtin.help_tags Lists available help tags and opens a new window with the relevant help info on builtin.man_pages Lists manpage entries, opens them in a help window on builtin.marks Lists vim marks and their value builtin.colorscheme Lists available colorschemes and applies them on builtin.quickfix Lists items in the quickfix list builtin.quickfixhistory Lists all quickfix lists in your history and open them with builtin.quickfix or quickfix window builtin.loclist Lists items from the current window's location list builtin.jumplist Lists Jump List entries builtin.vim_options Lists vim options, allows you to edit the current value on builtin.registers Lists vim registers, pastes the contents of the register on builtin.autocommands Lists vim autocommands and goes to their declaration on builtin.spell_suggest Lists spelling suggestions for the current word under the cursor, replaces word with selected suggestion on builtin.keymaps Lists normal mode keymappings builtin.filetypes Lists all available filetypes builtin.highlights Lists all available highlights builtin.current_buffer_fuzzy_find Live fuzzy search inside of the currently open buffer builtin.current_buffer_tags Lists all of the tags for the currently open buffer, with a preview builtin.resume Lists the results incl. multi-selections of the previous picker builtin.pickers Lists the previous pickers incl. multi-selections (see :h telescope.defaults.cache_picker) Neovim LSP Pickers Functions Description builtin.lsp_references Lists LSP references for word under the cursor builtin.lsp_incoming_calls Lists LSP incoming calls for word under the cursor builtin.lsp_outgoing_calls Lists LSP outgoing calls for word under the cursor builtin.lsp_document_symbols Lists LSP document symbols in the current buffer builtin.lsp_workspace_symbols Lists LSP document symbols in the current workspace builtin.lsp_dynamic_workspace_symbols Dynamically Lists LSP for all workspace symbols builtin.diagnostics Lists Diagnostics for all open buffers or a specific buffer. Use option bufnr=0 for current buffer. builtin.lsp_implementations Goto the implementation of the word under the cursor if there's only one, otherwise show all options in Telescope builtin.lsp_definitions Goto the definition of the word under the cursor, if there's only one, otherwise show all options in Telescope builtin.lsp_type_definitions Goto the definition of the type of the word under the cursor, if there's only one, otherwise show all options in Telescope Git Pickers Functions Description builtin.git_commits Lists git commits with diff preview, checkout action , reset mixed m, reset soft s and reset hard h builtin.git_bcommits Lists buffer's git commits with diff preview and checks them out on builtin.git_bcommits_range Lists buffer's git commits in a range of lines. Use options from and to to specify the range. In visual mode, lists commits for the selected lines builtin.git_branches Lists all branches with log preview, checkout action , track action , rebase action, create action , switch action , delete action and merge action builtin.git_status Lists current changes per file with diff preview and add action. (Multi-selection still WIP) builtin.git_stash Lists stash items in current repository with ability to apply them on Treesitter Picker Functions Description builtin.treesitter Lists Function names, variables, from Treesitter! Lists Picker Functions Description builtin.planets Use the telescope... builtin.builtin Lists Built-in pickers and run them on . builtin.reloader Lists Lua modules and reload them on . builtin.symbols Lists symbols inside a file data/telescope-sources/*.json found in your rtp. More info and symbol sources can be found here Previewers Previewers Description previewers.vim_buffer_cat.new Default previewer for files. Uses vim buffers previewers.vim_buffer_vimgrep.new Default previewer for grep and similar. Uses vim buffers previewers.vim_buffer_qflist.new Default previewer for qflist. Uses vim buffers previewers.cat.new Terminal previewer for files. Uses cat/bat previewers.vimgrep.new Terminal previewer for grep and similar. Uses cat/bat previewers.qflist.new Terminal previewer for qflist. Uses cat/bat

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 using vim.filetype to guess the filetype for the selected file. The guessing is done by inspecting the filename, the head of the file(shebang) and the tail of the file (modeline). If you have trouble with filetype detection you should read :help vim.filetype.

We need to do it manually because we can't determine the filetype in the traditional way: We don't do bufload and instead read the file asynchronously with vim.loop.fs_ and attach only a highlighter; otherwise the speed of the previewer would slow down considerably.

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

A data field is passed to the callback, which contains the filetype and the buffer name.

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

Layout can be configured by choosing a specific layout_strategy and specifying a particular layout_config for that strategy. For more details on available strategies and configuration options, see :help telescope.layout.

Some options for configuring sizes in layouts are "resolvable". This means that they can take different forms, and will be interpreted differently according to which form they take. For example, if we wanted to set the width of a picker using the vertical layout strategy to 50% of the screen width, we would specify that width as 0.5, but if we wanted to specify the width to be exactly 80 characters wide, we would specify it as 80. For more details on resolving sizes, see :help telescope.resolve.

As an example, if we wanted to specify the layout strategy and width, but only for this instance, we could do something like:

If we wanted to change the width for every time we use the vertical layout strategy, we could add the following to our setup() call:

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 builtin function:

for more information and how to realize more complex commands please read :help telescope.command.

Telescope user autocmds:

Telescope provides the capabilities to create & register extensions, which improves 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 over LuaJIT's FFI library.

A list of community extensions can be found in the Extensions wiki. Always read the README of the extension you want to install, but here is a general overview of how most extensions work.

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

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

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

They can also be called directly from Lua:

For writing your own picker and for information about the API please read the Developers Documentation.

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