From 5131df7df17d640191201ddb462e863022d7a61b Mon Sep 17 00:00:00 2001 From: Simon Hauser Date: Mon, 13 Sep 2021 22:03:41 +0200 Subject: [PATCH] docs: rewrite readme and add missing config values + builtin opts --- .github/ISSUE_TEMPLATE/bug_report.yml | 18 + LICENSE | 2 +- README.md | 704 +++++---------- developers.md | 312 ++++++- doc/telescope.txt | 951 +++++++++++++------- lua/telescope/actions/generate.lua | 4 +- lua/telescope/actions/utils.lua | 54 +- lua/telescope/builtin/init.lua | 190 ++-- lua/telescope/builtin/internal.lua | 7 +- lua/telescope/command.lua | 3 +- lua/telescope/config.lua | 647 ++++++++----- lua/telescope/init.lua | 57 +- lua/telescope/make_entry.lua | 8 +- lua/telescope/pickers.lua | 4 +- lua/telescope/pickers/layout_strategies.lua | 4 +- lua/telescope/previewers/init.lua | 8 +- lua/telescope/themes.lua | 14 +- 17 files changed, 1822 insertions(+), 1165 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index b136ce5..e2e2e8a 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -28,6 +28,24 @@ body: placeholder: "macOS 11.5" validations: required: true + - type: textarea + attributes: + label: "checkhealth telescope" + description: "Output of `:checkhealth telescope`" + placeholder: | + health#telescope#check + ======================================================================== + ## Checking for required plugins + - OK: plenary installed. + - OK: nvim-treesitter installed. + + ## Checking external dependencies + - OK: rg: found ripgrep 13.0.0 + - OK: fd: found fd 8.2.1 + + ## ===== Installed extensions ===== + validations: + required: true - type: textarea attributes: label: "Steps to reproduce" diff --git a/LICENSE b/LICENSE index d55bfbb..9117664 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2020 nvim-telescope +Copyright (c) 2020-2021 nvim-telescope Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 99a689c..cd7fcfe 100644 --- a/README.md +++ b/README.md @@ -6,61 +6,64 @@ 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. +`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](#pickers), [sorters](#sorters) and [previewers](#previewers). - -### Built-in Support: - -- [Vim](#vim-pickers) -- [Files](#file-pickers) -- [Git](#git-pickers) -- [LSP](#neovim-lsp-pickers) -- [Treesitter](#treesitter-picker) +Community driven builtin [pickers](#pickers), [sorters](#sorters) and +[previewers](#previewers). ![Preview](https://i.imgur.com/TTTja6t.gif) -For more showcases of Telescope, please visit the [Showcase section](https://github.com/nvim-telescope/telescope.nvim/wiki/Showcase) in the Telescope Wiki - - - +For more showcases of Telescope, please visit the [Showcase +section](https://github.com/nvim-telescope/telescope.nvim/wiki/Showcase) in the +Telescope Wiki ## Telescope Table of Contents - [Getting Started](#getting-started) - [Usage](#usage) - [Customization](#customization) -- [Mappings](#mappings) +- [Default Mappings](#default-mappings) - [Pickers](#pickers) -- [Sorters](#sorters) - [Previewers](#previewers) +- [Sorters](#sorters) +- [Layout](#layout-display) - [Themes](#themes) +- [Commands](#vim-commands) +- [Autocmds](#autocmds) - [Extensions](#extensions) - [API](#api) - [Media](#media) -- [Gallery](https://github.com/nvim-telescope/telescope.nvim/wiki/Gallery) -- [FAQ](#faq) -- [Configuration recipes](https://github.com/nvim-telescope/telescope.nvim/wiki/Configuration-Recipes) - [Contributing](#contributing) ## Getting Started -This section should guide you to run your first built-in pickers :smile:. +This section should guide you to run your first builtin pickers. [Neovim (v0.5)](https://github.com/neovim/neovim/releases/tag/v0.5.0) or newer is required for `telescope.nvim` to work. +### Suggested dependencies + +- [BurntSushi/ripgrep](https://github.com/BurntSushi/ripgrep) is required for + `live_grep` and `grep_string` + +We also suggest you install one native telescope sorter to significantly improve +sorting performance. Take a look at either +[telescope-fzf-native.nvim](https://github.com/nvim-telescope/telescope-fzf-native.nvim) +or +[telescope-fzy-native.nvim](https://github.com/nvim-telescope/telescope-fzy-native.nvim). +For more information and a performance benchmark take a look at the +[Extensions](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions) +wiki. + ### Optional dependencies -- [sharkdp/bat](https://github.com/sharkdp/bat) (preview) - [sharkdp/fd](https://github.com/sharkdp/fd) (finder) -- [BurntSushi/ripgrep](https://github.com/BurntSushi/ripgrep) (finder) - [nvim-treesitter/nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) (finder/preview) - [neovim LSP]( https://neovim.io/doc/user/lsp.html) (picker) - [devicons](https://github.com/kyazdani42/nvim-web-devicons) (icons) - ### Installation Using [vim-plug](https://github.com/junegunn/vim-plug) @@ -85,6 +88,14 @@ use { } ``` +### checkhealth + +Make sure you call `:checkhealth telescope` after installing telescope to ensure +everything is setup correctly. + +After this setup you can continue reading here or switch to `:help telescope` +to get an understanding of how to use Telescope and how to configure it. + ## Usage Try the command `:Telescope find_files` @@ -104,7 +115,7 @@ nnoremap fb lua require('telescope.builtin').buffers() nnoremap fh lua require('telescope.builtin').help_tags() ``` -See [built-in pickers](#pickers) for a list of all built-in functions. +See [builtin pickers](#pickers) for a list of all builtin functions. ## Customization @@ -114,63 +125,46 @@ customize your `telescope.nvim`. Unlike most vim plugins, `telescope.nvim` can be customized by either applying customizations globally, or individually per picker. -- **Global Customization** affecting all pickers can be done through the - main `setup()` method (see defaults below) -- **Individual Customization** affecting a single picker by passing `opts` - built-in pickers (e.g. `builtin.fd(opts)`) see [Configuration recipes](https://github.com/nvim-telescope/telescope.nvim/wiki/Configuration-Recipes) wiki page for ideas. +- **Global Customization** affecting all pickers can be done through the main + `setup()` method (see defaults below) +- **Individual Customization** affecting a single picker by passing `opts` to + builtin pickers (e.g. `builtin.find_files(opts)`) see + [Configuration recipes](https://github.com/nvim-telescope/telescope.nvim/wiki/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: +### Telescope setup structure ```lua require('telescope').setup{ defaults = { - vimgrep_arguments = { - 'rg', - '--color=never', - '--no-heading', - '--with-filename', - '--line-number', - '--column', - '--smart-case' - }, - prompt_prefix = "> ", - selection_caret = "> ", - entry_prefix = " ", - initial_mode = "insert", - selection_strategy = "reset", - sorting_strategy = "descending", - layout_strategy = "horizontal", - layout_config = { - 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, - winblend = 0, - border = {}, - borderchars = { '─', '│', '─', '│', '╭', '╮', '╯', '╰' }, - color_devicons = true, - use_less = true, - path_display = {}, - 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 + -- 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 } } ``` +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 << EOF code-snippet EOF`: @@ -183,214 +177,61 @@ require('telescope').setup{ EOF ``` - - -### Options affecting Presentation - -| Keys | Description | Options | -|------------------------|-------------------------------------------------------|-----------------------------| -| `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 | -| `layout_strategy` | How the telescope is drawn. | [supported layouts](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts) | -| `layout_config` | Extra settings for fine-tuning how your layout looks | [supported settings](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts#layout-defaults) | -| `sorting_strategy` | Where first selection should be located. | descending/ascending | -| `scroll_strategy` | How to behave when the when there are no more item next/prev | cycle, nil | -| `winblend` | How transparent is the telescope window should be. | number | -| `borderchars` | The border chars, it gives border telescope window | dict | -| `disable_devicons` | Whether to display devicons or not | boolean | -| `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 | -| `path_display` | How file paths are displayed | [supported settings](https://github.com/nvim-telescope/telescope.nvim/wiki/Path-Display-Configuration) | -| `file_previewer` | What telescope previewer to use for files. | [Previewers](#previewers) | -| `grep_previewer` | What telescope previewer to use for grep and similar | [Previewers](#previewers) | -| `qflist_previewer` | What telescope previewer to use for qflist | [Previewers](#previewers) | - - -### Options for extension developers - -| Keys | Description | Options | -|--------------------------|-------------------------------------------------------|----------------------------| -| `buffer_previewer_maker` | How a file gets loaded and which highlighter will be used. Extensions will change it | function | - -### Options affecting Sorting - -| Keys | Description | Options | -|------------------------|-------------------------------------------------------|--------------------------| -| `file_sorter` | The sorter for file lists. | [Sorters](#sorters) | -| `generic_sorter` | The sorter for everything else. | [Sorters](#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/closest | -| `file_ignore_patterns` | Pattern to be ignored `{ "scratch/.*", "%.env" }` | dict | - -### Customize Default Builtin behavior - -You can customize each default builtin behavior by adding the preferred options -into the table that is passed into `require("telescope").setup()`. - -Example: - -```lua -require("telescope").setup { - defaults = { - -- Your defaults config goes in here - }, - pickers = { - -- Your special builtin config goes in here - buffers = { - sort_lastused = true, - theme = "dropdown", - previewer = false, - mappings = { - i = { - [""] = require("telescope.actions").delete_buffer, - -- Right hand side can also be the name of the action as a string - [""] = "delete_buffer", - }, - n = { - [""] = require("telescope.actions").delete_buffer, - } - } - }, - find_files = { - theme = "dropdown" - } - }, - extensions = { - -- Your extension config goes in here - } -} -``` - -## Mappings +## Default Mappings Mappings are fully customizable. Many familiar mapping patterns are setup as defaults. -| Mappings | Action | -|----------------|--------------------------------------------------------------| -| `/` | Next item | -| `/` | Previous item | -| `j/k` | Next/previous (in normal mode) | -| `` | Confirm selection | -| `` | Confirm selection and open quickfix window | -| `` | Go to file selection as a split | -| `` | Go to file selection as a vsplit | -| `` | Go to a file in a new tab | -| `` | Scroll up in preview window | -| `` | Scroll down in preview window | +| Mappings | Action | +|----------------|---------------------------------------------| +| `/` | Next item | +| `/` | Previous item | +| `j/k` | Next/previous (in normal mode) | +| `H/M/L` | Select High/Middle/Low (in normal mode) | +| `` | Confirm selection | +| `` | Go to file selection as a split | +| `` | Go to file selection as a vsplit | +| `` | Go to a file in a new tab | +| `` | Scroll up in preview window | +| `` | Scroll down in preview window | | `/?` | Show picker mappings (in insert & normal mode, respectively) | -| `` | Close telescope | -| `` | Close telescope (in normal mode) | - -To see the full list of mappings, check out `lua/telescope/mappings.lua` and -the `default_mappings` table. +| `` | Close telescope | +| `` | Close telescope (in normal mode) | +| `` | Toggle selection and move to next selection | +| `` | Toggle selection and move to prev selection | +| `` | Send all items not filtered to qflist | +| `` | Send all selected items to qflist | -Much like [built-in pickers](#pickers), there are a number of +To see the full list of mappings, check out `lua/telescope/mappings.lua` and the +`default_mappings` table. + +Much like [builtin pickers](#pickers), there are a number of [actions](https://github.com/nvim-telescope/telescope.nvim/blob/master/lua/telescope/actions/init.lua) -you can pick from to remap your telescope buffer mappings, or create a new custom action: +you can pick from to remap your telescope buffer mappings, or create a new +custom action: - ```lua -- 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() + x = function(prompt_bufnr) 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: - -```lua -local actions = require('telescope.actions') --- Global remapping ------------------------------- -require('telescope').setup{ - defaults = { - mappings = { - i = { - -- To disable a keymap, put [map] = false - -- So, to not map "", just put - [""] = false, - - -- Otherwise, just set the mapping to the function that you want it to be. - [""] = actions.select_horizontal, - - -- Add up multiple actions - [""] = actions.select_default + actions.center, - - -- You can perform as many actions in a row as you like - [""] = actions.select_default + actions.center + my_cool_custom_action, - }, - n = { - [""] = actions.close, - [""] = my_cool_custom_action, - }, - }, - } -} -``` - -For a [picker](#pickers) specific remapping, it can be done by setting -its `attach_mappings` key to a function, like so: - -```lua -local actions = require('telescope.actions') -local action_set = require('telescope.actions.set') -local action_state = require('telescope.actions.state') --- 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 matter 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', '', actions.git_delete_branch) -- this action already exist - map('n', '', 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](./developers.md) +To remap telescope mappings, please read `:help telescope.defaults.mappings`. +To do picker specific mappings, its suggested to do this with the `pickers` +table in `telescope.setup`. Each picker accepts a `mappings` table like its +explained in `:help telescope.defaults.mappings`. ## Pickers -Built-in functions. Ready to be bound to any key you like. :smile: +Built-in functions. Ready to be bound to any key you like. ```vim :lua require'telescope.builtin'.planets{} @@ -408,13 +249,6 @@ Built-in functions. Ready to be bound to any key you like. :smile: | `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 | Options | -|------------------------|------------------------------------------------------------------------------------|---------| -| `grep_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 | Description | @@ -460,14 +294,6 @@ Built-in functions. Ready to be bound to any key you like. :smile: | `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| -#### 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 `` 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 symbols not recognized as methods by treesitter. ### Git Pickers @@ -505,13 +331,15 @@ document symbols not recognized as methods by treesitter. | `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 they miss, -leading to wrong highlights. This is 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 more filetypes, take a look at +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 they miss, leading to wrong highlights. This is 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 more filetypes, take a look at [plenary wiki](https://github.com/nvim-lua/plenary.nvim#plenaryfiletype). If you want to configure the `vim_buffer_` previewer (e.g. you want the line to wrap), do this: @@ -534,162 +362,16 @@ 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. - -![dropdown](https://i.imgur.com/SorAcXv.png) - -| Themes | Description | -|--------------------------|---------------------------------------------------------------------------------------------| -| `themes.get_dropdown` | A list like centered list. [dropdown](https://i.imgur.com/SorAcXv.png) | -| `themes.get_cursor` | [A cursor relative list.](https://github.com/nvim-telescope/telescope.nvim/pull/878) | -| `themes.get_ivy` | Bottom panel overlay. [Ivy #771](https://github.com/nvim-telescope/telescope.nvim/pull/771) | - -To use a theme, simply append it to a built-in function: - -```vim -nnoremap f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({})) -" Change an option -nnoremap f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({ winblend = 10 })) -``` - -Or use with a command: - -```vim -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 | Description | -|---------------------------------|---------------------------------------------------------| -| `User 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: - -```lua --- 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: - -```viml -" Run the `configurations` picker from nvim-dap -:Telescope dap configurations -``` - -They can also be called directly from Lua: - -```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](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions) - -## API - - -### Finders - -```lua --- 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 and configured. - -```lua --- 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 = {"─", "│", "─", "│", "┌", "┐", "┘", "└"}, - 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: - -```lua -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 "" in insert mode to the function, actions.set_command_line - map('i', '', 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) - +## Layout (display) 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. +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 @@ -719,6 +401,54 @@ require('telescope').setup({ }) ``` +## 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. + +![dropdown](https://i.imgur.com/SorAcXv.png) + +| Themes | Description | +|--------------------------|---------------------------------------------------------------------------------------------| +| `themes.get_dropdown` | A list like centered list. [dropdown](https://i.imgur.com/SorAcXv.png) | +| `themes.get_cursor` | [A cursor relative list.](https://github.com/nvim-telescope/telescope.nvim/pull/878) | +| `themes.get_ivy` | Bottom panel overlay. [Ivy #771](https://github.com/nvim-telescope/telescope.nvim/pull/771) | + +To use a theme, simply append it to a builtin function: + +```vim +nnoremap f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({})) +" Change an option +nnoremap f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({ winblend = 10 })) +``` + +Or use with a command: + +```vim +Telescope find_files theme=dropdown +``` + +Or you can configure it in the pickers table in `telescope.setup`: + +```lua +require('telescope').setup{ + defaults = { + -- ... + }, + pickers = { + find_files = { + theme = "dropdown", + } + }, + extensions = { + -- ... + } +} +``` + +Themes should work with every `telescope.builtin` function. If you wish to make +a theme, check out `lua/telescope/themes.lua`. + ## Vim Commands All `telescope.nvim` functions are wrapped in `vim` commands for easy access, @@ -735,64 +465,80 @@ tab completions and setting options. " Setting options :Telescope find_files prompt_prefix=🔍 -" If option is table type in Lua code, you can use `,` to connect each command string, e.g.: -" find_command,vimgrep_arguments are both table type. So configure it on command-line like so: +" If the option accepts a Lua table as its value, you can use, to connect each +" command string, e.g.: find_command, vimgrep_arguments are both options that +" accept a Lua table as a value. So, you can configure them on the command line +"like so: :Telescope find_files find_command=rg,--ignore,--hidden,--files prompt_prefix=🔍 ``` +for more information and how to realize more complex commands please read +`:help telescope.command`. + +## Autocmds + +Telescope user autocmds: + +| Event | Description | +|---------------------------------|---------------------------------------------------------| +| `User 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 over LuaJIT's FFI library. + +A list of community extensions can be found in the +[Extensions](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions) +wiki. Always read the README of the extension you want to install, but here is a +general overview of how most extensions work. + +### Loading extensions + +To load an extension, use the `load_extension` function as shown in the example +below: + +```lua +-- 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: + +```viml +" Run the `configurations` picker from nvim-dap +:Telescope dap configurations +``` + +They can also be called directly from Lua: + +```lua +-- Run the `configurations` picker from nvim-dap +require('telescope').extensions.dap.configurations() +``` + +## API + +For writing your own picker and for information about the API please read the +[Developers Documentation](developers.md). + ## Media - [What is Telescope? (Video)](https://www.twitch.tv/teej_dv/clip/RichDistinctPlumberPastaThat) - [More advanced configuration (Video)](https://www.twitch.tv/videos/756229115) - [Example video](https://www.youtube.com/watch?v=65AVwHZflsU) -## FAQ - - -### How to change some defaults in built-in functions? - -All options available from the setup function (see [Configuration options](#customization) -and some other functions can be easily changed in custom pickers or built-in functions. - - -```lua --- Disable preview for find_files -nnoremap ff :lua require('telescope.builtin').find_files({previewer = false}) - --- Change prompt prefix for find_files builtin function: -nnoremap fg :lua require('telescope.builtin').live_grep({ prompt_prefix="🔍" }) -nnoremap fg :Telescope live_grep prompt_prefix=🔍 -``` - -### How to change Telescope Highlights group? - -There are 10 highlight groups you can play around with in order to meet your needs: - -```viml -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 - -" Highlight characters your input matches -highlight TelescopeMatching guifg=blue - -" Color the prompt prefix -highlight TelescopePromptPrefix guifg=red -``` - -To checkout the default values of the highlight groups, check out `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. diff --git a/developers.md b/developers.md index 37b02ff..7284727 100644 --- a/developers.md +++ b/developers.md @@ -1,15 +1,311 @@ +# Developers +- [Introduction](#introduction) +- [Guide to your first Picker](#guide-to-your-first-picker) + - [Requires](#requires) + - [First Picker](#first-picker) + - [Replacing Actions](#replacing-actions) + - [Entry Maker](#entry-maker) + - [Oneshot job](#oneshot-job) + - [Previewer](#previewer) + - [More examples](#more-examples) +- [Technical](#technical) + - [picker](#picker) + - [finders](#finders) + - [actions](#actions) + - [previewers](#previewers) -## Overriding actions/action_set +## Introduction + +So you want to develop your own picker and/or extension for telescope? Then you +are in the right place! This file will first present an introduction on how to +do this. After that, this document will present a technical explanation of +pickers, finders, actions, and the previewer. You will find more information +in specific help pages and we likely will move some of the technical stuff to +our vim help docs in the future. + +This guide is mainly for telescope so it will assume that a lua knowledge is +present. You can find information for lua here: +- [Lua 5.1 Manual](https://www.lua.org/manual/5.1/) +- [Getting started using Lua in Neovim](https://github.com/nanotee/nvim-lua-guide) + +## Guide to your first Picker + +To guide you along the way to first picker we will do the following. We will +open a empty lua scratch file in which we will develop the picker and run it +each time using `:luafile %`. Later this file then be bundled as extension. + +### Requires + +The most important includes are the following modules: +```lua +local pickers = require "telescope.pickers" +local finders = require "telescope.finders" +local conf = require("telescope.config").values +``` + +- `pickers` is the main module which is used to create a new picker. +- `finders` provides interfaces to fill the picker with items. +- `config` which is used for user configuration and the `values` table holds + these configurations. So to make it easier we only get this table in `conf`. + +### First Picker + +We will now make the most simplest color picker. (Note that the previous snippet +is also required. We will approach this example step by step). + +```lua +-- our picker function: colors +local colors = function(opts) + pickers.new(opts, { + prompt_title = "colors", + finder = finders.new_table { + results = { "red", "green", "blue" } + }, + sorter = conf.generic_sorter(opts), + }):find() +end + +-- to execute the function +colors() +``` + +Running this file should open a telescope picker with the entries `red`, +`green`, `blue`. Pressing enter will open a new file, depending which element is +selected, in this case this is not what we want so we will address this after +explaining this snippet. + +We will define a new function which will take in a table `opts`. This is good +practice because now the user can define the behavior of the picker, for example +change the theme. That the user is able to change the theme we need to pass in +`opts` as the first argument to `pickers.new`. The second argument is a table +that defines the default behavior of the picker. + +We can define a `prompt_title`, this option is not required, default will be +`Prompt` if not set. + +`finder` is a required field that needs to be set to the result of a `finders` +function. In this case we take `new_table` which allows us to define a static +set of values, `results`, which is a array of elements, in this case our colors +as strings. It doesn't have to be a array of strings, it can also be a array of +tables. More to this later. + +`sorter` on the other hand is not a required field but its good practice to +define it, because the default value will set it to `empty()`, meaning no sorter +is attached and you can't filter the results. Good practice is to set the sorter +to either `conf.generic_sorter(opts)` or `conf.file_sorter(opts)`. Setting it to +a `conf` value will respect user configuration, so if a user has setup +`fzf-native` as sorter then this decision will be respected and the fzf sorter +will be attached. Its also suggested to pass in opts here because the sorter +could make use of it. As an example the fzf sorter can be configured to be case +sensitive or insensitive. A user can setup a default behavior and then alter +this behavior with the `opts` table. + +After the picker is defined you need to call `find()` to actually start the +picker. + +### Replacing Actions + +Now calling `colors()` will result in the opening of telescope with the values. +`red`, `green` and `blue`. The default theme isn't optimal for this picker so we +want to change it and thanks to the acceptance of `opts` we can. We will replace +the last line with the following to open the picker with the `dropdown` theme. + +```lua +colors(require("telescope.themes").get_dropdown{}) +``` + +Now lets address the issue that selecting a color opens a new buffer. For that +we need to replace the default select action. The benefit of replace rather than +mapping a new function to `` is that it will respect user configuration. So +if a user has remapped `select_default` to another key then this decision will +be respected and it works as expected for the user. + +To make this work we need more includes at the top of the file. + +```lua +local actions = require "telescope.actions" +local action_state = require "telescope.actions.state" +``` + +- `actions` holds all actions that can be mapped by a user and we need it to + access the default action so we can replace it. Also see `:help + telescope.actions` + +- `action_state` gives us a couple of util function we can use to get the + current picker, current selection or current line. Also see `:help + telescope.actions.state` + +So lets replace the default action. For that we need to define a new key value +pair in our table that we pass into `pickers.new`, for example after `sorter`. + +```lua + attach_mappings = function(prompt_bufnr, map) + actions.select_default:replace(function() + actions.close(prompt_bufnr) + local selection = action_state.get_selected_entry() + -- print(vim.inspect(selection)) + vim.api.nvim_put({ selection[1] }, "", false, true) + end) + return true + end, +``` + +So we do this by setting the `attach_mappings` key to a function. This function +needs to return either `true` or `false`. If it returns false it means that only +the actions defined in the function should be attached. So no +`move_selection_{next,previous}`, so most of the cases you want that this +function returns `true`. If the function does not return anything a error is +thrown. The `attach_mappings` function will get to parameters passed in +`prompt_bufnr` the buffer number of the prompt buffer, which we can use to get +the pickers object, and `map` a function we can use to map actions or functions +to arbitrary key sequences. + +Now we are replacing `select_default` the default action that happens on `` +(if not remapped). To do so we need to call `actions.select_default:replace` and +pass in a new function. In this new function we first close the picker with +`actions.close` and then get the `selection` with `action_state`. Its important +to notice that you can still get the selection and current prompt input +(`action_state.get_current_line()`) with `action_state` even tho the picker is +already closed. You can look at the selection with +`print(vim.inspect(selection))` and you will see that it differs from our input +(string), this is because we will internally pack it in a table with different +keys. You can specify this behavior and we will talk about that in the next +section. Now all that is left is to do anything with the selection we have. In +this case we just put the text in the current buffer. + +### Entry Maker + +Entry maker is a function that is used to transform a item from the finder to a +internal entry table, which has a couple of required keys. It allows to have a +different display and match something completly different. It also allows to set +a absolute path (so the file will always be found) and a relative file path as +display and for sorting. This allows that the relative file path doesn't even +have to be valid in the context of the current working directory. + +We will now try to define a our entry maker for our example by providing a +`entry_maker` to `finders.new_table` and changing our table to be a little bit +more interesting. We will end up following new input for `finders.new_table`: + +```lua + finder = finders.new_table { + results = { + { "red", "#ff0000" }, + { "green", "#00ff00" }, + { "blue", "#0000ff" }, + }, + entry_maker = function(entry) + return { + value = entry, + display = entry[1], + ordinal = entry[1], + } + end + }, +``` + +With the new snippet we now no longer have a array of strings but a array of +tables. Each table has a color name and the hex value. + +`entry_maker` is a function that will receive each table and then we can set the +values we want to set. Its best practice to have a `value` reference to the +original entry, that way you can access the whole table in your action later. + +The first required key is `display` and is either a string or a `function(tbl)`, +where `tbl` the table that is returned by `entry_maker`. For a lot of values its +suggested to have display as function especially if you are modifying it because +then the function will only be executed for the entries that are being +displayed. For examples of entry maker take a look at +`lua/telescope/make_entry.lua`. A good way to make your `display` more like a +table is to use `displayer` which can be found in +`lua/telescope/entry_display.lua`. A more simple example of `displayer` is the +function `gen_from_git_commits` in `make_entry.lua`. + +The second required key is `ordinal`, which is used for sorting. So you can have +different display and sorting values. This allows `display` to be more fancier +with icons and special indicators and a separate sorting key. + +There are more important keys which can be set but do not make sense in the +current context: +- `path`: to set the absolute path of the file to make sure its always found +- `lnum`: to specify a line number in the file. This will allow the + `conf.grep_previewer` to show that line and the default action to jump to + that line. + +### Previewer + +We will not write a previewer for this picker because it makes less sense and is +a more advanced topic. Its already documented pretty good under `:help +telescope.previewers` so you should read this section if you want to write your +own `previewer`. If you want a file previewer with or without col you should +default to `conf.file_previewer` or `conf.grep_previewer`. + +### Oneshot Job + +The `oneshot_job` finder can be used to have a async external process which will +produce results and call `entry_maker` on each new line. Example usage would be +`find`. + +```lua +finder = finders.new_oneshot_job { "find", opts }, +``` + +### More examples + +A good way to find more examples is to look into the `lua/telescope/builtin/` +directory which contains all builtin pickers. Another way to find more examples +is to take a look at the [extension wiki page](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions) +and then at a extension some wrote. + +If you still have questions after reading this guide feel free to ask us for +more information on [gitter](https://gitter.im/nvim-telescope/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) +and we happily answer your questions and potentially even improve this guide. Of +course you can also improve this guide by sending a PRs. + +## Technical + +### Picker + +This section is an overview of how custom pickers can be created and configured. + +```lua +-- lua/telescope/pickers.lua +Picker:new{ + prompt_title = "", + 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 = {"─", "│", "─", "│", "┌", "┐", "┘", "└"}, + default_selection_index = 1, -- Change the index of the initial selection row +} +``` + +### Finders + +```lua +-- lua/telescope/finders.lua +Finder:new{ + entry_maker = function(line) end, + fn_command = function() { command = "", args = { "ls-files" } } end, + static = false, + maximum_results = false +} +``` + +### Actions + +#### Overriding actions/action_set How to override what different functions / keys do. TODO: Talk about what actions vs actions sets are -### Relevant Files +##### Relevant Files - `lua/telescope/actions/init.lua` - - The most "user-facing" of the files, which has the actions we provide builtin + - The most "user-facing" of the files, which has the builtin actions that we provide - `lua/telescope/actions/set.lua` - The second most "user-facing" of the files. This provides actions that are consumed by several builtin actions, which allows for only overriding ONE item, instead of copying the same configuration / function several times. - `lua/telescope/actions/state.lua` @@ -18,7 +314,7 @@ TODO: Talk about what actions vs actions sets are - `lua/telescope/actions/mt.lua` - You probably don't need to look at this, but it defines the behavior of actions. -### `:replace(function)` +##### `:replace(function)` Directly override an action with a new function @@ -27,7 +323,7 @@ local actions = require('telescope.actions') actions.select_default:replace(git_checkout_function) ``` -### `:replace_if(conditional, function)` +##### `:replace_if(conditional, function)` Override an action only when `conditional` returns true. @@ -44,7 +340,7 @@ action_set.select:replace_if( ) ``` -### `:replace_map(configuration)` +##### `:replace_map(configuration)` ```lua local action_set = require('telescope.actions.set') @@ -54,3 +350,7 @@ action_set.select:replace_map { [function(e) return e == 0 end] = function(e) return (e + 10) end, } ``` + +### Previewers + +See `:help telescope.previewers` 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. + Setup function to be run by user. Configures the defaults, pickers and + extensions of telescope. + + 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 + } + } +< Valid keys for {opts.defaults} - *telescope.defaults.border* - border: ~ - Boolean defining if borders are added to Telescope windows. + *telescope.defaults.sorting_strategy* + sorting_strategy: ~ + Determines the direction "better" results are sorted towards. - Default: true + Available options are: + - "descending" (default) + - "ascending" - *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. + *telescope.defaults.selection_strategy* + selection_strategy: ~ + Determines how the cursor acts after each sort iteration. - 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. + Available options are: + - "reset" (default) + - "follow" + - "row" + - "closest" - 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.scroll_strategy* + scroll_strategy: ~ + Determines what happens if you try to scroll past the view of the + picker. + Available options are: + - "cycle" (default) + - "limit" - *telescope.defaults.default_mappings* - default_mappings: ~ - Not recommended to use except for advanced users. - - Will allow you to completely remove all of telescope's default maps - and use your own. - - - *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. - - Default: false - - *telescope.defaults.entry_prefix* - entry_prefix: ~ - Prefix in front of each result entry. Current selection not included. - - Default: ' ' - - *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 = { - [""] = require('telescope.actions').cycle_history_next, - [""] = 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.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 = { + [""] = require('telescope.actions').cycle_history_next, + [""] = 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 = { - [""] = require("telescope.actions").delete_buffer, - -- or right hand side can also be the name of the action as string - [""] = "delete_buffer", - }, - n = { - [""] = 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: + - ``: 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 `` @@ -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 `` @@ -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: - - ``: 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 `` @@ -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 `` @@ -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 `` @@ -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 `` @@ -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 diff --git a/lua/telescope/actions/generate.lua b/lua/telescope/actions/generate.lua index fafce8c..40fc4b7 100644 --- a/lua/telescope/actions/generate.lua +++ b/lua/telescope/actions/generate.lua @@ -3,8 +3,8 @@ ---@brief [[ --- Module for convenience to override defaults of corresponding |telescope.actions| at |telescope.setup()|. --- ---- 
 --- General usage:
+--- 
 ---   require("telescope").setup {
 ---     defaults = {
 ---       mappings = {
@@ -19,7 +19,7 @@
 ---       },
 ---     },
 ---   }
----
+--- ---@brief ]] local actions = require "telescope.actions" diff --git a/lua/telescope/actions/utils.lua b/lua/telescope/actions/utils.lua index 7c8a3ac..4d0c17d 100644 --- a/lua/telescope/actions/utils.lua +++ b/lua/telescope/actions/utils.lua @@ -16,20 +16,21 @@ local utils = {} --- - 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 +--- ---@param prompt_bufnr number: The prompt bufnr ---@param f function: Function to map onto entries of picker that takes (entry, index, row) as viable arguments function utils.map_entries(prompt_bufnr, f) @@ -52,20 +53,21 @@ end --- - 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 +--- ---@param prompt_bufnr number: The prompt bufnr ---@param f function: Function to map onto selection of picker that takes (selection) as a viable argument function utils.map_selections(prompt_bufnr, f) diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua index 0f55467..34f0089 100644 --- a/lua/telescope/builtin/init.lua +++ b/lua/telescope/builtin/init.lua @@ -1,5 +1,7 @@ ---@tag telescope.builtin +---@config { ['field_heading'] = "Options" } + ---@brief [[ --- Telescope Builtins is a collection of community maintained pickers to support common workflows. It can be used as --- reference when writing PRs, Telescope extensions, your own custom pickers, or just as a discovery tool for all of @@ -12,44 +14,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 = {
----           [""] = require("telescope.actions").delete_buffer,
----           -- or right hand side can also be the name of the action as string
----           [""] = "delete_buffer",
----         },
----         n = {
----           [""] = 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 +--- }) +--- ---@brief ]] if 1 ~= vim.fn.has "nvim-0.5" then @@ -79,28 +53,33 @@ end --- Search for a string and get results live as you type (respecting .gitignore) ---@param opts table: options to pass to the picker ----@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer) +---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer) ---@field grep_open_files boolean: if true, restrict search to open files only, mutually exclusive with `search_dirs` ---@field search_dirs table: directory/directories to search in, mutually exclusive with `grep_open_files` ---@field additional_args function: function(opts) which returns a table of additional arguments to be passed on +---@field max_results number: define a upper result value +---@field disable_coordinates boolean: don't show the line & row numbers (default: false) builtin.live_grep = require_on_exported_call("telescope.builtin.files").live_grep --- Searches for the string under your cursor in your current working directory ---@param opts table: options to pass to the picker ----@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer) +---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer) ---@field search string: the query to search ---@field search_dirs table: directory/directories to search in ----@field use_regex boolean: if true, special characters won't be escaped, allows for using regex (default is false) +---@field use_regex boolean: if true, special characters won't be escaped, allows for using regex (default: false) +---@field word_match string: can be set to `-w` to enable exact word matches ---@field additional_args function: function(opts) which returns a table of additional arguments to be passed on +---@field disable_coordinates boolean: don't show the line and row numbers (default: false) +---@field sort_only_text boolean: only sort the text, not the file, line or row (default: false) builtin.grep_string = require_on_exported_call("telescope.builtin.files").grep_string --- Search for files (respecting .gitignore) ---@param opts table: options to pass to the picker ----@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer) ----@field find_command table: command line arguments for `find_files` to use for the search, overrides default config +---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer) +---@field find_command table: command line arguments for `find_files` to use for the search, overrides default: config ---@field follow boolean: if true, follows symlinks (i.e. uses `-L` flag for the `find` command) ----@field hidden boolean: determines whether to show hidden files or not (default is false) ----@field no_ignore boolean: show files ignored by .gitignore, .ignore, etc. (default is false) +---@field hidden boolean: determines whether to show hidden files or not (default: false) +---@field no_ignore boolean: show files ignored by .gitignore, .ignore, etc. (default: false) ---@field search_dirs table: directory/directories to search in builtin.find_files = require_on_exported_call("telescope.builtin.files").find_files @@ -116,31 +95,40 @@ builtin.fd = builtin.find_files --- create the file `init.lua` inside of `lua/telescope` and will create the necessary folders (similar to how --- `mkdir -p` would work) if they do not already exist ---@param opts table: options to pass to the picker ----@field cwd string: root dir to browse from (default is cwd, use utils.buffer_dir() to search relative to open buffer) ----@field depth number: file tree depth to display (default is 1) ----@field dir_icon string: change the icon for a directory. default:  ----@field hidden boolean: determines whether to show hidden files or not (default is false) +---@field cwd string: root dir to browse from (default: cwd, use utils.buffer_dir() to search relative to open buffer) +---@field depth number: file tree depth to display (default: 1) +---@field dir_icon string: change the icon for a directory. (default: ) +---@field hidden boolean: determines whether to show hidden files or not (default: false) builtin.file_browser = require_on_exported_call("telescope.builtin.files").file_browser --- Lists function names, variables, and other symbols from treesitter queries --- - Default keymaps: --- - ``: show autocompletion menu to prefilter your query by kind of ts node you want to see (i.e. `:var:`) ----@field show_line boolean: if true, shows the row:column that the result is found at (default is true) +---@field show_line boolean: if true, shows the row:column that the result is found at (default: true) +---@field bufnr number: specify the buffer number where treesitter should run. (default: current buffer) +---@field symbol_highlights table: string -> string. Matches symbol with hl_group builtin.treesitter = require_on_exported_call("telescope.builtin.files").treesitter --- Live fuzzy search inside of the currently open buffer ---@param opts table: options to pass to the picker +---@field skip_empty_lines boolean: if true we dont display empty lines (default: false) builtin.current_buffer_fuzzy_find = require_on_exported_call("telescope.builtin.files").current_buffer_fuzzy_find --- 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) ---@param opts table: options to pass to the picker +---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer) ---@field ctags_file string: specify a particular ctags file to use ----@field show_line boolean: if true, shows the content of the line the tag is found on in the picker (default is true) +---@field show_line boolean: if true, shows the content of the line the tag is found on in the picker (default: true) +---@field only_sort_tags boolean: if true we will only sort tags (default: false) builtin.tags = require_on_exported_call("telescope.builtin.files").tags --- Lists all of the tags for the currently open buffer, with a preview ---@param opts table: options to pass to the picker +---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer) +---@field ctags_file string: specify a particular ctags file to use +---@field show_line boolean: if true, shows the content of the line the tag is found on in the picker (default: true) +---@field only_sort_tags boolean: if true we will only sort tags (default: false) builtin.current_buffer_tags = require_on_exported_call("telescope.builtin.files").current_buffer_tags -- @@ -154,8 +142,10 @@ builtin.current_buffer_tags = require_on_exported_call("telescope.builtin.files" --- - Default keymaps: --- - ``: opens the currently selected file ---@param opts table: options to pass to the picker ----@field show_untracked boolean: if true, adds `--others` flag to command and shows untracked files (default is true) ----@field recurse_submodules boolean: if true, adds the `--recurse-submodules` flag to command (default is false) +---@field cwd string: specify the path of the repo +---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true) +---@field show_untracked boolean: if true, adds `--others` flag to command and shows untracked files (default: true) +---@field recurse_submodules boolean: if true, adds the `--recurse-submodules` flag to command (default: false) builtin.git_files = require_on_exported_call("telescope.builtin.git").files --- Lists commits for current directory with diff preview @@ -166,6 +156,7 @@ builtin.git_files = require_on_exported_call("telescope.builtin.git").files --- - `h`: resets current branch to selected commit using hard mode ---@param opts table: options to pass to the picker ---@field cwd string: specify the path of the repo +---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true) builtin.git_commits = require_on_exported_call("telescope.builtin.git").commits --- Lists commits for current buffer with diff preview @@ -176,6 +167,7 @@ builtin.git_commits = require_on_exported_call("telescope.builtin.git").commits --- - ``: opens a diff in a new tab ---@param opts table: options to pass to the picker ---@field cwd string: specify the path of the repo +---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true) ---@field current_file string: specify the current file that should be used for bcommits (default: current buffer) builtin.git_bcommits = require_on_exported_call("telescope.builtin.git").bcommits @@ -188,6 +180,8 @@ builtin.git_bcommits = require_on_exported_call("telescope.builtin.git").bcommit --- - ``: deletes the currently selected branch, with confirmation prompt before deletion --- - ``: merges the currently selected branch, with confirmation prompt before deletion ---@param opts table: options to pass to the picker +---@field cwd string: specify the path of the repo +---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true) builtin.git_branches = require_on_exported_call("telescope.builtin.git").branches --- Lists git status for current directory @@ -195,12 +189,17 @@ builtin.git_branches = require_on_exported_call("telescope.builtin.git").branche --- - ``: stages or unstages the currently selected file --- - ``: opens the currently selected file ---@param opts table: options to pass to the picker +---@field cwd string: specify the path of the repo +---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true) +---@field git_icons table: string -> string. Matches name with icon (see source code, make_entry.lua git_icon_defaults) builtin.git_status = require_on_exported_call("telescope.builtin.git").status --- Lists stash items in current repository --- - Default keymaps: --- - ``: runs `git apply` for currently selected stash ---@param opts table: options to pass to the picker +---@field cwd string: specify the path of the repo +---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true) builtin.git_stash = require_on_exported_call("telescope.builtin.git").stash -- @@ -211,10 +210,28 @@ builtin.git_stash = require_on_exported_call("telescope.builtin.git").stash --- Lists all of the community maintained pickers built into Telescope ---@param opts table: options to pass to the picker +---@field ignore_filename boolean: dont show filenames (default: true) +---@field include_extensions boolean: if true will show the pickers of the installed extensions (default: false) builtin.builtin = require_on_exported_call("telescope.builtin.internal").builtin +--- 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| +---@param opts table: options to pass to the picker +---@field cache_index number: what picker to resume, where 1 denotes most recent (default: 1) +builtin.resume = require_on_exported_call("telescope.builtin.internal").resume + +--- Opens a picker over previously cached pickers in there preserved states (incl. multi selections) +--- - Default keymaps: +--- - ``: delete the selected cached picker +--- - Notes: +--- - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker| +---@param opts table: options to pass to the picker +builtin.pickers = require_on_exported_call("telescope.builtin.internal").pickers + --- Use the telescope... ---@param opts table: options to pass to the picker +---@field show_pluto boolean: we love pluto (default: false, because its a hidden feature) builtin.planets = require_on_exported_call("telescope.builtin.internal").planets --- Lists symbols inside of `data/telescope-sources/*.json` found in your runtime path @@ -233,14 +250,17 @@ builtin.commands = require_on_exported_call("telescope.builtin.internal").comman --- Lists items in the quickfix list, jumps to location on `` ---@param opts table: options to pass to the picker +---@field ignore_filename boolean: dont show filenames (default: true) builtin.quickfix = require_on_exported_call("telescope.builtin.internal").quickfix --- Lists items from the current window's location list, jumps to location on `` ---@param opts table: options to pass to the picker +---@field ignore_filename boolean: dont show filenames (default: true) builtin.loclist = require_on_exported_call("telescope.builtin.internal").loclist --- Lists previously open files, opens on `` ---@param opts table: options to pass to the picker +---@field only_cwd boolean: show only files in the cwd (default: false) builtin.oldfiles = require_on_exported_call("telescope.builtin.internal").oldfiles --- Lists commands that were executed recently, and reruns them on `` @@ -255,46 +275,35 @@ builtin.command_history = require_on_exported_call("telescope.builtin.internal") ---@param opts table: options to pass to the picker builtin.search_history = require_on_exported_call("telescope.builtin.internal").search_history ---- 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| ----@param opts table: options to pass to the picker ----@field cache_index number: what picker to resume, where 1 denotes most recent (default 1) -builtin.resume = require_on_exported_call("telescope.builtin.internal").resume - ---- Opens a picker over previously cached pickers in there preserved states (incl. multi selections) ---- - Default keymaps: ---- - ``: delete the selected cached picker ---- - Notes: ---- - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker| ----@param opts table: options to pass to the picker -builtin.pickers = require_on_exported_call("telescope.builtin.internal").pickers - --- Lists vim options, allows you to edit the current value on `` ---@param opts table: options to pass to the picker builtin.vim_options = require_on_exported_call("telescope.builtin.internal").vim_options --- Lists available help tags and opens a new window with the relevant help info on `` ---@param opts table: options to pass to the picker +---@field lang string: specify language (default: vim.o.helplang) +---@field fallback boolean: fallback to en if language isn't installed (default: true) builtin.help_tags = require_on_exported_call("telescope.builtin.internal").help_tags --- Lists manpage entries, opens them in a help window on `` ---@param opts table: options to pass to the picker ----@field sections table: a list of sections to search, use `{ "ALL" }` to search in all sections +---@field sections table: a list of sections to search, use `{ "ALL" }` to search in all sections (default: { "1" }) +---@field man_cmd function: that returns the man command. (Default: `apropos ""` on linux, `apropos " "` on macos) builtin.man_pages = require_on_exported_call("telescope.builtin.internal").man_pages --- Lists lua modules and reloads them on `` ---@param opts table: options to pass to the picker +---@field column_len number: define the max column len for the module name (default: dynamic, longest module name) builtin.reloader = require_on_exported_call("telescope.builtin.internal").reloader --- Lists open buffers in current neovim instance, opens selected buffer on `` ---@param opts table: options to pass to the picker ----@field show_all_buffers boolean: if true, show all buffers, including unloaded buffers (default true) ----@field ignore_current_buffer boolean: if true, don't show the current buffer in the list (default false) ----@field only_cwd boolean: if true, only show buffers in the current working directory (default false) ----@field sort_lastused boolean: Sorts current and last buffer to the top and selects the lastused (default false) ----@field sort_mru boolean: Sorts all buffers after most recent used. Not just the current and last one (default false) ----@field bufnr_width number: Defines the width of the buffer numbers in front of the filenames +---@field show_all_buffers boolean: if true, show all buffers, including unloaded buffers (default: true) +---@field ignore_current_buffer boolean: if true, don't show the current buffer in the list (default: false) +---@field only_cwd boolean: if true, only show buffers in the current working directory (default: false) +---@field sort_lastused boolean: Sorts current and last buffer to the top and selects the lastused (default: false) +---@field sort_mru boolean: Sorts all buffers after most recent used. Not just the current and last one (default: false) +---@field bufnr_width number: Defines the width of the buffer numbers in front of the filenames (default: dynamic) builtin.buffers = require_on_exported_call("telescope.builtin.internal").buffers --- Lists available colorschemes and applies them on `` @@ -334,10 +343,12 @@ builtin.spell_suggest = require_on_exported_call("telescope.builtin.internal").s --- Lists the tag stack for the current window, jumps to tag on `` ---@param opts table: options to pass to the picker +---@field ignore_filename boolean: dont show filenames (default: true) builtin.tagstack = require_on_exported_call("telescope.builtin.internal").tagstack --- Lists items from Vim's jumplist, jumps to location on `` ---@param opts table: options to pass to the picker +---@field ignore_filename boolean: dont show filenames (default: true) builtin.jumplist = require_on_exported_call("telescope.builtin.internal").jumplist -- @@ -348,52 +359,73 @@ builtin.jumplist = require_on_exported_call("telescope.builtin.internal").jumpli --- Lists LSP references for word under the cursor, jumps to reference on `` ---@param opts table: options to pass to the picker +---@field timeout number: timeout for the sync call (default: 10000) builtin.lsp_references = require_on_exported_call("telescope.builtin.lsp").references --- Goto the definition of the word under the cursor, if there's only one, otherwise show all options in Telescope ---@param opts table: options to pass to the picker +---@field timeout number: timeout for the sync call (default: 10000) ---@field jump_type string: how to goto definition if there is only one, values: "tab", "split", "vsplit", "never" +---@field ignore_filename boolean: dont show filenames (default: true) builtin.lsp_definitions = require_on_exported_call("telescope.builtin.lsp").definitions --- Goto the definition of the type of the word under the cursor, if there's only one, --- otherwise show all options in Telescope ---@param opts table: options to pass to the picker +---@field timeout number: timeout for the sync call (default: 10000) ---@field jump_type string: how to goto definition if there is only one, values: "tab", "split", "vsplit", "never" +---@field ignore_filename boolean: dont show filenames (default: true) builtin.lsp_type_definitions = require("telescope.builtin.lsp").type_definitions --- Goto the implementation of the word under the cursor if there's only one, otherwise show all options in Telescope ---@param opts table: options to pass to the picker +---@field timeout number: timeout for the sync call (default: 10000) ---@field jump_type string: how to goto implementation if there is only one, values: "tab", "split", "vsplit", "never" +---@field ignore_filename boolean: dont show filenames (default: true) builtin.lsp_implementations = require_on_exported_call("telescope.builtin.lsp").implementations --- Lists any LSP actions for the word under the cursor which can be triggered with `` ---@param opts table: options to pass to the picker +---@field timeout number: timeout for the sync call (default: 10000) builtin.lsp_code_actions = require_on_exported_call("telescope.builtin.lsp").code_actions --- Lists any LSP actions for a given range, that can be triggered with `` ---@param opts table: options to pass to the picker +---@field timeout number: timeout for the sync call (default: 10000) +---@field start_line number: where the code action starts (default: handled by :'<,'>Telescope lsp_range_code_actions) +---@field start_line number: where the code action ends (default: handled by :'<,'>Telescope lsp_range_code_actions) builtin.lsp_range_code_actions = require_on_exported_call("telescope.builtin.lsp").range_code_actions --- Lists LSP document symbols in the current buffer --- - Default keymaps: --- - ``: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`) ---@param opts table: options to pass to the picker ----@field ignore_filename type: string with file to ignore +---@field timeout number: timeout for the sync call (default: 10000) +---@field ignore_filename boolean: dont show filenames (default: true) +---@field show_line boolean: if true, shows the content of the line the tag is found on (default: false) ---@field symbols string|table: filter results by symbol kind(s) +---@field symbol_highlights table: string -> string. Matches symbol with hl_group builtin.lsp_document_symbols = require_on_exported_call("telescope.builtin.lsp").document_symbols --- Lists LSP document symbols in the current workspace --- - Default keymaps: --- - ``: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`) ---@param opts table: options to pass to the picker ----@field ignore_filename string: file(s) to ignore +---@field query string: for what to query the workspace (default: "") +---@field timeout number: timeout for the sync call (default: 10000) +---@field ignore_filename boolean: dont show filenames (default: false) +---@field show_line boolean: if true, shows the content of the line the tag is found on (default: false) ---@field symbols string|table: filter results by symbol kind(s) +---@field symbol_highlights table: string -> string. Matches symbol with hl_group builtin.lsp_workspace_symbols = require_on_exported_call("telescope.builtin.lsp").workspace_symbols --- Dynamically lists LSP for all workspace symbols --- - Default keymaps: --- - ``: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`) ---@param opts table: options to pass to the picker +---@field ignore_filename boolean: dont show filenames (default: false) +---@field show_line boolean: if true, shows the content of the line the symbol is found on (default: false) +---@field symbol_highlights table: string -> string. Matches symbol with hl_group builtin.lsp_dynamic_workspace_symbols = require_on_exported_call("telescope.builtin.lsp").dynamic_workspace_symbols --- Lists LSP diagnostics for the current buffer @@ -405,7 +437,7 @@ builtin.lsp_dynamic_workspace_symbols = require_on_exported_call("telescope.buil ---@field severity string|number: filter diagnostics by severity name (string) or id (number) ---@field severity_limit string|number: keep diagnostics equal or more severe wrt severity name (string) or id (number) ---@field severity_bound string|number: keep diagnostics equal or less severe wrt severity name (string) or id (number) ----@field no_sign bool: hide LspDiagnosticSigns from Results (default is false) +---@field no_sign boolean: hide LspDiagnosticSigns from Results (default: false) ---@field line_width number: set length of diagnostic entry text in Results builtin.lsp_document_diagnostics = require_on_exported_call("telescope.builtin.lsp").diagnostics @@ -418,7 +450,7 @@ builtin.lsp_document_diagnostics = require_on_exported_call("telescope.builtin.l ---@field severity string|number: filter diagnostics by severity name (string) or id (number) ---@field severity_limit string|number: keep diagnostics equal or more severe wrt severity name (string) or id (number) ---@field severity_bound string|number: keep diagnostics equal or less severe wrt severity name (string) or id (number) ----@field no_sign bool: hide LspDiagnosticSigns from Results (default is false) +---@field no_sign boolean: hide LspDiagnosticSigns from Results (default: false) ---@field line_width number: set length of diagnostic entry text in Results builtin.lsp_workspace_diagnostics = require_on_exported_call("telescope.builtin.lsp").workspace_diagnostics diff --git a/lua/telescope/builtin/internal.lua b/lua/telescope/builtin/internal.lua index cbacf97..ae3b10e 100644 --- a/lua/telescope/builtin/internal.lua +++ b/lua/telescope/builtin/internal.lua @@ -635,7 +635,7 @@ internal.reloader = function(opts) local package_list = vim.tbl_keys(package.loaded) -- filter out packages we don't want and track the longest package name - opts.column_len = 0 + local column_len = 0 for index, module_name in pairs(package_list) do if type(require(module_name)) ~= "table" @@ -643,10 +643,11 @@ internal.reloader = function(opts) or package.searchpath(module_name, package.path) == nil then table.remove(package_list, index) - elseif #module_name > opts.column_len then - opts.column_len = #module_name + elseif #module_name > column_len then + column_len = #module_name end end + opts.column_len = vim.F.if_nil(opts.column_len, column_len) pickers.new(opts, { prompt_title = "Packages", diff --git a/lua/telescope/command.lua b/lua/telescope/command.lua index db75eb1..f75fdeb 100644 --- a/lua/telescope/command.lua +++ b/lua/telescope/command.lua @@ -166,7 +166,8 @@ local function run_command(args) end if string.len(theme) > 0 then - opts = themes[theme](opts) + local func = themes[theme] or themes["get_" .. theme] + opts = func(opts) end if string.len(extension_type) > 0 and extension_type ~= '"' then diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua index c66278f..406d3c6 100644 --- a/lua/telescope/config.lua +++ b/lua/telescope/config.lua @@ -120,191 +120,247 @@ local layout_config_description = string.format( -- - first entry is the value -- - second entry is the description of the option -local telescope_defaults = { +local telescope_defaults = {} +config.descriptions_order = {} +local append = function(name, val, doc) + telescope_defaults[name] = { val, doc } + table.insert(config.descriptions_order, name) +end - sorting_strategy = { - "descending", - [[ - Determines the direction "better" results are sorted towards. +append( + "sorting_strategy", + "descending", + [[ + Determines the direction "better" results are sorted towards. - Available options are: - - "descending" (default) - - "ascending"]], - }, + Available options are: + - "descending" (default) + - "ascending"]] +) - selection_strategy = { - "reset", - [[ - Determines how the cursor acts after each sort iteration. +append( + "selection_strategy", + "reset", + [[ + Determines how the cursor acts after each sort iteration. - Available options are: - - "reset" (default) - - "follow" - - "row" - - "closest"]], - }, + Available options are: + - "reset" (default) + - "follow" + - "row" + - "closest"]] +) - scroll_strategy = { - "cycle", - [[ - Determines what happens you try to scroll past view of the picker. +append( + "scroll_strategy", + "cycle", + [[ + Determines what happens if you try to scroll past the view of the + picker. - Available options are: - - "cycle" (default) - - "limit"]], - }, + Available options are: + - "cycle" (default) + - "limit"]] +) - layout_strategy = { - "horizontal", - [[ - Determines the default layout of Telescope pickers. - See |telescope.layout| for details of the available strategies. +append( + "layout_strategy", + "horizontal", + [[ + Determines the default layout of Telescope pickers. + See |telescope.layout| for details of the available strategies. - Default: 'horizontal']], - }, + Default: 'horizontal']] +) - layout_config = { layout_config_defaults, layout_config_description }, +append("layout_config", layout_config_defaults, layout_config_description) - winblend = { 0 }, +append( + "winblend", + 0, + [[ + Configure winblend for telescope floating windows. See |winblend| for + more information. - prompt_prefix = { "> ", [[ - Will be shown in front of the prompt. + Default: 0]] +) - Default: '> ']] }, +append( + "prompt_prefix", + "> ", + [[ + The character(s) that will be shown in front of Telescope's prompt. - selection_caret = { "> ", [[ - Will be shown in front of the selection. + Default: '> ']] +) - Default: '> ']] }, +append( + "selection_caret", + "> ", + [[ + The character(s) that will be shown in front of the current selection. - entry_prefix = { - " ", - [[ - Prefix in front of each result entry. Current selection not included. - Default: ' ']], - }, + Default: '> ']] +) - initial_mode = { "insert" }, +append( + "entry_prefix", + " ", + [[ + Prefix in front of each result entry. Current selection not included. - border = { true, [[ - Boolean defining if borders are added to Telescope windows. + Default: ' ']] +) - Default: true]] }, +append( + "initial_mode", + "insert", + [[ + Determines in which mode telescope starts. Valid Keys: + `insert` and `normal`. - path_display = { - {}, - [[ - Determines how file paths are displayed + Default: "insert"]] +) - 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 +append( + "border", + true, + [[ + Boolean defining if borders are added to Telescope windows. - 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` + Default: true]] +) - path_display can also be set to 'hidden' string to hide file names +append( + "path_display", + {}, + [[ + Determines how file paths are displayed - path_display can also be set to a function for custom formatting of - the path display. Example: + 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 - -- 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, + 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` - Default: {}]], - }, + path_display can also be set to 'hidden' string to hide file names - borderchars = { { "─", "│", "─", "│", "╭", "╮", "╯", "╰" } }, + path_display can also be set to a function for custom formatting of + the path display. Example: - get_status_text = { - function(self, opts) - local xx = (self.stats.processed or 0) - (self.stats.filtered or 0) - local yy = self.stats.processed or 0 - if xx == 0 and yy == 0 then - return "" - end + -- 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, - -- local status_icon - -- if opts.completed then - -- status_icon = "✔️" - -- else - -- status_icon = "*" - -- end + Default: {}]] +) - return string.format("%s / %s ", xx, yy) +append( + "borderchars", + { "─", "│", "─", "│", "╭", "╮", "╯", "╰" }, + [[ + Set the borderchars of telescope floating windows. It has to be a + table of 8 string values. + + Default: { "─", "│", "─", "│", "╭", "╮", "╯", "╰" }]] +) + +append( + "get_status_text", + function(self) + local xx = (self.stats.processed or 0) - (self.stats.filtered or 0) + local yy = self.stats.processed or 0 + if xx == 0 and yy == 0 then + return "" + end + + -- local status_icon + -- if opts.completed then + -- status_icon = "✔️" + -- else + -- status_icon = "*" + -- end + return string.format("%s / %s", xx, yy) + end, + [[ + A function that determines what the virtual text looks like. + Signature: function(picker) -> str + + Default: function that shows current count / all]] +) + +append( + "dynamic_preview_title", + false, + [[ + 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]] +) + +append( + "history", + { + path = vim.fn.stdpath "data" .. os_sep .. "telescope_history", + limit = 100, + handler = function(...) + return require("telescope.actions.history").get_simple_history(...) end, }, + [[ + 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. - dynamic_preview_title = { - false, - [[ - Will change the title of the preview window dynamically, where it - is supported. Means the preview window will for example show the - full filename. - - Default: false]], - }, - - history = { - { - path = vim.fn.stdpath "data" .. os_sep .. "telescope_history", - limit = 100, - handler = function(...) - return require("telescope.actions.history").get_simple_history(...) - end, - }, - [[ - 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 = { - [""] = require('telescope.actions').cycle_history_next, - [""] = require('telescope.actions').cycle_history_prev, - }, + Currently mappings still need to be added, Example: + mappings = { + i = { + [""] = require('telescope.actions').cycle_history_next, + [""] = 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 - ]], - }, - - cache_picker = { - { - num_pickers = 1, - limit_entries = 1000, }, - [[ + + 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]] +) + +append( + "cache_picker", + { + num_pickers = 1, + limit_entries = 1000, + }, + [[ 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. @@ -323,117 +379,239 @@ local telescope_defaults = { Default: 1 - limit_entries: The amount of entries that will be written in the Default: 1000 - ]], - }, + ]] +) - -- Builtin configuration +append( + "vimgrep_arguments", + { "rg", "--color=never", "--no-heading", "--with-filename", "--line-number", "--column", "--smart-case" }, + [[ + 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. - -- List that will be executed. - -- Last argument will be the search term (passed in during execution) - vimgrep_arguments = { - { "rg", "--color=never", "--no-heading", "--with-filename", "--line-number", "--column", "--smart-case" }, - }, + Default: { + "rg", + "--color=never", + "--no-heading", + "--with-filename", + "--line-number", + "--column", + "--smart-case" + }]] +) - use_less = { true }, +append( + "use_less", + true, + [[ + Boolean if less should be enabled in term_previewer (deprecated and + currently no longer used in the builtin pickers). - color_devicons = { true }, + Default: true]] +) - set_env = { nil }, +append( + "set_env", + nil, + [[ + Set an environment for term_previewer. A table of key values: + Example: { COLORTERM = "truecolor", ... } + Hint: Empty table is not allowed. + + Default: nil]] +) + +append( + "color_devicons", + true, + [[ + Boolean if devicons should be enabled or not. + Hint: Coloring only works if |termguicolors| is enabled. + + Default: true]] +) + +append( + "mappings", + {}, + [[ + Your mappings to override telescope's default mappings. + + Format is: + { + mode = { ..keys } + } + + where {mode} is the one character letter for a mode + ('i' for insert, 'n' for normal). + + For example: mappings = { - {}, - [[ - Your mappings to override telescope's default mappings. + i = { + [""] = require('telescope.actions').close, + }, + } - Format is: - { - mode = { ..keys } - } - where {mode} is the one character letter for a mode - ('i' for insert, 'n' for normal). + To disable a keymap, put [map] = false + So, to not map "", just put + ..., + [""] = false, + ..., + + Into your config. + + + otherwise, just set the mapping to the function that you want it to + be. + + ..., + [""] = require('telescope.actions').select_default, + ..., + + If the function you want is part of `telescope.actions`, then you can + simply give a string. + For example, the previous option is equivalent to: + + ..., + [""] = "select_default", + ..., + + You can also add other mappings using tables with `type = "command"`. For example: - mappings = { - i = { - [""] = require('telescope.actions').close, - }, - } + ..., + ["jj"] = { "", type = "command" }, + ["kk"] = { "echo \"Hello, World!\"", type = "command" },) + ..., + ]] +) +append( + "default_mappings", + nil, + [[ + Not recommended to use except for advanced users. - To disable a keymap, put [map] = false - So, to not map "", just put + Will allow you to completely remove all of telescope's default maps + and use your own. + ]] +) - ..., - [""] = false, - ..., +append( + "file_sorter", + sorters.get_fzy_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. - Into your config. + Default: require("telescope.sorters").get_fzy_sorter]] +) +append( + "generic_sorter", + sorters.get_fzy_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. - otherwise, just set the mapping to the function that you want it to - be. + Default: require("telescope.sorters").get_fzy_sorter]] +) - ..., - [""] = require('telescope.actions').select_default, - ..., +--TODO(conni2461): Why is this even configurable??? +append( + "prefilter_sorter", + sorters.prefilter, + [[ + 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 - If the function you want is part of `telescope.actions`, then you can - simply give a string. - For example, the previous option is equivalent to: + Default: require("telescope.sorters").prefilter]] +) - ..., - [""] = "select_default", - ..., +append( + "file_ignore_patterns", + nil, + [[ + 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 - You can also add other mappings using tables with `type = "command"`. - For example: + Default: nil]] +) - ..., - ["jj"] = { "", type = "command" }, - ["kk"] = { "echo \"Hello, World!\"", type = "command" },) - ..., - ]], - }, +append( + "file_previewer", + function(...) + return require("telescope.previewers").vim_buffer_cat.new(...) + end, + [[ + 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_mappings = { - nil, - [[ - Not recommended to use except for advanced users. + Default: require("telescope.previewers").vim_buffer_cat.new]] +) - Will allow you to completely remove all of telescope's default maps - and use your own. - ]], - }, +append( + "grep_previewer", + function(...) + return require("telescope.previewers").vim_buffer_vimgrep.new(...) + end, + [[ + 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 - generic_sorter = { sorters.get_generic_fuzzy_sorter }, - prefilter_sorter = { sorters.prefilter }, - file_sorter = { sorters.get_fuzzy_file }, + Default: require("telescope.previewers").vim_buffer_vimgrep.new]] +) - file_ignore_patterns = { nil }, +append( + "qflist_previewer", + function(...) + return require("telescope.previewers").vim_buffer_qflist.new(...) + end, + [[ + 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 - file_previewer = { - function(...) - return require("telescope.previewers").vim_buffer_cat.new(...) - end, - }, - grep_previewer = { - function(...) - return require("telescope.previewers").vim_buffer_vimgrep.new(...) - end, - }, - qflist_previewer = { - function(...) - return require("telescope.previewers").vim_buffer_qflist.new(...) - end, - }, - buffer_previewer_maker = { - function(...) - return require("telescope.previewers").buffer_previewer_maker(...) - end, - }, -} + Default: require("telescope.previewers").vim_buffer_vimgrep.new]] +) + +append( + "buffer_previewer_maker", + function(...) + return require("telescope.previewers").buffer_previewer_maker(...) + end, + [[ + 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]] +) -- @param user_defaults table: a table where keys are the names of options, -- and values are the ones the user wants @@ -470,8 +648,7 @@ function config.set_defaults(user_defaults, tele_defaults) end local function set(name, default_val, description) - -- TODO(doc): Once we have descriptions for all of these, then we can add this back in. - -- assert(description, "Config values must always have a description") + assert(description, "Config values must always have a description") config.values[name] = get(name, default_val) if description then diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua index 7a740a3..d52d60d 100644 --- a/lua/telescope/init.lua +++ b/lua/telescope/init.lua @@ -2,6 +2,7 @@ local _extensions = require "telescope._extensions" local telescope = {} +-- TODO(conni2461): also table of contents for tree-sitter-lua -- TODO: Add pre to the works -- ---@pre [[ -- ---@pre ]] @@ -10,22 +11,68 @@ local telescope = {} --- 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
 ---
---@brief ]] ---@tag telescope.nvim ---- Setup function to be run by user. Configures the defaults, extensions ---- and other aspects of telescope. ----@param opts table: Configuration opts. Keys: defaults, extensions +--- Setup function to be run by user. Configures the defaults, pickers and +--- extensions of telescope. +--- +--- 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 +--- } +--- } +--- +---@param opts table: Configuration opts. Keys: defaults, pickers, extensions ---@eval { ["description"] = require('telescope').__format_setup_keys() } function telescope.setup(opts) opts = opts or {} @@ -56,11 +103,9 @@ end telescope.extensions = require("telescope._extensions").manager telescope.__format_setup_keys = function() + local names = require("telescope.config").descriptions_order local descriptions = require("telescope.config").descriptions - local names = vim.tbl_keys(descriptions) - table.sort(names) - local result = { "
", "", "Valid keys for {opts.defaults}" }
   for _, name in ipairs(names) do
     local desc = descriptions[name]
diff --git a/lua/telescope/make_entry.lua b/lua/telescope/make_entry.lua
index beb7e18..bf0287c 100644
--- a/lua/telescope/make_entry.lua
+++ b/lua/telescope/make_entry.lua
@@ -61,7 +61,7 @@ do
   function make_entry.gen_from_file(opts)
     opts = opts or {}
 
-    local cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd())
+    local cwd = vim.fn.expand(opts.cwd or vim.loop.cwd())
 
     local disable_devicons = opts.disable_devicons
 
@@ -181,7 +181,7 @@ do
     local display_string = "%s:%s%s"
 
     mt_vimgrep_entry = {
-      cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd()),
+      cwd = vim.fn.expand(opts.cwd or vim.loop.cwd()),
 
       display = function(entry)
         local display_filename = utils.transform_path(opts, entry.filename)
@@ -428,7 +428,7 @@ function make_entry.gen_from_buffer(opts)
     },
   }
 
-  local cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd())
+  local cwd = vim.fn.expand(opts.cwd or vim.loop.cwd())
 
   local make_display = function(entry)
     local display_bufname = utils.transform_path(opts, entry.filename)
@@ -842,7 +842,7 @@ end
 function make_entry.gen_from_ctags(opts)
   opts = opts or {}
 
-  local cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd())
+  local cwd = vim.fn.expand(opts.cwd or vim.loop.cwd())
   local current_file = Path:new(vim.fn.expand "%"):normalize(cwd)
 
   local display_items = {
diff --git a/lua/telescope/pickers.lua b/lua/telescope/pickers.lua
index 1c0ce67..624ab00 100644
--- a/lua/telescope/pickers.lua
+++ b/lua/telescope/pickers.lua
@@ -538,14 +538,14 @@ end
 --- such as deleting buffers or files.
 ---
 --- Example usage:
---- 
+--- 
 --- actions.delete_something = function(prompt_bufnr)
 ---    local current_picker = action_state.get_current_picker(prompt_bufnr)
 ---    current_picker:delete_selection(function(selection)
 ---      -- delete the selection outside of telescope
 ---    end)
 --- end
---- 

+--- 
 ---
 --- Example usage in telescope:
 ---   - `actions.delete_buffer()`
diff --git a/lua/telescope/pickers/layout_strategies.lua b/lua/telescope/pickers/layout_strategies.lua
index b97888a..c703d4f 100644
--- a/lua/telescope/pickers/layout_strategies.lua
+++ b/lua/telescope/pickers/layout_strategies.lua
@@ -6,7 +6,7 @@
 ---
 --- All layout strategies are functions with the following signature:
 ---
---- 
+--- 
 ---   function(picker, columns, lines, layout_config)
 ---     -- Do some calculations here...
 ---     return {
@@ -15,7 +15,9 @@
 ---       prompt = prompt_configuration,
 ---     }
 ---   end
+--- 
 ---
+--- 
 ---   Parameters: ~
 ---     - picker        : A Picker object. (docs coming soon)
 ---     - columns       : (number) Columns in the vim window
diff --git a/lua/telescope/previewers/init.lua b/lua/telescope/previewers/init.lua
index b749056..0051fff 100644
--- a/lua/telescope/previewers/init.lua
+++ b/lua/telescope/previewers/init.lua
@@ -77,11 +77,11 @@ end
 --- 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"
@@ -219,12 +219,12 @@ previewers.qflist = term_previewer.qflist
 ---     - `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`
diff --git a/lua/telescope/themes.lua b/lua/telescope/themes.lua
index 1cd2efe..301fa37 100644
--- a/lua/telescope/themes.lua
+++ b/lua/telescope/themes.lua
@@ -15,14 +15,13 @@
 local themes = {}
 
 --- Dropdown style theme.
---- 
 ---
 --- Usage:
----
+--- 
 ---     `local builtin = require('telescope.builtin')`
 ---     `local themes = require('telescope.themes')`
 ---     `builtin.find_files(themes.get_dropdown())`
---- 

+--- 
 function themes.get_dropdown(opts)
   opts = opts or {}
 
@@ -59,14 +58,14 @@ function themes.get_dropdown(opts)
 end
 
 --- Cursor style theme.
---- 
 ---
 --- Usage:
+--- 
 ---
 ---     `local builtin = require('telescope.builtin')`
 ---     `local themes = require('telescope.themes')`
 ---     `builtin.lsp_code_actions(themes.get_cursor())`
---- 

+--- 
 function themes.get_cursor(opts)
   opts = opts or {}
 
@@ -97,14 +96,13 @@ function themes.get_cursor(opts)
 end
 
 --- Ivy style theme.
---- 
 ---
 --- Usage:
----
+--- 
 ---     `local builtin = require('telescope.builtin')`
 ---     `local themes = require('telescope.themes')`
 ---     `builtin.find_files(themes.get_ivy())`
---- 

+--- 
 function themes.get_ivy(opts)
   opts = opts or {}