diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/telescope.txt | 951 |
1 files changed, 643 insertions, 308 deletions
diff --git a/doc/telescope.txt b/doc/telescope.txt index cdcfe56..9543949 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -4,101 +4,101 @@ Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search, filter, find and pick things in Lua. +Getting started with telescope: + 1. Run `:checkhealth telescope` to make sure everything is installed. + 2. Evalulate it working with `:Telescope find_files` or `:lua + require("telescope.builtin").find_files()` + 3. Put a `require("telescope").setup() call somewhere in your neovim config. + 4. Read |telescope.setup| to check what config keys are available and what + you can put inside the setup call + 5. Read |telescope.builtin| to check which builtin pickers are offered and + what options these implement + 6. Profit + To find out more: https://github.com/nvim-telescope/telescope.nvim :h telescope.setup + :h telescope.command :h telescope.builtin + :h telescope.themes :h telescope.layout + :h telescope.resolve :h telescope.actions + :h telescope.actions.state + :h telescope.actions.set + :h telescope.actions.utils + :h telescope.actions.generate + :h telescope.previewers + :h telescope.actions.history telescope.setup({opts}) *telescope.setup()* - Setup function to be run by user. Configures the defaults, extensions and - other aspects of telescope. - - - Valid keys for {opts.defaults} - - *telescope.defaults.border* - border: ~ - Boolean defining if borders are added to Telescope windows. - - Default: true - - *telescope.defaults.cache_picker* - cache_picker: ~ - This field handles the configuration for picker caching. - By default it is a table, with default values (more below). - To disable caching, set it to false. - - Caching preserves all previous multi selections and results and - therefore may result in slowdown or increased RAM occupation - if too many pickers (`cache_picker.num_pickers`) or entries - ('cache_picker.limit_entries`) are cached. - - Fields: - - num_pickers: The number of pickers to be cached. - Set to -1 to preserve all pickers of your session. - If passed to a picker, the cached pickers with - indices larger than `cache_picker.num_pickers` will - be cleared. - Default: 1 - - limit_entries: The amount of entries that will be written in the - Default: 1000 - + Setup function to be run by user. Configures the defaults, pickers and + extensions of telescope. - *telescope.defaults.default_mappings* - default_mappings: ~ - Not recommended to use except for advanced users. + Usage: + > + require('telescope').setup{ + defaults = { + -- Default configuration for telescope goes here: + -- config_key = value, + -- .. + }, + 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 + } + } +< - Will allow you to completely remove all of telescope's default maps - and use your own. + Valid keys for {opts.defaults} - *telescope.defaults.dynamic_preview_title* - dynamic_preview_title: ~ - Will change the title of the preview window dynamically, where it - is supported. Means the preview window will for example show the - full filename. + *telescope.defaults.sorting_strategy* + sorting_strategy: ~ + Determines the direction "better" results are sorted towards. - Default: false + Available options are: + - "descending" (default) + - "ascending" - *telescope.defaults.entry_prefix* - entry_prefix: ~ - Prefix in front of each result entry. Current selection not included. + *telescope.defaults.selection_strategy* + selection_strategy: ~ + Determines how the cursor acts after each sort iteration. - Default: ' ' + Available options are: + - "reset" (default) + - "follow" + - "row" + - "closest" - *telescope.defaults.history* - history: ~ - This field handles the configuration for prompt history. - By default it is a table, with default values (more below). - To disable history, set it to false. - - Currently mappings still need to be added, Example: - mappings = { - i = { - ["<C-Down>"] = require('telescope.actions').cycle_history_next, - ["<C-Up>"] = require('telescope.actions').cycle_history_prev, - }, - }, + *telescope.defaults.scroll_strategy* + scroll_strategy: ~ + Determines what happens if you try to scroll past the view of the + picker. - Fields: - - path: The path to the telescope history as string. - default: stdpath("data")/telescope_history - - limit: The amount of entries that will be written in the - history. - Warning: If limit is set to nil it will grown unbound. - default: 100 - - handler: A lua function that implements the history. - This is meant as a developer setting for extensions to - override the history handling, e.g., - https://github.com/nvim-telescope/telescope-smart-history.nvim, - which allows context sensitive (cwd + picker) history. + Available options are: + - "cycle" (default) + - "limit" - Default: - require('telescope.actions.history').get_simple_history + *telescope.defaults.layout_strategy* + layout_strategy: ~ + Determines the default layout of Telescope pickers. + See |telescope.layout| for details of the available strategies. + Default: 'horizontal' *telescope.defaults.layout_config* layout_config: ~ @@ -131,12 +131,195 @@ telescope.setup({opts}) *telescope.setup()* } - *telescope.defaults.layout_strategy* - layout_strategy: ~ - Determines the default layout of Telescope pickers. - See |telescope.layout| for details of the available strategies. + *telescope.defaults.winblend* + winblend: ~ + Configure winblend for telescope floating windows. See |winblend| for + more information. - Default: 'horizontal' + Default: 0 + + *telescope.defaults.prompt_prefix* + prompt_prefix: ~ + The character(s) that will be shown in front of Telescope's prompt. + + Default: '> ' + + *telescope.defaults.selection_caret* + selection_caret: ~ + The character(s) that will be shown in front of the current selection. + + + Default: '> ' + + *telescope.defaults.entry_prefix* + entry_prefix: ~ + Prefix in front of each result entry. Current selection not included. + + Default: ' ' + + *telescope.defaults.initial_mode* + initial_mode: ~ + Determines in which mode telescope starts. Valid Keys: + `insert` and `normal`. + + Default: "insert" + + *telescope.defaults.border* + border: ~ + Boolean defining if borders are added to Telescope windows. + + Default: true + + *telescope.defaults.path_display* + path_display: ~ + Determines how file paths are displayed + + path_display can be set to an array with a combination of: + - "hidden" hide file names + - "tail" only display the file name, and not the path + - "absolute" display absolute paths + - "smart" remove as much from the path as possible to only show + the difference between the displayed paths + - "shorten" only display the first character of each directory in + the path + + You can also specify the number of characters of each directory name + to keep by setting `path_display.shorten = num`. + e.g. for a path like + `alpha/beta/gamma/delta.txt` + setting `path_display.shorten = 1` will give a path like: + `a/b/g/delta.txt` + Similarly, `path_display.shorten = 2` will give a path like: + `al/be/ga/delta.txt` + + path_display can also be set to 'hidden' string to hide file names + + path_display can also be set to a function for custom formatting of + the path display. Example: + + -- Format path as "file.txt (path\to\file\)" + path_display = function(opts, path) + local tail = require("telescope.utils").path_tail(path) + return string.format("%s (%s)", tail, path) + end, + + Default: {} + + *telescope.defaults.borderchars* + borderchars: ~ + Set the borderchars of telescope floating windows. It has to be a + table of 8 string values. + + Default: { "─", "│", "─", "│", "╭", "╮", "╯", "╰" } + + *telescope.defaults.get_status_text* + get_status_text: ~ + A function that determines what the virtual text looks like. + Signature: function(picker) -> str + + Default: function that shows current count / all + + *telescope.defaults.dynamic_preview_title* + dynamic_preview_title: ~ + Will change the title of the preview window dynamically, where it + is supported. For example, the preview window's title could show up as + the full filename. + + Default: false + + *telescope.defaults.history* + history: ~ + This field handles the configuration for prompt history. + By default it is a table, with default values (more below). + To disable history, set it to false. + + Currently mappings still need to be added, Example: + mappings = { + i = { + ["<C-Down>"] = require('telescope.actions').cycle_history_next, + ["<C-Up>"] = require('telescope.actions').cycle_history_prev, + }, + }, + + Fields: + - path: The path to the telescope history as string. + default: stdpath("data")/telescope_history + - limit: The amount of entries that will be written in the + history. + Warning: If limit is set to nil it will grown unbound. + default: 100 + - handler: A lua function that implements the history. + This is meant as a developer setting for extensions to + override the history handling, e.g., + https://github.com/nvim-telescope/telescope-smart-history.nvim, + which allows context sensitive (cwd + picker) history. + + Default: + require('telescope.actions.history').get_simple_history + + *telescope.defaults.cache_picker* + cache_picker: ~ + This field handles the configuration for picker caching. + By default it is a table, with default values (more below). + To disable caching, set it to false. + + Caching preserves all previous multi selections and results and + therefore may result in slowdown or increased RAM occupation + if too many pickers (`cache_picker.num_pickers`) or entries + ('cache_picker.limit_entries`) are cached. + + Fields: + - num_pickers: The number of pickers to be cached. + Set to -1 to preserve all pickers of your session. + If passed to a picker, the cached pickers with + indices larger than `cache_picker.num_pickers` will + be cleared. + Default: 1 + - limit_entries: The amount of entries that will be written in the + Default: 1000 + + + *telescope.defaults.vimgrep_arguments* + vimgrep_arguments: ~ + Defines the command that will be used for `live_grep` and `grep_string` + pickers. + Hint: Make sure that color is currently set to `never` because we do + not yet interpret color codes + Hint 2: Make sure that these options are in your changes arguments: + "--no-heading", "--with-filename", "--line-number", "--column" + because we need them so the ripgrep output is in the correct format. + + Default: { + "rg", + "--color=never", + "--no-heading", + "--with-filename", + "--line-number", + "--column", + "--smart-case" + } + + *telescope.defaults.use_less* + use_less: ~ + Boolean if less should be enabled in term_previewer (deprecated and + currently no longer used in the builtin pickers). + + Default: true + + *telescope.defaults.set_env* + set_env: ~ + Set an environment for term_previewer. A table of key values: + Example: { COLORTERM = "truecolor", ... } + Hint: Empty table is not allowed. + + Default: nil + + *telescope.defaults.color_devicons* + color_devicons: ~ + Boolean if devicons should be enabled or not. + Hint: Coloring only works if |termguicolors| is enabled. + + Default: true *telescope.defaults.mappings* mappings: ~ @@ -193,81 +376,92 @@ telescope.setup({opts}) *telescope.setup()* ..., - *telescope.defaults.path_display* - path_display: ~ - Determines how file paths are displayed + *telescope.defaults.default_mappings* + default_mappings: ~ + Not recommended to use except for advanced users. - path_display can be set to an array with a combination of: - - "hidden" hide file names - - "tail" only display the file name, and not the path - - "absolute" display absolute paths - - "smart" remove as much from the path as possible to only show - the difference between the displayed paths - - "shorten" only display the first character of each directory in - the path + Will allow you to completely remove all of telescope's default maps + and use your own. - You can also specify the number of characters of each directory name - to keep by setting `path_display.shorten = num`. - e.g. for a path like - `alpha/beta/gamma/delta.txt` - setting `path_display.shorten = 1` will give a path like: - `a/b/g/delta.txt` - Similarly, `path_display.shorten = 2` will give a path like: - `al/be/ga/delta.txt` - path_display can also be set to 'hidden' string to hide file names + *telescope.defaults.file_sorter* + file_sorter: ~ + A function pointer that specifies the file_sorter. This sorter will + be used for find_files, git_files and similar. + Hint: If you load a native sorter, you dont need to change this value, + the native sorter will override it anyway. - path_display can also be set to a function for custom formatting of - the path display. Example: + Default: require("telescope.sorters").get_fzy_sorter - -- Format path as "file.txt (path\to\file\)" - path_display = function(opts, path) - local tail = require("telescope.utils").path_tail(path) - return string.format("%s (%s)", tail, path) - end, + *telescope.defaults.generic_sorter* + generic_sorter: ~ + A function pointer to the generic sorter. The sorter that should be + used for everything that is not a file. + Hint: If you load a native sorter, you dont need to change this value, + the native sorter will override it anyway. - Default: {} + Default: require("telescope.sorters").get_fzy_sorter - *telescope.defaults.prompt_prefix* - prompt_prefix: ~ - Will be shown in front of the prompt. + *telescope.defaults.prefilter_sorter* + prefilter_sorter: ~ + This points to a wrapper sorter around the generic_sorter that is able + to do prefiltering. + Its usually used for lsp_*_symbols and lsp_*_diagnostics - Default: '> ' + Default: require("telescope.sorters").prefilter - *telescope.defaults.scroll_strategy* - scroll_strategy: ~ - Determines what happens you try to scroll past view of the picker. + *telescope.defaults.file_ignore_patterns* + file_ignore_patterns: ~ + A table of lua regex that define the files that should be ignored. + Example: { "^scratch/" } -- ignore all files in scratch directory + Example: { "%.npz" } -- ignore all npz files + See: https://www.lua.org/manual/5.1/manual.html#5.4.1 for more + information about lua regex - Available options are: - - "cycle" (default) - - "limit" + Default: nil - *telescope.defaults.selection_caret* - selection_caret: ~ - Will be shown in front of the selection. + *telescope.defaults.file_previewer* + file_previewer: ~ + Function pointer to the default file_previewer. It is mostly used + for find_files, git_files and similar. + You can change this function pointer to either use your own + previewer or use the command-line program bat as the previewer: + require("telescope.previewers").cat.new - Default: '> ' + Default: require("telescope.previewers").vim_buffer_cat.new - *telescope.defaults.selection_strategy* - selection_strategy: ~ - Determines how the cursor acts after each sort iteration. + *telescope.defaults.grep_previewer* + grep_previewer: ~ + Function pointer to the default vim_grep previewer. It is mostly + used for live_grep, grep_string and similar. + You can change this function pointer to either use your own + previewer or use the command-line program bat as the previewer: + require("telescope.previewers").vimgrep.new - Available options are: - - "reset" (default) - - "follow" - - "row" - - "closest" + Default: require("telescope.previewers").vim_buffer_vimgrep.new - *telescope.defaults.sorting_strategy* - sorting_strategy: ~ - Determines the direction "better" results are sorted towards. + *telescope.defaults.qflist_previewer* + qflist_previewer: ~ + Function pointer to the default qflist previewer. It is mostly + used for qflist, loclist and lsp. + You can change this function pointer to either use your own + previewer or use the command-line program bat as the previewer: + require("telescope.previewers").qflist.new - Available options are: - - "descending" (default) - - "ascending" + Default: require("telescope.previewers").vim_buffer_vimgrep.new + + *telescope.defaults.buffer_previewer_maker* + buffer_previewer_maker: ~ + Developer option that defines the underlining functionality + of the buffer previewer. + For interesting configuration examples take a look at + https://github.com/nvim-telescope/telescope.nvim/wiki/Configuration-Recipes + + Default: require("telescope.previewers").buffer_previewer_maker Parameters: ~ - {opts} (table) Configuration opts. Keys: defaults, extensions + {opts} (table) Configuration opts. Keys: defaults, pickers, + extensions telescope.register_extension({mod}) *telescope.register_extension()* @@ -346,41 +540,16 @@ To use any of Telescope's default options or any picker-specific options, call your desired picker by passing a lua table to the picker with all of the options you want to use. Here's an example with the live_grep picker: -:lua require('telescope.builtin').live_grep({ - prompt_title = 'find string in open buffers...', - grep_open_files = true -}) --- or with dropdown theme -:lua require('telescope.builtin').find_files(require('telescope.themes').get_dropdown{ - previewer = false -}) - -You can also pass default configurations to builtin pickers. These options will -also be added if the picker is executed with `Telescope find_files`. - -require("telescope").setup { - pickers = { - buffers = { - show_all_buffers = true, - sort_lastused = true, - theme = "dropdown", - previewer = false, - mappings = { - i = { - ["<c-d>"] = require("telescope.actions").delete_buffer, - -- or right hand side can also be the name of the action as string - ["<c-d>"] = "delete_buffer", - }, - n = { - ["<c-d>"] = require("telescope.actions").delete_buffer, - } - } - } - } -} - -This will use the default configuration options. Other configuration options -are still in flux at the moment +> + :lua require('telescope.builtin').live_grep({ + prompt_title = 'find string in open buffers...', + grep_open_files = true + }) + -- or with dropdown theme + :lua require('telescope.builtin').find_files(require('telescope.themes').get_dropdown{ + previewer = false + }) +< builtin.live_grep({opts}) *builtin.live_grep()* Search for a string and get results live as you type (respecting @@ -390,18 +559,22 @@ builtin.live_grep({opts}) *builtin.live_grep()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {cwd} (string) root dir to search from (default is cwd, - use utils.buffer_dir() to search - relative to open buffer) - {grep_open_files} (boolean) if true, restrict search to open files - only, mutually exclusive with - `search_dirs` - {search_dirs} (table) directory/directories to search in, - mutually exclusive with - `grep_open_files` - {additional_args} (function) function(opts) which returns a table of - additional arguments to be passed on + Options: ~ + {cwd} (string) root dir to search from (default: + cwd, use utils.buffer_dir() to + search relative to open buffer) + {grep_open_files} (boolean) if true, restrict search to open + files only, mutually exclusive with + `search_dirs` + {search_dirs} (table) directory/directories to search in, + mutually exclusive with + `grep_open_files` + {additional_args} (function) function(opts) which returns a table + of additional arguments to be passed + on + {max_results} (number) define a upper result value + {disable_coordinates} (boolean) don't show the line & row numbers + (default: false) builtin.grep_string({opts}) *builtin.grep_string()* @@ -411,17 +584,24 @@ builtin.grep_string({opts}) *builtin.grep_string()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {cwd} (string) root dir to search from (default is cwd, - use utils.buffer_dir() to search - relative to open buffer) - {search} (string) the query to search - {search_dirs} (table) directory/directories to search in - {use_regex} (boolean) if true, special characters won't be - escaped, allows for using regex (default - is false) - {additional_args} (function) function(opts) which returns a table of - additional arguments to be passed on + Options: ~ + {cwd} (string) root dir to search from (default: + cwd, use utils.buffer_dir() to + search relative to open buffer) + {search} (string) the query to search + {search_dirs} (table) directory/directories to search in + {use_regex} (boolean) if true, special characters won't be + escaped, allows for using regex + (default: false) + {word_match} (string) can be set to `-w` to enable exact + word matches + {additional_args} (function) function(opts) which returns a table + of additional arguments to be passed + on + {disable_coordinates} (boolean) don't show the line and row numbers + (default: false) + {sort_only_text} (boolean) only sort the text, not the file, + line or row (default: false) builtin.find_files({opts}) *builtin.find_files()* @@ -431,18 +611,19 @@ builtin.find_files({opts}) *builtin.find_files()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {cwd} (string) root dir to search from (default is cwd, use + Options: ~ + {cwd} (string) root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer) {find_command} (table) command line arguments for `find_files` to - use for the search, overrides default config + use for the search, overrides default: + config {follow} (boolean) if true, follows symlinks (i.e. uses `-L` flag for the `find` command) {hidden} (boolean) determines whether to show hidden files or - not (default is false) + not (default: false) {no_ignore} (boolean) show files ignored by .gitignore, .ignore, - etc. (default is false) + etc. (default: false) {search_dirs} (table) directory/directories to search in @@ -469,14 +650,14 @@ builtin.file_browser({opts}) *builtin.file_browser()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {cwd} (string) root dir to browse from (default is cwd, use + Options: ~ + {cwd} (string) root dir to browse from (default: cwd, use utils.buffer_dir() to search relative to open buffer) - {depth} (number) file tree depth to display (default is 1) - {dir_icon} (string) change the icon for a directory. default: + {depth} (number) file tree depth to display (default: 1) + {dir_icon} (string) change the icon for a directory. (default: ) {hidden} (boolean) determines whether to show hidden files or not - (default is false) + (default: false) builtin.treesitter() *builtin.treesitter()* @@ -486,9 +667,14 @@ builtin.treesitter() *builtin.treesitter()* node you want to see (i.e. `:var:`) - Fields: ~ - {show_line} (boolean) if true, shows the row:column that the result - is found at (default is true) + Options: ~ + {show_line} (boolean) if true, shows the row:column that the + result is found at (default: true) + {bufnr} (number) specify the buffer number where + treesitter should run. (default: + current buffer) + {symbol_highlights} (table) string -> string. Matches symbol with + hl_group builtin.current_buffer_fuzzy_find({opts})*builtin.current_buffer_fuzzy_find()* @@ -498,6 +684,10 @@ builtin.current_buffer_fuzzy_find({opts})*builtin.current_buffer_fuzzy_find()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {skip_empty_lines} (boolean) if true we dont display empty lines + (default: false) + builtin.tags({opts}) *builtin.tags()* Lists tags in current directory with tag location file preview (users are @@ -508,10 +698,16 @@ builtin.tags({opts}) *builtin.tags()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {ctags_file} (string) specify a particular ctags file to use - {show_line} (boolean) if true, shows the content of the line the tag - is found on in the picker (default is true) + Options: ~ + {cwd} (string) root dir to search from (default: cwd, use + utils.buffer_dir() to search relative to + open buffer) + {ctags_file} (string) specify a particular ctags file to use + {show_line} (boolean) if true, shows the content of the line the + tag is found on in the picker (default: + true) + {only_sort_tags} (boolean) if true we will only sort tags (default: + false) builtin.current_buffer_tags({opts}) *builtin.current_buffer_tags()* @@ -521,6 +717,17 @@ builtin.current_buffer_tags({opts}) *builtin.current_buffer_tags()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {cwd} (string) root dir to search from (default: cwd, use + utils.buffer_dir() to search relative to + open buffer) + {ctags_file} (string) specify a particular ctags file to use + {show_line} (boolean) if true, shows the content of the line the + tag is found on in the picker (default: + true) + {only_sort_tags} (boolean) if true we will only sort tags (default: + false) + builtin.git_files({opts}) *builtin.git_files()* Fuzzy search for files tracked by Git. This command lists the output of the @@ -533,13 +740,17 @@ builtin.git_files({opts}) *builtin.git_files()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ + Options: ~ + {cwd} (string) specify the path of the repo + {use_git_root} (boolean) if we should use git root as cwd or + the cwd (important for submodule) + (default: true) {show_untracked} (boolean) if true, adds `--others` flag to command and shows untracked files - (default is true) + (default: true) {recurse_submodules} (boolean) if true, adds the `--recurse-submodules` flag to command - (default is false) + (default: false) builtin.git_commits({opts}) *builtin.git_commits()* @@ -554,8 +765,10 @@ builtin.git_commits({opts}) *builtin.git_commits()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {cwd} (string) specify the path of the repo + Options: ~ + {cwd} (string) specify the path of the repo + {use_git_root} (boolean) if we should use git root as cwd or the cwd + (important for submodule) (default: true) builtin.git_bcommits({opts}) *builtin.git_bcommits()* @@ -570,10 +783,12 @@ builtin.git_bcommits({opts}) *builtin.git_bcommits()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {cwd} (string) specify the path of the repo - {current_file} (string) specify the current file that should be used - for bcommits (default: current buffer) + Options: ~ + {cwd} (string) specify the path of the repo + {use_git_root} (boolean) if we should use git root as cwd or the cwd + (important for submodule) (default: true) + {current_file} (string) specify the current file that should be used + for bcommits (default: current buffer) builtin.git_branches({opts}) *builtin.git_branches()* @@ -593,6 +808,11 @@ builtin.git_branches({opts}) *builtin.git_branches()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {cwd} (string) specify the path of the repo + {use_git_root} (boolean) if we should use git root as cwd or the cwd + (important for submodule) (default: true) + builtin.git_status({opts}) *builtin.git_status()* Lists git status for current directory @@ -604,6 +824,14 @@ builtin.git_status({opts}) *builtin.git_status()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {cwd} (string) specify the path of the repo + {use_git_root} (boolean) if we should use git root as cwd or the cwd + (important for submodule) (default: true) + {git_icons} (table) string -> string. Matches name with icon + (see source code, make_entry.lua + git_icon_defaults) + builtin.git_stash({opts}) *builtin.git_stash()* Lists stash items in current repository @@ -614,6 +842,11 @@ builtin.git_stash({opts}) *builtin.git_stash()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {cwd} (string) specify the path of the repo + {use_git_root} (boolean) if we should use git root as cwd or the cwd + (important for submodule) (default: true) + builtin.builtin({opts}) *builtin.builtin()* Lists all of the community maintained pickers built into Telescope @@ -622,6 +855,40 @@ builtin.builtin({opts}) *builtin.builtin()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {ignore_filename} (boolean) dont show filenames (default: true) + {include_extensions} (boolean) if true will show the pickers of the + installed extensions (default: false) + + +builtin.resume({opts}) *builtin.resume()* + Opens the previous picker in the identical state (incl. multi selections) + - Notes: + - Requires `cache_picker` in setup or when having invoked pickers, see + |telescope.defaults.cache_picker| + + + Parameters: ~ + {opts} (table) options to pass to the picker + + Options: ~ + {cache_index} (number) what picker to resume, where 1 denotes most + recent (default: 1) + + +builtin.pickers({opts}) *builtin.pickers()* + Opens a picker over previously cached pickers in there preserved states + (incl. multi selections) + - Default keymaps: + - `<C-x>`: delete the selected cached picker + - Notes: + - Requires `cache_picker` in setup or when having invoked pickers, see + |telescope.defaults.cache_picker| + + + Parameters: ~ + {opts} (table) options to pass to the picker + builtin.planets({opts}) *builtin.planets()* Use the telescope... @@ -630,6 +897,10 @@ builtin.planets({opts}) *builtin.planets()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {show_pluto} (boolean) we love pluto (default: false, because its a + hidden feature) + builtin.symbols({opts}) *builtin.symbols()* Lists symbols inside of `data/telescope-sources/*.json` found in your @@ -643,7 +914,7 @@ builtin.symbols({opts}) *builtin.symbols()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ + Options: ~ {symbol_path} (string) specify the second path. Default: `stdpath("data")/telescope/symbols/*.json` {sources} (table) specify a table of sources you want to load @@ -665,6 +936,9 @@ builtin.quickfix({opts}) *builtin.quickfix()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {ignore_filename} (boolean) dont show filenames (default: true) + builtin.loclist({opts}) *builtin.loclist()* Lists items from the current window's location list, jumps to location on @@ -674,6 +948,9 @@ builtin.loclist({opts}) *builtin.loclist()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {ignore_filename} (boolean) dont show filenames (default: true) + builtin.oldfiles({opts}) *builtin.oldfiles()* Lists previously open files, opens on `<cr>` @@ -682,6 +959,9 @@ builtin.oldfiles({opts}) *builtin.oldfiles()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {only_cwd} (boolean) show only files in the cwd (default: false) + builtin.command_history({opts}) *builtin.command_history()* Lists commands that were executed recently, and reruns them on `<cr>` @@ -705,35 +985,6 @@ builtin.search_history({opts}) *builtin.search_history()* {opts} (table) options to pass to the picker -builtin.resume({opts}) *builtin.resume()* - Opens the previous picker in the identical state (incl. multi selections) - - Notes: - - Requires `cache_picker` in setup or when having invoked pickers, see - |telescope.defaults.cache_picker| - - - Parameters: ~ - {opts} (table) options to pass to the picker - - Fields: ~ - {cache_index} (number) what picker to resume, where 1 denotes most - recent (default 1) - - -builtin.pickers({opts}) *builtin.pickers()* - Opens a picker over previously cached pickers in there preserved states - (incl. multi selections) - - Default keymaps: - - `<C-x>`: delete the selected cached picker - - Notes: - - Requires `cache_picker` in setup or when having invoked pickers, see - |telescope.defaults.cache_picker| - - - Parameters: ~ - {opts} (table) options to pass to the picker - - builtin.vim_options({opts}) *builtin.vim_options()* Lists vim options, allows you to edit the current value on `<cr>` @@ -750,6 +1001,11 @@ builtin.help_tags({opts}) *builtin.help_tags()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {lang} (string) specify language (default: vim.o.helplang) + {fallback} (boolean) fallback to en if language isn't installed + (default: true) + builtin.man_pages({opts}) *builtin.man_pages()* Lists manpage entries, opens them in a help window on `<cr>` @@ -758,9 +1014,11 @@ builtin.man_pages({opts}) *builtin.man_pages()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {sections} (table) a list of sections to search, use `{ "ALL" }` to - search in all sections + Options: ~ + {sections} (table) a list of sections to search, use `{ "ALL" }` + to search in all sections (default: { "1" }) + {man_cmd} (function) that returns the man command. (Default: + `apropos ""` on linux, `apropos " "` on macos) builtin.reloader({opts}) *builtin.reloader()* @@ -770,6 +1028,10 @@ builtin.reloader({opts}) *builtin.reloader()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {column_len} (number) define the max column len for the module name + (default: dynamic, longest module name) + builtin.buffers({opts}) *builtin.buffers()* Lists open buffers in current neovim instance, opens selected buffer on @@ -779,23 +1041,24 @@ builtin.buffers({opts}) *builtin.buffers()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ + Options: ~ {show_all_buffers} (boolean) if true, show all buffers, - including unloaded buffers (default - true) + including unloaded buffers + (default: true) {ignore_current_buffer} (boolean) if true, don't show the current - buffer in the list (default false) + buffer in the list (default: false) {only_cwd} (boolean) if true, only show buffers in the - current working directory (default + current working directory (default: false) {sort_lastused} (boolean) Sorts current and last buffer to the top and selects the lastused - (default false) + (default: false) {sort_mru} (boolean) Sorts all buffers after most recent used. Not just the current and last - one (default false) + one (default: false) {bufnr_width} (number) Defines the width of the buffer - numbers in front of the filenames + numbers in front of the filenames + (default: dynamic) builtin.colorscheme({opts}) *builtin.colorscheme()* @@ -805,7 +1068,7 @@ builtin.colorscheme({opts}) *builtin.colorscheme()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ + Options: ~ {enable_preview} (boolean) if true, will preview the selected color @@ -876,6 +1139,9 @@ builtin.tagstack({opts}) *builtin.tagstack()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {ignore_filename} (boolean) dont show filenames (default: true) + builtin.jumplist({opts}) *builtin.jumplist()* Lists items from Vim's jumplist, jumps to location on `<cr>` @@ -884,6 +1150,9 @@ builtin.jumplist({opts}) *builtin.jumplist()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {ignore_filename} (boolean) dont show filenames (default: true) + builtin.lsp_references({opts}) *builtin.lsp_references()* Lists LSP references for word under the cursor, jumps to reference on @@ -893,6 +1162,9 @@ builtin.lsp_references({opts}) *builtin.lsp_references()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {timeout} (number) timeout for the sync call (default: 10000) + builtin.lsp_definitions({opts}) *builtin.lsp_definitions()* Goto the definition of the word under the cursor, if there's only one, @@ -902,9 +1174,13 @@ builtin.lsp_definitions({opts}) *builtin.lsp_definitions()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {jump_type} (string) how to goto definition if there is only one, - values: "tab", "split", "vsplit", "never" + Options: ~ + {timeout} (number) timeout for the sync call (default: + 10000) + {jump_type} (string) how to goto definition if there is only + one, values: "tab", "split", "vsplit", + "never" + {ignore_filename} (boolean) dont show filenames (default: true) builtin.lsp_type_definitions({opts}) *builtin.lsp_type_definitions()* @@ -915,9 +1191,13 @@ builtin.lsp_type_definitions({opts}) *builtin.lsp_type_definitions()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {jump_type} (string) how to goto definition if there is only one, - values: "tab", "split", "vsplit", "never" + Options: ~ + {timeout} (number) timeout for the sync call (default: + 10000) + {jump_type} (string) how to goto definition if there is only + one, values: "tab", "split", "vsplit", + "never" + {ignore_filename} (boolean) dont show filenames (default: true) builtin.lsp_implementations({opts}) *builtin.lsp_implementations()* @@ -928,9 +1208,13 @@ builtin.lsp_implementations({opts}) *builtin.lsp_implementations()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {jump_type} (string) how to goto implementation if there is only one, - values: "tab", "split", "vsplit", "never" + Options: ~ + {timeout} (number) timeout for the sync call (default: + 10000) + {jump_type} (string) how to goto implementation if there is + only one, values: "tab", "split", + "vsplit", "never" + {ignore_filename} (boolean) dont show filenames (default: true) builtin.lsp_code_actions({opts}) *builtin.lsp_code_actions()* @@ -941,6 +1225,9 @@ builtin.lsp_code_actions({opts}) *builtin.lsp_code_actions()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {timeout} (number) timeout for the sync call (default: 10000) + builtin.lsp_range_code_actions({opts}) *builtin.lsp_range_code_actions()* Lists any LSP actions for a given range, that can be triggered with `<cr>` @@ -949,6 +1236,11 @@ builtin.lsp_range_code_actions({opts}) *builtin.lsp_range_code_actions()* Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {timeout} (number) timeout for the sync call (default: 10000) + {start_line} (number) where the code action ends (default: handled by + :'<,'>Telescope lsp_range_code_actions) + builtin.lsp_document_symbols({opts}) *builtin.lsp_document_symbols()* Lists LSP document symbols in the current buffer @@ -960,9 +1252,17 @@ builtin.lsp_document_symbols({opts}) *builtin.lsp_document_symbols()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {ignore_filename} (type) string with file to ignore - {symbols} (string|table) filter results by symbol kind(s) + Options: ~ + {timeout} (number) timeout for the sync call + (default: 10000) + {ignore_filename} (boolean) dont show filenames (default: + true) + {show_line} (boolean) if true, shows the content of the + line the tag is found on (default: + false) + {symbols} (string|table) filter results by symbol kind(s) + {symbol_highlights} (table) string -> string. Matches symbol + with hl_group builtin.lsp_workspace_symbols({opts}) *builtin.lsp_workspace_symbols()* @@ -975,9 +1275,19 @@ builtin.lsp_workspace_symbols({opts}) *builtin.lsp_workspace_symbols()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {ignore_filename} (string) file(s) to ignore - {symbols} (string|table) filter results by symbol kind(s) + Options: ~ + {query} (string) for what to query the workspace + (default: "") + {timeout} (number) timeout for the sync call + (default: 10000) + {ignore_filename} (boolean) dont show filenames (default: + false) + {show_line} (boolean) if true, shows the content of the + line the tag is found on (default: + false) + {symbols} (string|table) filter results by symbol kind(s) + {symbol_highlights} (table) string -> string. Matches symbol + with hl_group builtin.lsp_dynamic_workspace_symbols({opts})*builtin.lsp_dynamic_workspace_symbols()* @@ -990,6 +1300,13 @@ builtin.lsp_dynamic_workspace_symbols({opts})*builtin.lsp_dynamic_workspace_symb Parameters: ~ {opts} (table) options to pass to the picker + Options: ~ + {ignore_filename} (boolean) dont show filenames (default: false) + {show_line} (boolean) if true, shows the content of the line + the symbol is found on (default: false) + {symbol_highlights} (table) string -> string. Matches symbol with + hl_group + builtin.lsp_document_diagnostics({opts}) *builtin.lsp_document_diagnostics()* Lists LSP diagnostics for the current buffer @@ -1004,7 +1321,7 @@ builtin.lsp_document_diagnostics({opts}) *builtin.lsp_document_diagnostics()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ + Options: ~ {severity} (string|number) filter diagnostics by severity name (string) or id (number) {severity_limit} (string|number) keep diagnostics equal or more @@ -1013,8 +1330,8 @@ builtin.lsp_document_diagnostics({opts}) *builtin.lsp_document_diagnostics()* {severity_bound} (string|number) keep diagnostics equal or less severe wrt severity name (string) or id (number) - {no_sign} (bool) hide LspDiagnosticSigns from Results - (default is false) + {no_sign} (boolean) hide LspDiagnosticSigns from Results + (default: false) {line_width} (number) set length of diagnostic entry text in Results @@ -1033,7 +1350,7 @@ builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()* Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ + Options: ~ {severity} (string|number) filter diagnostics by severity name (string) or id (number) {severity_limit} (string|number) keep diagnostics equal or more @@ -1042,8 +1359,8 @@ builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()* {severity_bound} (string|number) keep diagnostics equal or less severe wrt severity name (string) or id (number) - {no_sign} (bool) hide LspDiagnosticSigns from Results - (default is false) + {no_sign} (boolean) hide LspDiagnosticSigns from Results + (default: false) {line_width} (number) set length of diagnostic entry text in Results @@ -1061,10 +1378,11 @@ themes.get_dropdown() *themes.get_dropdown()* Dropdown style theme. Usage: - + > `local builtin = require('telescope.builtin')` `local themes = require('telescope.themes')` `builtin.find_files(themes.get_dropdown())` +< @@ -1072,10 +1390,12 @@ themes.get_cursor() *themes.get_cursor()* Cursor style theme. Usage: + > `local builtin = require('telescope.builtin')` `local themes = require('telescope.themes')` `builtin.lsp_code_actions(themes.get_cursor())` +< @@ -1083,10 +1403,11 @@ themes.get_ivy() *themes.get_ivy()* Ivy style theme. Usage: - + > `local builtin = require('telescope.builtin')` `local themes = require('telescope.themes')` `builtin.find_files(themes.get_ivy())` +< @@ -1098,6 +1419,7 @@ Layout strategies are different functions to position telescope. All layout strategies are functions with the following signature: +> function(picker, columns, lines, layout_config) -- Do some calculations here... return { @@ -1106,6 +1428,7 @@ All layout strategies are functions with the following signature: prompt = prompt_configuration, } end +< Parameters: ~ - picker : A Picker object. (docs coming soon) @@ -1773,18 +2096,21 @@ utils.map_entries({prompt_bufnr}, {f}) *utils.map_entries()* - Indices are 1-indexed, whereas rows are 0-indexed. - Warning: `map_entries` has no return value. - The below example showcases how to collect results + Usage: - local action_state = require "telescope.actions.state" - local action_utils = require "telescope.actions.utils" - function entry_value_by_row() - local prompt_bufnr = vim.api.nvim_get_current_buf() - local current_picker = action_state.get_current_picker(prompt_bufnr) - local results = {} - action_utils.map_entries(prompt_bufnr, function(entry, index, row) - results[row] = entry.value - end) - return results - end + > + local action_state = require "telescope.actions.state" + local action_utils = require "telescope.actions.utils" + function entry_value_by_row() + local prompt_bufnr = vim.api.nvim_get_current_buf() + local current_picker = action_state.get_current_picker(prompt_bufnr) + local results = {} + action_utils.map_entries(prompt_bufnr, function(entry, index, row) + results[row] = entry.value + end) + return results + end +< Parameters: ~ @@ -1802,18 +2128,21 @@ utils.map_selections({prompt_bufnr}, {f}) *utils.map_selections()* - Selected entries are returned in order of their selection. - Warning: `map_selections` has no return value. - The below example showcases how to collect results + Usage: - local action_state = require "telescope.actions.state" - local action_utils = require "telescope.actions.utils" - function selection_by_index() - local prompt_bufnr = vim.api.nvim_get_current_buf() - local current_picker = action_state.get_current_picker(prompt_bufnr) - local results = {} - action_utils.map_selections(prompt_bufnr, function(entry, index) - results[index] = entry.value - end) - return results - end + > + local action_state = require "telescope.actions.state" + local action_utils = require "telescope.actions.utils" + function selection_by_index() + local prompt_bufnr = vim.api.nvim_get_current_buf() + local current_picker = action_state.get_current_picker(prompt_bufnr) + local results = {} + action_utils.map_selections(prompt_bufnr, function(entry, index) + results[index] = entry.value + end) + return results + end +< Parameters: ~ @@ -1839,6 +2168,7 @@ Module for convenience to override defaults of corresponding |telescope.actions| at |telescope.setup()|. General usage: +> require("telescope").setup { defaults = { mappings = { @@ -1853,6 +2183,7 @@ General usage: }, }, } +< action_generate.which_key({opts}) *action_generate.which_key()* Display the keymaps of registered actions similar to which-key.nvim. @@ -1980,9 +2311,11 @@ previewers.new_termopen_previewer() *previewers.new_termopen_previewer()* It requires you to specify one table entry `get_command(entry, status)`. This `get_command` function has to return the terminal command that will be executed for each entry. Example: + > get_command = function(entry, status) return { 'bat', entry.path } end +< Additionally you can define: - `title` a static title for example "File Preview" @@ -2121,10 +2454,12 @@ previewers.new_buffer_previewer() *previewers.new_buffer_previewer()* - `require('telescope.previewers.utils').ts_highlighter(bufnr, ft)` - If you want to use `vim.fn.search` or similar you need to run it in that specific buffer context. Do + > vim.api.nvim_buf_call(bufnr, function() -- for example `search` and `matchadd` end) to achieve that. +< - If you want to read a file into the buffer it's best to use `buffer_previewer_maker`. But access this function with `require('telescope.config').values.buffer_previewer_maker` because it |