Github GitHub - nvim-telescope/telescope.nvim: Find, Filter, Preview, Pick. All...
source link: https://github.com/nvim-telescope/telescope.nvim
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
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:
For more showcases of Telescope, please visit the Showcase section in the Telescope Wiki
Telescope Table of Contents
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>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 per 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
Keys Description Optionsprompt_position
Where the prompt should be located.
top/bottom
prompt_prefix
What should the prompt prefix be.
string
selection_caret
What should the selection caret be.
string
entry_prefix
What should be shown in front of every entry. (current selection excluded)
string
initial_mode
The initial mode when a prompt is opened.
insert/normal
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
Extra settings for fine-tuning how your layout looks
supported settings
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
file_previewer
What telescope previewer to use for files.
Previewers
grep_previewer
What telescope previewer to use for grep and similar
Previewers
qflist_previewer
What telescope previewer to use for qflist
Previewers
Options for extension developers
Keys Description Optionsbuffer_previewer_maker
How a file gets loaded and which highlighter will be used. Extensions will change it
function
Options affecting Sorting
Keys Description Optionsfile_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 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
Functions Descriptionbuiltin.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, optionally ignores untracked files
builtin.grep_string
Searches for the string under your cursor in your current working directory
builtin.live_grep
Search for a string in your current working directory and get results live as you type (respecting .gitignore)
builtin.file_browser
Lists files and folders in your current working directory, open files, navigate your filesystem, and create new files and folders
Options for builtin.live_grep
Keys Description Optionsgrep_open_files
Restrict live_grep to currently open files, mutually exclusive with search_dirs
boolean
search_dirs
List of directories to search in, mutually exclusive with grep_open_files
list
Vim Pickers
Functions Descriptionbuiltin.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 <cr>
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 <cr>
builtin.search_history
Lists searches that were executed recently, and reruns them on <cr>
builtin.help_tags
Lists available help tags and opens a new window with the relevant help info on <cr>
builtin.man_pages
Lists manpage entries, opens them in a help window on <cr>
builtin.marks
Lists vim marks and their value
builtin.colorscheme
Lists available colorschemes and applies them on <cr>
builtin.quickfix
Lists items in the quickfix list
builtin.loclist
Lists items from the current window's location list
builtin.vim_options
Lists vim options, allows you to edit the current value on <cr>
builtin.registers
Lists vim registers, pastes the contents of the register on <cr>
builtin.autocommands
Lists vim autocommands and goes to their declaration on <cr>
builtin.spell_suggest
Lists spelling suggestions for the current word under the cursor, replaces word with selected suggestion on <cr>
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
Neovim LSP Pickers
Functions Descriptionbuiltin.lsp_references
Lists LSP references 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.lsp_code_actions
Lists any LSP actions for the word under the cursor, that can be triggered with <cr>
builtin.lsp_range_code_actions
Lists any LSP actions for a given range, that can be triggered with <cr>
builtin.lsp_document_diagnostics
Lists LSP diagnostics for the current buffer
builtin.lsp_workspace_diagnostics
Lists LSP diagnostics for the current workspace if supported, otherwise searches in all open buffers
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
Pre-filtering option for LSP pickers
For the *_symbols
and *_diagnostics
LSP pickers, there is a special filtering that you can use to specify your
search. When in insert mode while the picker is open, type :
and then press <C-l>
to get an autocomplete menu
filled with all of the possible filters you can use.
i.e. while using the lsp_document_symbols
picker, adding :methods:
to your query filters out any document
document symbols that are not recognized as methods by treesitter.
Git Pickers
Functions Descriptionbuiltin.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, checkout action <cr>
, track action <C-t>
and rebase action<C-r>
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 <cr>
Treesitter Picker
Functions Descriptionbuiltin.treesitter
Lists Function names, variables, from Treesitter!
Lists Picker
Functions Descriptionbuiltin.planets
Use the telescope...
builtin.builtin
Lists Built-in pickers and run them on enter.
builtin.reloader
Lists lua modules and reload them on enter.
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 Descriptionpreviewers.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
Deprecated previewer for files. Uses cat
/bat
previewers.vimgrep.new
Deprecated previewer for grep and similar. Uses cat
/bat
previewers.qflist.new
Deprecated 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 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
Sorters Descriptionsorters.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
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
.
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 Descriptionthemes.get_dropdown
A list like centered list. dropdown
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:
Event DescriptionUser TelescopeFindPre
Do it before Telescope creates all the floating windows
User TelescopePreviewerLoaded
Do it after Telescope previewer window is created
Extensions
Telescope provides the capabilities 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
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
:
- 0 <= number < 1:
- This means total height as a percentage
- 1 <= number:
- This means total height as a fixed number
- 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
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 highlight groups 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
Related Projects
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK