summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--.github/ISSUE_TEMPLATE/bug_report.yml18
-rw-r--r--LICENSE2
-rw-r--r--README.md678
-rw-r--r--developers.md312
-rw-r--r--doc/telescope.txt951
-rw-r--r--lua/telescope/actions/generate.lua4
-rw-r--r--lua/telescope/actions/utils.lua54
-rw-r--r--lua/telescope/builtin/init.lua190
-rw-r--r--lua/telescope/builtin/internal.lua7
-rw-r--r--lua/telescope/command.lua3
-rw-r--r--lua/telescope/config.lua643
-rw-r--r--lua/telescope/init.lua57
-rw-r--r--lua/telescope/make_entry.lua8
-rw-r--r--lua/telescope/pickers.lua4
-rw-r--r--lua/telescope/pickers/layout_strategies.lua4
-rw-r--r--lua/telescope/previewers/init.lua8
-rw-r--r--lua/telescope/themes.lua14
17 files changed, 1807 insertions, 1150 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
@@ -30,6 +30,24 @@ body:
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"
description: "Steps to reproduce using the minimal config provided below."
placeholder: |
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)
-<sub>For more showcases of Telescope, please visit the [Showcase section](https://github.com/nvim-telescope/telescope.nvim/wiki/Showcase) in the Telescope Wiki</sub>
-
-<!-- You can read this documentation from start to finish, or you can look at the -->
-<!-- outline and directly jump to the section that interests you most. -->
+<sub>For more showcases of Telescope, please visit the [Showcase
+section](https://github.com/nvim-telescope/telescope.nvim/wiki/Showcase) in the
+Telescope Wiki</sub>
## 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<cr>`
@@ -104,7 +115,7 @@ nnoremap <leader>fb <cmd>lua require('telescope.builtin').buffers()<cr>
nnoremap <leader>fh <cmd>lua require('telescope.builtin').help_tags()<cr>
```
-See [built-in pickers](#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.
-
-### Telescope Defaults
+- **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.
-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
```
-<!-- TODO: move some options to Options affecting behavior -->
-
-### 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 = {
- ["<c-d>"] = require("telescope.actions").delete_buffer,
- -- Right hand side can also be the name of the action as a string
- ["<c-d>"] = "delete_buffer",
- },
- n = {
- ["<c-d>"] = 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 |
-|----------------|--------------------------------------------------------------|
-| `<C-n>/<Down>` | Next item |
-| `<C-p>/<Up>` | Previous item |
-| `j/k` | Next/previous (in normal mode) |
-| `<cr>` | Confirm selection |
-| `<C-q>` | Confirm selection and open quickfix window |
-| `<C-x>` | Go to file selection as a split |
-| `<C-v>` | Go to file selection as a vsplit |
-| `<C-t>` | Go to a file in a new tab |
-| `<C-u>` | Scroll up in preview window |
-| `<C-d>` | Scroll down in preview window |
+| Mappings | Action |
+|----------------|---------------------------------------------|
+| `<C-n>/<Down>` | Next item |
+| `<C-p>/<Up>` | Previous item |
+| `j/k` | Next/previous (in normal mode) |
+| `H/M/L` | Select High/Middle/Low (in normal mode) |
+| `<CR>` | Confirm selection |
+| `<C-x>` | Go to file selection as a split |
+| `<C-v>` | Go to file selection as a vsplit |
+| `<C-t>` | Go to a file in a new tab |
+| `<C-u>` | Scroll up in preview window |
+| `<C-d>` | Scroll down in preview window |
| `<C-/>/?` | Show picker mappings (in insert & normal mode, respectively) |
-| `<C-c>` | Close telescope |
-| `<Esc>` | Close telescope (in normal mode) |
+| `<C-c>` | Close telescope |
+| `<Esc>` | Close telescope (in normal mode) |
+| `<Tab>` | Toggle selection and move to next selection |
+| `<S-Tab>` | Toggle selection and move to prev selection |
+| `<C-q>` | Send all items not filtered to qflist |
+| `<M-q>` | Send all selected items to qflist |
-To see the full list of mappings, check out `lua/telescope/mappings.lua` and
-the `default_mappings` table.
+To see the full list of mappings, check out `lua/telescope/mappings.lua` and the
+`default_mappings` table.
-Much like [built-in pickers](#pickers), there are a number of
+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:
-<!-- TODO: add custom action in addition to a function that gets ran after a given 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 "<C-n>", just put
- ["<C-n>"] = false,
-
- -- Otherwise, just set the mapping to the function that you want it to be.
- ["<C-i>"] = actions.select_horizontal,
-
- -- Add up multiple actions
- ["<cr>"] = actions.select_default + actions.center,
-
- -- You can perform as many actions in a row as you like
- ["<cr>"] = actions.select_default + actions.center + my_cool_custom_action,
- },
- n = {
- ["<esc>"] = actions.close,
- ["<C-i>"] = my_cool_custom_action,
- },
- },
- }
-}
-```
-
-For a [picker](#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', '<c-d>', actions.git_delete_branch) -- this action already exist
- map('n', '<c-d>', actions.git_delete_branch) -- this action already exist
- -- For more actions look at lua/telescope/actions/init.lua
- return true
-end})
-```
-
-For more info, see [./developers.md](./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 `<C-l>` to get an autocomplete menu
-filled with all of the possible filters you can use.
-
-I.e. while using the `lsp_document_symbols` picker, adding `:methods:` to your query filters out any
-document 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,11 +362,44 @@ 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`.
-<!-- TODO review -->
-<!-- - Currently, it's not possible to delay calling the `Sorter` until the end of the execution, it is called on each item as we receive them. -->
-<!-- - This was done this way so that long running / expensive searches can be instantly searchable and we don't have to wait til it completes for things to start being worked on. -->
-<!-- - However, this prevents using some tools, like FZF easily. -->
-<!-- - In the future, I'll probably add a mode where you can delay the sorting til the end, so you can use more traditional sorting tools. -->
+## 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.
+For example, if we wanted to set the `width` of a picker using the `vertical`
+layout strategy to 50% of the screen width, we would specify that width
+as `0.5`, but if we wanted to specify the `width` to be exactly 80
+characters wide, we would specify it as `80`.
+For more details on resolving sizes, see `:help telescope.resolve`.
+
+As an example, if we wanted to specify the layout strategy and width,
+but only for this instance, we could do something like:
+
+```
+:lua require('telescope.builtin').find_files({layout_strategy='vertical',layout_config={width=0.5}})
+```
+
+If we wanted to change the width for every time we use the `vertical`
+layout strategy, we could add the following to our `setup()` call:
+
+```lua
+require('telescope').setup({
+ defaults = {
+ layout_config = {
+ vertical = { width = 0.5 }
+ -- other layout configuration here
+ },
+ -- other defaults configuration here
+ },
+ -- other configuration values here
+})
+```
## Themes
@@ -550,10 +411,10 @@ We have some built in themes but are looking for more cool options.
| 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_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:
+To use a theme, simply append it to a builtin function:
```vim
nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({}))<cr>
@@ -564,11 +425,55 @@ nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope
Or use with a command:
```vim
-Telescope find_files theme=get_dropdown
+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,
+tab completions and setting options.
+
+```viml
+" Show all builtin pickers
+:Telescope
+
+" Tab completion
+:Telescope |<tab>
+:Telescope find_files
+
+" Setting options
+:Telescope find_files prompt_prefix=🔍
+
+" 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=🔍
```
-Themes should work with every `telescope.builtin` function. If you wish to make a theme,
-check out `lua/telescope/themes.lua`.
+for more information and how to realize more complex commands please read
+`:help telescope.command`.
## Autocmds
@@ -581,28 +486,35 @@ Telescope user autocmds:
## Extensions
-Telescope provides the capabilities to create & register extensions, which improve telescope in a
-variety of ways.
+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.
-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.
+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:
+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.
+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:
+Pickers from extensions are added to the `:Telescope` command under their
+respective name. For example:
```viml
" Run the `configurations` picker from nvim-dap
@@ -616,129 +528,10 @@ They can also be called directly from Lua:
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
-<!-- TODO: need to provide working examples for every api -->
-
-### Finders
-<!-- TODO what is 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
-<!-- TODO: this section need some love, an in-depth explanation will be appreciated it need some in depth explanation -->
-<!-- TODO what is pickers -->
-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 "<cr>" in insert mode to the function, actions.set_command_line
- map('i', '<cr>', actions.set_command_line)
-
- -- If the return value of `attach_mappings` is true, then the other
- -- default mappings are still applies.
- --
- -- Return false if you don't want any other mappings applied.
- --
- -- A return value _must_ be returned. It is an error to not return anything.
- return true
- end,
- }):find()
-end
-```
-
-### Layout (display)
-<!-- TODO need some work -->
-
-Layout can be configured by choosing a specific `layout_strategy` and
-specifying a particular `layout_config` for that strategy.
-For more details on available strategies and configuration options,
-see `:help telescope.layout`.
-
-Some options for configuring sizes in layouts are "resolvable".
-This means that they can take different forms, and will be interpreted differently according
-to which form they take.
-For example, if we wanted to set the `width` of a picker using the `vertical`
-layout strategy to 50% of the screen width, we would specify that width
-as `0.5`, but if we wanted to specify the `width` to be exactly 80
-characters wide, we would specify it as `80`.
-For more details on resolving sizes, see `:help telescope.resolve`.
-
-As an example, if we wanted to specify the layout strategy and width,
-but only for this instance, we could do something like:
-
-```
-:lua require('telescope.builtin').find_files({layout_strategy='vertical',layout_config={width=0.5}})
-```
-
-If we wanted to change the width for every time we use the `vertical`
-layout strategy, we could add the following to our `setup()` call:
-
-```lua
-require('telescope').setup({
- defaults = {
- layout_config = {
- vertical = { width = 0.5 }
- -- other layout configuration here
- },
- -- other defaults configuration here
- },
- -- other configuration values here
-})
-```
-## Vim Commands
-
-All `telescope.nvim` functions are wrapped in `vim` commands for easy access,
-tab completions and setting options.
-
-```viml
-" Show all builtin pickers
-:Telescope
-
-" Tab completion
-:Telescope |<tab>
-:Telescope find_files
-
-" Setting options
-:Telescope find_files prompt_prefix=🔍
-
-" If option is table type in Lua code, you can use `,` to connect each command string, e.g.:
-" find_command,vimgrep_arguments are both table type. So configure it on command-line like so:
-:Telescope find_files find_command=rg,--ignore,--hidden,--files prompt_prefix=🔍
-```
+For writing your own picker and for information about the API please read the
+[Developers Documentation](developers.md).
## Media
@@ -746,53 +539,6 @@ tab completions and setting options.
- [More advanced configuration (Video)](https://www.twitch.tv/videos/756229115)
- [Example video](https://www.youtube.com/watch?v=65AVwHZflsU)
-## FAQ
-<!-- Any question answered in issues should be written here -->
-
-### 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.
-<!-- TODO: insert a list of available options like previewer and prompt prefix -->
-
-```lua
--- Disable preview for find_files
-nnoremap <leader>ff :lua require('telescope.builtin').find_files({previewer = false})<cr>
-
--- Change prompt prefix for find_files builtin function:
-nnoremap <leader>fg :lua require('telescope.builtin').live_grep({ prompt_prefix="🔍" })<cr>
-nnoremap <leader>fg :Telescope live_grep prompt_prefix=🔍<cr>
-```
-
-### How to change Telescope Highlights group?
-
-There are 10 highlight groups you can play around with in order to meet your needs:
-
-```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 `<CR>` 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 `<CR>`
+(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
+<!-- TODO what is 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.
-
-
- Valid keys for {opts.defaults}
-
- *telescope.defaults.border*
- border: ~
- Boolean defining if borders are added to Telescope windows.
-
- Default: true
-
- *telescope.defaults.cache_picker*
- cache_picker: ~
- This field handles the configuration for picker caching.
- By default it is a table, with default values (more below).
- To disable caching, set it to false.
-
- Caching preserves all previous multi selections and results and
- therefore may result in slowdown or increased RAM occupation
- if too many pickers (`cache_picker.num_pickers`) or entries
- ('cache_picker.limit_entries`) are cached.
-
- Fields:
- - num_pickers: The number of pickers to be cached.
- Set to -1 to preserve all pickers of your session.
- If passed to a picker, the cached pickers with
- indices larger than `cache_picker.num_pickers` will
- be cleared.
- Default: 1
- - limit_entries: The amount of entries that will be written in the
- Default: 1000
-
+ Setup function to be run by user. Configures the defaults, pickers and
+ extensions of telescope.
- *telescope.defaults.default_mappings*
- default_mappings: ~
- Not recommended to use except for advanced users.
+ Usage:
+ >
+ require('telescope').setup{
+ defaults = {
+ -- Default configuration for telescope goes here:
+ -- config_key = value,
+ -- ..
+ },
+ pickers = {
+ -- Default configuration for builtin pickers goes here:
+ -- picker_name = {
+ -- picker_config_key = value,
+ -- ...
+ -- }
+ -- Now the picker_config_key will be applied every time you call this
+ -- builtin picker
+ },
+ extensions = {
+ -- Your extension configuration goes here:
+ -- extension_name = {
+ -- extension_config_key = value,
+ -- }
+ -- please take a look at the readme of the extension you want to configure
+ }
+ }
+<
- Will allow you to completely remove all of telescope's default maps
- and use your own.
+ Valid keys for {opts.defaults}
- *telescope.defaults.dynamic_preview_title*
- dynamic_preview_title: ~
- Will change the title of the preview window dynamically, where it
- is supported. Means the preview window will for example show the
- full filename.
+ *telescope.defaults.sorting_strategy*
+ sorting_strategy: ~
+ Determines the direction "better" results are sorted towards.
- Default: false
+ Available options are:
+ - "descending" (default)
+ - "ascending"
- *telescope.defaults.entry_prefix*
- entry_prefix: ~
- Prefix in front of each result entry. Current selection not included.
+ *telescope.defaults.selection_strategy*
+ selection_strategy: ~
+ Determines how the cursor acts after each sort iteration.
- Default: ' '
+ Available options are:
+ - "reset" (default)
+ - "follow"
+ - "row"
+ - "closest"
- *telescope.defaults.history*
- history: ~
- This field handles the configuration for prompt history.
- By default it is a table, with default values (more below).
- To disable history, set it to false.
-
- Currently mappings still need to be added, Example:
- mappings = {
- i = {
- ["<C-Down>"] = require('telescope.actions').cycle_history_next,
- ["<C-Up>"] = require('telescope.actions').cycle_history_prev,
- },
- },
+ *telescope.defaults.scroll_strategy*
+ scroll_strategy: ~
+ Determines what happens if you try to scroll past the view of the
+ picker.
- Fields:
- - path: The path to the telescope history as string.
- default: stdpath("data")/telescope_history
- - limit: The amount of entries that will be written in the
- history.
- Warning: If limit is set to nil it will grown unbound.
- default: 100
- - handler: A lua function that implements the history.
- This is meant as a developer setting for extensions to
- override the history handling, e.g.,
- https://github.com/nvim-telescope/telescope-smart-history.nvim,
- which allows context sensitive (cwd + picker) history.
+ Available options are:
+ - "cycle" (default)
+ - "limit"
- Default:
- require('telescope.actions.history').get_simple_history
+ *telescope.defaults.layout_strategy*
+ layout_strategy: ~
+ Determines the default layout of Telescope pickers.
+ See |telescope.layout| for details of the available strategies.
+ Default: 'horizontal'
*telescope.defaults.layout_config*
layout_config: ~
@@ -131,12 +131,195 @@ telescope.setup({opts}) *telescope.setup()*
}
- *telescope.defaults.layout_strategy*
- layout_strategy: ~
- Determines the default layout of Telescope pickers.
- See |telescope.layout| for details of the available strategies.
+ *telescope.defaults.winblend*
+ winblend: ~
+ Configure winblend for telescope floating windows. See |winblend| for
+ more information.
- Default: 'horizontal'
+ Default: 0
+
+ *telescope.defaults.prompt_prefix*
+ prompt_prefix: ~
+ The character(s) that will be shown in front of Telescope's prompt.
+
+ Default: '> '
+
+ *telescope.defaults.selection_caret*
+ selection_caret: ~
+ The character(s) that will be shown in front of the current selection.
+
+
+ Default: '> '
+
+ *telescope.defaults.entry_prefix*
+ entry_prefix: ~
+ Prefix in front of each result entry. Current selection not included.
+
+ Default: ' '
+
+ *telescope.defaults.initial_mode*
+ initial_mode: ~
+ Determines in which mode telescope starts. Valid Keys:
+ `insert` and `normal`.
+
+ Default: "insert"
+
+ *telescope.defaults.border*
+ border: ~
+ Boolean defining if borders are added to Telescope windows.
+
+ Default: true
+
+ *telescope.defaults.path_display*
+ path_display: ~
+ Determines how file paths are displayed
+
+ path_display can be set to an array with a combination of:
+ - "hidden" hide file names
+ - "tail" only display the file name, and not the path
+ - "absolute" display absolute paths
+ - "smart" remove as much from the path as possible to only show
+ the difference between the displayed paths
+ - "shorten" only display the first character of each directory in
+ the path
+
+ You can also specify the number of characters of each directory name
+ to keep by setting `path_display.shorten = num`.
+ e.g. for a path like
+ `alpha/beta/gamma/delta.txt`
+ setting `path_display.shorten = 1` will give a path like:
+ `a/b/g/delta.txt`
+ Similarly, `path_display.shorten = 2` will give a path like:
+ `al/be/ga/delta.txt`
+
+ path_display can also be set to 'hidden' string to hide file names
+
+ path_display can also be set to a function for custom formatting of
+ the path display. Example:
+
+ -- Format path as "file.txt (path\to\file\)"
+ path_display = function(opts, path)
+ local tail = require("telescope.utils").path_tail(path)
+ return string.format("%s (%s)", tail, path)
+ end,
+
+ Default: {}
+
+ *telescope.defaults.borderchars*
+ borderchars: ~
+ Set the borderchars of telescope floating windows. It has to be a
+ table of 8 string values.
+
+ Default: { "─", "│", "─", "│", "╭", "╮", "╯", "╰" }
+
+ *telescope.defaults.get_status_text*
+ get_status_text: ~
+ A function that determines what the virtual text looks like.
+ Signature: function(picker) -> str
+
+ Default: function that shows current count / all
+
+ *telescope.defaults.dynamic_preview_title*
+ dynamic_preview_title: ~
+ Will change the title of the preview window dynamically, where it
+ is supported. For example, the preview window's title could show up as
+ the full filename.
+
+ Default: false
+
+ *telescope.defaults.history*
+ history: ~
+ This field handles the configuration for prompt history.
+ By default it is a table, with default values (more below).
+ To disable history, set it to false.
+
+ Currently mappings still need to be added, Example:
+ mappings = {
+ i = {
+ ["<C-Down>"] = require('telescope.actions').cycle_history_next,
+ ["<C-Up>"] = require('telescope.actions').cycle_history_prev,
+ },
+ },
+
+ Fields:
+ - path: The path to the telescope history as string.
+ default: stdpath("data")/telescope_history
+ - limit: The amount of entries that will be written in the
+ history.
+ Warning: If limit is set to nil it will grown unbound.
+ default: 100
+ - handler: A lua function that implements the history.
+ This is meant as a developer setting for extensions to
+ override the history handling, e.g.,
+ https://github.com/nvim-telescope/telescope-smart-history.nvim,
+ which allows context sensitive (cwd + picker) history.
+
+ Default:
+ require('telescope.actions.history').get_simple_history
+
+ *telescope.defaults.cache_picker*
+ cache_picker: ~
+ This field handles the configuration for picker caching.
+ By default it is a table, with default values (more below).
+ To disable caching, set it to false.
+
+ Caching preserves all previous multi selections and results and
+ therefore may result in slowdown or increased RAM occupation
+ if too many pickers (`cache_picker.num_pickers`) or entries
+ ('cache_picker.limit_entries`) are cached.
+
+ Fields:
+ - num_pickers: The number of pickers to be cached.
+ Set to -1 to preserve all pickers of your session.
+ If passed to a picker, the cached pickers with
+ indices larger than `cache_picker.num_pickers` will
+ be cleared.
+ Default: 1
+ - limit_entries: The amount of entries that will be written in the
+ Default: 1000
+
+
+ *telescope.defaults.vimgrep_arguments*
+ vimgrep_arguments: ~
+ Defines the command that will be used for `live_grep` and `grep_string`
+ pickers.
+ Hint: Make sure that color is currently set to `never` because we do
+ not yet interpret color codes
+ Hint 2: Make sure that these options are in your changes arguments:
+ "--no-heading", "--with-filename", "--line-number", "--column"
+ because we need them so the ripgrep output is in the correct format.
+
+ Default: {
+ "rg",
+ "--color=never",
+ "--no-heading",
+ "--with-filename",
+ "--line-number",
+ "--column",
+ "--smart-case"
+ }
+
+ *telescope.defaults.use_less*
+ use_less: ~
+ Boolean if less should be enabled in term_previewer (deprecated and
+ currently no longer used in the builtin pickers).
+
+ Default: true
+
+ *telescope.defaults.set_env*
+ set_env: ~
+ Set an environment for term_previewer. A table of key values:
+ Example: { COLORTERM = "truecolor", ... }
+ Hint: Empty table is not allowed.
+
+ Default: nil
+
+ *telescope.defaults.color_devicons*
+ color_devicons: ~
+ Boolean if devicons should be enabled or not.
+ Hint: Coloring only works if |termguicolors| is enabled.
+
+ Default: true
*telescope.defaults.mappings*
mappings: ~
@@ -193,81 +376,92 @@ telescope.setup({opts}) *telescope.setup()*
...,
- *telescope.defaults.path_display*
- path_display: ~
- Determines how file paths are displayed
+ *telescope.defaults.default_mappings*
+ default_mappings: ~
+ Not recommended to use except for advanced users.
- path_display can be set to an array with a combination of:
- - "hidden" hide file names
- - "tail" only display the file name, and not the path
- - "absolute" display absolute paths
- - "smart" remove as much from the path as possible to only show
- the difference between the displayed paths
- - "shorten" only display the first character of each directory in
- the path
+ Will allow you to completely remove all of telescope's default maps
+ and use your own.
- You can also specify the number of characters of each directory name
- to keep by setting `path_display.shorten = num`.
- e.g. for a path like
- `alpha/beta/gamma/delta.txt`
- setting `path_display.shorten = 1` will give a path like:
- `a/b/g/delta.txt`
- Similarly, `path_display.shorten = 2` will give a path like:
- `al/be/ga/delta.txt`
- path_display can also be set to 'hidden' string to hide file names
+ *telescope.defaults.file_sorter*
+ file_sorter: ~
+ A function pointer that specifies the file_sorter. This sorter will
+ be used for find_files, git_files and similar.
+ Hint: If you load a native sorter, you dont need to change this value,
+ the native sorter will override it anyway.
- path_display can also be set to a function for custom formatting of
- the path display. Example:
+ Default: require("telescope.sorters").get_fzy_sorter
- -- Format path as "file.txt (path\to\file\)"
- path_display = function(opts, path)
- local tail = require("telescope.utils").path_tail(path)
- return string.format("%s (%s)", tail, path)
- end,
+ *telescope.defaults.generic_sorter*
+ generic_sorter: ~
+ A function pointer to the generic sorter. The sorter that should be
+ used for everything that is not a file.
+ Hint: If you load a native sorter, you dont need to change this value,
+ the native sorter will override it anyway.
- Default: {}
+ Default: require("telescope.sorters").get_fzy_sorter
- *telescope.defaults.prompt_prefix*
- prompt_prefix: ~
- Will be shown in front of the prompt.
+ *telescope.defaults.prefilter_sorter*
+ prefilter_sorter: ~
+ This points to a wrapper sorter around the generic_sorter that is able
+ to do prefiltering.
+ Its usually used for lsp_*_symbols and lsp_*_diagnostics
- Default: '> '
+ Default: require("telescope.sorters").prefilter
- *telescope.defaults.scroll_strategy*
- scroll_strategy: ~
- Determines what happens you try to scroll past view of the picker.
+ *telescope.defaults.file_ignore_patterns*
+ file_ignore_patterns: ~
+ A table of lua regex that define the files that should be ignored.
+ Example: { "^scratch/" } -- ignore all files in scratch directory
+ Example: { "%.npz" } -- ignore all npz files
+ See: https://www.lua.org/manual/5.1/manual.html#5.4.1 for more
+ information about lua regex
- Available options are:
- - "cycle" (default)
- - "limit"
+ Default: nil
- *telescope.defaults.selection_caret*
- selection_caret: ~
- Will be shown in front of the selection.
+ *telescope.defaults.file_previewer*
+ file_previewer: ~
+ Function pointer to the default file_previewer. It is mostly used
+ for find_files, git_files and similar.
+ You can change this function pointer to either use your own
+ previewer or use the command-line program bat as the previewer:
+ require("telescope.previewers").cat.new
- Default: '> '
+ Default: require("telescope.previewers").vim_buffer_cat.new
- *telescope.defaults.selection_strategy*
- selection_strategy: ~
- Determines how the cursor acts after each sort iteration.
+ *telescope.defaults.grep_previewer*
+ grep_previewer: ~
+ Function pointer to the default vim_grep previewer. It is mostly
+ used for live_grep, grep_string and similar.
+ You can change this function pointer to either use your own
+ previewer or use the command-line program bat as the previewer:
+ require("telescope.previewers").vimgrep.new
- Available options are:
- - "reset" (default)
- - "follow"
- - "row"
- - "closest"
+ Default: require("telescope.previewers").vim_buffer_vimgrep.new
- *telescope.defaults.sorting_strategy*
- sorting_strategy: ~
- Determines the direction "better" results are sorted towards.
+ *telescope.defaults.qflist_previewer*
+ qflist_previewer: ~
+ Function pointer to the default qflist previewer. It is mostly
+ used for qflist, loclist and lsp.
+ You can change this function pointer to either use your own
+ previewer or use the command-line program bat as the previewer:
+ require("telescope.previewers").qflist.new
- Available options are:
- - "descending" (default)
- - "ascending"
+ Default: require("telescope.previewers").vim_buffer_vimgrep.new
+
+ *telescope.defaults.buffer_previewer_maker*
+ buffer_previewer_maker: ~
+ Developer option that defines the underlining functionality
+ of the buffer previewer.
+ For interesting configuration examples take a look at
+ https://github.com/nvim-telescope/telescope.nvim/wiki/Configuration-Recipes
+
+ Default: require("telescope.previewers").buffer_previewer_maker
Parameters: ~
- {opts} (table) Configuration opts. Keys: defaults, extensions
+ {opts} (table) Configuration opts. Keys: defaults, pickers,
+ extensions
telescope.register_extension({mod}) *telescope.register_extension()*
@@ -346,41 +540,16 @@ To use any of Telescope's default options or any picker-specific options, call
your desired picker by passing a lua table to the picker with all of the
options you want to use. Here's an example with the live_grep picker:
-:lua require('telescope.builtin').live_grep({
- prompt_title = 'find string in open buffers...',
- grep_open_files = true
-})
--- or with dropdown theme
-:lua require('telescope.builtin').find_files(require('telescope.themes').get_dropdown{
- previewer = false
-})
-
-You can also pass default configurations to builtin pickers. These options will
-also be added if the picker is executed with `Telescope find_files`.
-
-require("telescope").setup {
- pickers = {
- buffers = {
- show_all_buffers = true,
- sort_lastused = true,
- theme = "dropdown",
- previewer = false,
- mappings = {
- i = {
- ["<c-d>"] = require("telescope.actions").delete_buffer,
- -- or right hand side can also be the name of the action as string
- ["<c-d>"] = "delete_buffer",
- },
- n = {
- ["<c-d>"] = require("telescope.actions").delete_buffer,
- }
- }
- }
- }
-}
-
-This will use the default configuration options. Other configuration options
-are still in flux at the moment
+>
+ :lua require('telescope.builtin').live_grep({
+ prompt_title = 'find string in open buffers...',
+ grep_open_files = true
+ })
+ -- or with dropdown theme
+ :lua require('telescope.builtin').find_files(require('telescope.themes').get_dropdown{
+ previewer = false
+ })
+<
builtin.live_grep({opts}) *builtin.live_grep()*
Search for a string and get results live as you type (respecting
@@ -390,18 +559,22 @@ builtin.live_grep({opts}) *builtin.live_grep()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {cwd} (string) root dir to search from (default is cwd,
- use utils.buffer_dir() to search
- relative to open buffer)
- {grep_open_files} (boolean) if true, restrict search to open files
- only, mutually exclusive with
- `search_dirs`
- {search_dirs} (table) directory/directories to search in,
- mutually exclusive with
- `grep_open_files`
- {additional_args} (function) function(opts) which returns a table of
- additional arguments to be passed on
+ Options: ~
+ {cwd} (string) root dir to search from (default:
+ cwd, use utils.buffer_dir() to
+ search relative to open buffer)
+ {grep_open_files} (boolean) if true, restrict search to open
+ files only, mutually exclusive with
+ `search_dirs`
+ {search_dirs} (table) directory/directories to search in,
+ mutually exclusive with
+ `grep_open_files`
+ {additional_args} (function) function(opts) which returns a table
+ of additional arguments to be passed
+ on
+ {max_results} (number) define a upper result value
+ {disable_coordinates} (boolean) don't show the line & row numbers
+ (default: false)
builtin.grep_string({opts}) *builtin.grep_string()*
@@ -411,17 +584,24 @@ builtin.grep_string({opts}) *builtin.grep_string()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {cwd} (string) root dir to search from (default is cwd,
- use utils.buffer_dir() to search
- relative to open buffer)
- {search} (string) the query to search
- {search_dirs} (table) directory/directories to search in
- {use_regex} (boolean) if true, special characters won't be
- escaped, allows for using regex (default
- is false)
- {additional_args} (function) function(opts) which returns a table of
- additional arguments to be passed on
+ Options: ~
+ {cwd} (string) root dir to search from (default:
+ cwd, use utils.buffer_dir() to
+ search relative to open buffer)
+ {search} (string) the query to search
+ {search_dirs} (table) directory/directories to search in
+ {use_regex} (boolean) if true, special characters won't be
+ escaped, allows for using regex
+ (default: false)
+ {word_match} (string) can be set to `-w` to enable exact
+ word matches
+ {additional_args} (function) function(opts) which returns a table
+ of additional arguments to be passed
+ on
+ {disable_coordinates} (boolean) don't show the line and row numbers
+ (default: false)
+ {sort_only_text} (boolean) only sort the text, not the file,
+ line or row (default: false)
builtin.find_files({opts}) *builtin.find_files()*
@@ -431,18 +611,19 @@ builtin.find_files({opts}) *builtin.find_files()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {cwd} (string) root dir to search from (default is cwd, use
+ Options: ~
+ {cwd} (string) root dir to search from (default: cwd, use
utils.buffer_dir() to search relative to
open buffer)
{find_command} (table) command line arguments for `find_files` to
- use for the search, overrides default config
+ use for the search, overrides default:
+ config
{follow} (boolean) if true, follows symlinks (i.e. uses `-L`
flag for the `find` command)
{hidden} (boolean) determines whether to show hidden files or
- not (default is false)
+ not (default: false)
{no_ignore} (boolean) show files ignored by .gitignore, .ignore,
- etc. (default is false)
+ etc. (default: false)
{search_dirs} (table) directory/directories to search in
@@ -469,14 +650,14 @@ builtin.file_browser({opts}) *builtin.file_browser()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {cwd} (string) root dir to browse from (default is cwd, use
+ Options: ~
+ {cwd} (string) root dir to browse from (default: cwd, use
utils.buffer_dir() to search relative to open
buffer)
- {depth} (number) file tree depth to display (default is 1)
- {dir_icon} (string) change the icon for a directory. default: 
+ {depth} (number) file tree depth to display (default: 1)
+ {dir_icon} (string) change the icon for a directory. (default: )
{hidden} (boolean) determines whether to show hidden files or not
- (default is false)
+ (default: false)
builtin.treesitter() *builtin.treesitter()*
@@ -486,9 +667,14 @@ builtin.treesitter() *builtin.treesitter()*
node you want to see (i.e. `:var:`)
- Fields: ~
- {show_line} (boolean) if true, shows the row:column that the result
- is found at (default is true)
+ Options: ~
+ {show_line} (boolean) if true, shows the row:column that the
+ result is found at (default: true)
+ {bufnr} (number) specify the buffer number where
+ treesitter should run. (default:
+ current buffer)
+ {symbol_highlights} (table) string -> string. Matches symbol with
+ hl_group
builtin.current_buffer_fuzzy_find({opts})*builtin.current_buffer_fuzzy_find()*
@@ -498,6 +684,10 @@ builtin.current_buffer_fuzzy_find({opts})*builtin.current_buffer_fuzzy_find()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {skip_empty_lines} (boolean) if true we dont display empty lines
+ (default: false)
+
builtin.tags({opts}) *builtin.tags()*
Lists tags in current directory with tag location file preview (users are
@@ -508,10 +698,16 @@ builtin.tags({opts}) *builtin.tags()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {ctags_file} (string) specify a particular ctags file to use
- {show_line} (boolean) if true, shows the content of the line the tag
- is found on in the picker (default is true)
+ Options: ~
+ {cwd} (string) root dir to search from (default: cwd, use
+ utils.buffer_dir() to search relative to
+ open buffer)
+ {ctags_file} (string) specify a particular ctags file to use
+ {show_line} (boolean) if true, shows the content of the line the
+ tag is found on in the picker (default:
+ true)
+ {only_sort_tags} (boolean) if true we will only sort tags (default:
+ false)
builtin.current_buffer_tags({opts}) *builtin.current_buffer_tags()*
@@ -521,6 +717,17 @@ builtin.current_buffer_tags({opts}) *builtin.current_buffer_tags()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {cwd} (string) root dir to search from (default: cwd, use
+ utils.buffer_dir() to search relative to
+ open buffer)
+ {ctags_file} (string) specify a particular ctags file to use
+ {show_line} (boolean) if true, shows the content of the line the
+ tag is found on in the picker (default:
+ true)
+ {only_sort_tags} (boolean) if true we will only sort tags (default:
+ false)
+
builtin.git_files({opts}) *builtin.git_files()*
Fuzzy search for files tracked by Git. This command lists the output of the
@@ -533,13 +740,17 @@ builtin.git_files({opts}) *builtin.git_files()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
+ Options: ~
+ {cwd} (string) specify the path of the repo
+ {use_git_root} (boolean) if we should use git root as cwd or
+ the cwd (important for submodule)
+ (default: true)
{show_untracked} (boolean) if true, adds `--others` flag to
command and shows untracked files
- (default is true)
+ (default: true)
{recurse_submodules} (boolean) if true, adds the
`--recurse-submodules` flag to command
- (default is false)
+ (default: false)
builtin.git_commits({opts}) *builtin.git_commits()*
@@ -554,8 +765,10 @@ builtin.git_commits({opts}) *builtin.git_commits()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {cwd} (string) specify the path of the repo
+ Options: ~
+ {cwd} (string) specify the path of the repo
+ {use_git_root} (boolean) if we should use git root as cwd or the cwd
+ (important for submodule) (default: true)
builtin.git_bcommits({opts}) *builtin.git_bcommits()*
@@ -570,10 +783,12 @@ builtin.git_bcommits({opts}) *builtin.git_bcommits()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {cwd} (string) specify the path of the repo
- {current_file} (string) specify the current file that should be used
- for bcommits (default: current buffer)
+ Options: ~
+ {cwd} (string) specify the path of the repo
+ {use_git_root} (boolean) if we should use git root as cwd or the cwd
+ (important for submodule) (default: true)
+ {current_file} (string) specify the current file that should be used
+ for bcommits (default: current buffer)
builtin.git_branches({opts}) *builtin.git_branches()*
@@ -593,6 +808,11 @@ builtin.git_branches({opts}) *builtin.git_branches()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {cwd} (string) specify the path of the repo
+ {use_git_root} (boolean) if we should use git root as cwd or the cwd
+ (important for submodule) (default: true)
+
builtin.git_status({opts}) *builtin.git_status()*
Lists git status for current directory
@@ -604,6 +824,14 @@ builtin.git_status({opts}) *builtin.git_status()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {cwd} (string) specify the path of the repo
+ {use_git_root} (boolean) if we should use git root as cwd or the cwd
+ (important for submodule) (default: true)
+ {git_icons} (table) string -> string. Matches name with icon
+ (see source code, make_entry.lua
+ git_icon_defaults)
+
builtin.git_stash({opts}) *builtin.git_stash()*
Lists stash items in current repository
@@ -614,6 +842,11 @@ builtin.git_stash({opts}) *builtin.git_stash()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {cwd} (string) specify the path of the repo
+ {use_git_root} (boolean) if we should use git root as cwd or the cwd
+ (important for submodule) (default: true)
+
builtin.builtin({opts}) *builtin.builtin()*
Lists all of the community maintained pickers built into Telescope
@@ -622,6 +855,40 @@ builtin.builtin({opts}) *builtin.builtin()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {ignore_filename} (boolean) dont show filenames (default: true)
+ {include_extensions} (boolean) if true will show the pickers of the
+ installed extensions (default: false)
+
+
+builtin.resume({opts}) *builtin.resume()*
+ Opens the previous picker in the identical state (incl. multi selections)
+ - Notes:
+ - Requires `cache_picker` in setup or when having invoked pickers, see
+ |telescope.defaults.cache_picker|
+
+
+ Parameters: ~
+ {opts} (table) options to pass to the picker
+
+ Options: ~
+ {cache_index} (number) what picker to resume, where 1 denotes most
+ recent (default: 1)
+
+
+builtin.pickers({opts}) *builtin.pickers()*
+ Opens a picker over previously cached pickers in there preserved states
+ (incl. multi selections)
+ - Default keymaps:
+ - `<C-x>`: delete the selected cached picker
+ - Notes:
+ - Requires `cache_picker` in setup or when having invoked pickers, see
+ |telescope.defaults.cache_picker|
+
+
+ Parameters: ~
+ {opts} (table) options to pass to the picker
+
builtin.planets({opts}) *builtin.planets()*
Use the telescope...
@@ -630,6 +897,10 @@ builtin.planets({opts}) *builtin.planets()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {show_pluto} (boolean) we love pluto (default: false, because its a
+ hidden feature)
+
builtin.symbols({opts}) *builtin.symbols()*
Lists symbols inside of `data/telescope-sources/*.json` found in your
@@ -643,7 +914,7 @@ builtin.symbols({opts}) *builtin.symbols()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
+ Options: ~
{symbol_path} (string) specify the second path. Default:
`stdpath("data")/telescope/symbols/*.json`
{sources} (table) specify a table of sources you want to load
@@ -665,6 +936,9 @@ builtin.quickfix({opts}) *builtin.quickfix()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {ignore_filename} (boolean) dont show filenames (default: true)
+
builtin.loclist({opts}) *builtin.loclist()*
Lists items from the current window's location list, jumps to location on
@@ -674,6 +948,9 @@ builtin.loclist({opts}) *builtin.loclist()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {ignore_filename} (boolean) dont show filenames (default: true)
+
builtin.oldfiles({opts}) *builtin.oldfiles()*
Lists previously open files, opens on `<cr>`
@@ -682,6 +959,9 @@ builtin.oldfiles({opts}) *builtin.oldfiles()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {only_cwd} (boolean) show only files in the cwd (default: false)
+
builtin.command_history({opts}) *builtin.command_history()*
Lists commands that were executed recently, and reruns them on `<cr>`
@@ -705,35 +985,6 @@ builtin.search_history({opts}) *builtin.search_history()*
{opts} (table) options to pass to the picker
-builtin.resume({opts}) *builtin.resume()*
- Opens the previous picker in the identical state (incl. multi selections)
- - Notes:
- - Requires `cache_picker` in setup or when having invoked pickers, see
- |telescope.defaults.cache_picker|
-
-
- Parameters: ~
- {opts} (table) options to pass to the picker
-
- Fields: ~
- {cache_index} (number) what picker to resume, where 1 denotes most
- recent (default 1)
-
-
-builtin.pickers({opts}) *builtin.pickers()*
- Opens a picker over previously cached pickers in there preserved states
- (incl. multi selections)
- - Default keymaps:
- - `<C-x>`: delete the selected cached picker
- - Notes:
- - Requires `cache_picker` in setup or when having invoked pickers, see
- |telescope.defaults.cache_picker|
-
-
- Parameters: ~
- {opts} (table) options to pass to the picker
-
-
builtin.vim_options({opts}) *builtin.vim_options()*
Lists vim options, allows you to edit the current value on `<cr>`
@@ -750,6 +1001,11 @@ builtin.help_tags({opts}) *builtin.help_tags()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {lang} (string) specify language (default: vim.o.helplang)
+ {fallback} (boolean) fallback to en if language isn't installed
+ (default: true)
+
builtin.man_pages({opts}) *builtin.man_pages()*
Lists manpage entries, opens them in a help window on `<cr>`
@@ -758,9 +1014,11 @@ builtin.man_pages({opts}) *builtin.man_pages()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {sections} (table) a list of sections to search, use `{ "ALL" }` to
- search in all sections
+ Options: ~
+ {sections} (table) a list of sections to search, use `{ "ALL" }`
+ to search in all sections (default: { "1" })
+ {man_cmd} (function) that returns the man command. (Default:
+ `apropos ""` on linux, `apropos " "` on macos)
builtin.reloader({opts}) *builtin.reloader()*
@@ -770,6 +1028,10 @@ builtin.reloader({opts}) *builtin.reloader()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {column_len} (number) define the max column len for the module name
+ (default: dynamic, longest module name)
+
builtin.buffers({opts}) *builtin.buffers()*
Lists open buffers in current neovim instance, opens selected buffer on
@@ -779,23 +1041,24 @@ builtin.buffers({opts}) *builtin.buffers()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
+ Options: ~
{show_all_buffers} (boolean) if true, show all buffers,
- including unloaded buffers (default
- true)
+ including unloaded buffers
+ (default: true)
{ignore_current_buffer} (boolean) if true, don't show the current
- buffer in the list (default false)
+ buffer in the list (default: false)
{only_cwd} (boolean) if true, only show buffers in the
- current working directory (default
+ current working directory (default:
false)
{sort_lastused} (boolean) Sorts current and last buffer to
the top and selects the lastused
- (default false)
+ (default: false)
{sort_mru} (boolean) Sorts all buffers after most recent
used. Not just the current and last
- one (default false)
+ one (default: false)
{bufnr_width} (number) Defines the width of the buffer
- numbers in front of the filenames
+ numbers in front of the filenames
+ (default: dynamic)
builtin.colorscheme({opts}) *builtin.colorscheme()*
@@ -805,7 +1068,7 @@ builtin.colorscheme({opts}) *builtin.colorscheme()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
+ Options: ~
{enable_preview} (boolean) if true, will preview the selected color
@@ -876,6 +1139,9 @@ builtin.tagstack({opts}) *builtin.tagstack()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {ignore_filename} (boolean) dont show filenames (default: true)
+
builtin.jumplist({opts}) *builtin.jumplist()*
Lists items from Vim's jumplist, jumps to location on `<cr>`
@@ -884,6 +1150,9 @@ builtin.jumplist({opts}) *builtin.jumplist()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {ignore_filename} (boolean) dont show filenames (default: true)
+
builtin.lsp_references({opts}) *builtin.lsp_references()*
Lists LSP references for word under the cursor, jumps to reference on
@@ -893,6 +1162,9 @@ builtin.lsp_references({opts}) *builtin.lsp_references()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {timeout} (number) timeout for the sync call (default: 10000)
+
builtin.lsp_definitions({opts}) *builtin.lsp_definitions()*
Goto the definition of the word under the cursor, if there's only one,
@@ -902,9 +1174,13 @@ builtin.lsp_definitions({opts}) *builtin.lsp_definitions()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {jump_type} (string) how to goto definition if there is only one,
- values: "tab", "split", "vsplit", "never"
+ Options: ~
+ {timeout} (number) timeout for the sync call (default:
+ 10000)
+ {jump_type} (string) how to goto definition if there is only
+ one, values: "tab", "split", "vsplit",
+ "never"
+ {ignore_filename} (boolean) dont show filenames (default: true)
builtin.lsp_type_definitions({opts}) *builtin.lsp_type_definitions()*
@@ -915,9 +1191,13 @@ builtin.lsp_type_definitions({opts}) *builtin.lsp_type_definitions()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {jump_type} (string) how to goto definition if there is only one,
- values: "tab", "split", "vsplit", "never"
+ Options: ~
+ {timeout} (number) timeout for the sync call (default:
+ 10000)
+ {jump_type} (string) how to goto definition if there is only
+ one, values: "tab", "split", "vsplit",
+ "never"
+ {ignore_filename} (boolean) dont show filenames (default: true)
builtin.lsp_implementations({opts}) *builtin.lsp_implementations()*
@@ -928,9 +1208,13 @@ builtin.lsp_implementations({opts}) *builtin.lsp_implementations()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {jump_type} (string) how to goto implementation if there is only one,
- values: "tab", "split", "vsplit", "never"
+ Options: ~
+ {timeout} (number) timeout for the sync call (default:
+ 10000)
+ {jump_type} (string) how to goto implementation if there is
+ only one, values: "tab", "split",
+ "vsplit", "never"
+ {ignore_filename} (boolean) dont show filenames (default: true)
builtin.lsp_code_actions({opts}) *builtin.lsp_code_actions()*
@@ -941,6 +1225,9 @@ builtin.lsp_code_actions({opts}) *builtin.lsp_code_actions()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {timeout} (number) timeout for the sync call (default: 10000)
+
builtin.lsp_range_code_actions({opts}) *builtin.lsp_range_code_actions()*
Lists any LSP actions for a given range, that can be triggered with `<cr>`
@@ -949,6 +1236,11 @@ builtin.lsp_range_code_actions({opts}) *builtin.lsp_range_code_actions()*
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {timeout} (number) timeout for the sync call (default: 10000)
+ {start_line} (number) where the code action ends (default: handled by
+ :'<,'>Telescope lsp_range_code_actions)
+
builtin.lsp_document_symbols({opts}) *builtin.lsp_document_symbols()*
Lists LSP document symbols in the current buffer
@@ -960,9 +1252,17 @@ builtin.lsp_document_symbols({opts}) *builtin.lsp_document_symbols()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {ignore_filename} (type) string with file to ignore
- {symbols} (string|table) filter results by symbol kind(s)
+ Options: ~
+ {timeout} (number) timeout for the sync call
+ (default: 10000)
+ {ignore_filename} (boolean) dont show filenames (default:
+ true)
+ {show_line} (boolean) if true, shows the content of the
+ line the tag is found on (default:
+ false)
+ {symbols} (string|table) filter results by symbol kind(s)
+ {symbol_highlights} (table) string -> string. Matches symbol
+ with hl_group
builtin.lsp_workspace_symbols({opts}) *builtin.lsp_workspace_symbols()*
@@ -975,9 +1275,19 @@ builtin.lsp_workspace_symbols({opts}) *builtin.lsp_workspace_symbols()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
- {ignore_filename} (string) file(s) to ignore
- {symbols} (string|table) filter results by symbol kind(s)
+ Options: ~
+ {query} (string) for what to query the workspace
+ (default: "")
+ {timeout} (number) timeout for the sync call
+ (default: 10000)
+ {ignore_filename} (boolean) dont show filenames (default:
+ false)
+ {show_line} (boolean) if true, shows the content of the
+ line the tag is found on (default:
+ false)
+ {symbols} (string|table) filter results by symbol kind(s)
+ {symbol_highlights} (table) string -> string. Matches symbol
+ with hl_group
builtin.lsp_dynamic_workspace_symbols({opts})*builtin.lsp_dynamic_workspace_symbols()*
@@ -990,6 +1300,13 @@ builtin.lsp_dynamic_workspace_symbols({opts})*builtin.lsp_dynamic_workspace_symb
Parameters: ~
{opts} (table) options to pass to the picker
+ Options: ~
+ {ignore_filename} (boolean) dont show filenames (default: false)
+ {show_line} (boolean) if true, shows the content of the line
+ the symbol is found on (default: false)
+ {symbol_highlights} (table) string -> string. Matches symbol with
+ hl_group
+
builtin.lsp_document_diagnostics({opts}) *builtin.lsp_document_diagnostics()*
Lists LSP diagnostics for the current buffer
@@ -1004,7 +1321,7 @@ builtin.lsp_document_diagnostics({opts}) *builtin.lsp_document_diagnostics()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
+ Options: ~
{severity} (string|number) filter diagnostics by severity name
(string) or id (number)
{severity_limit} (string|number) keep diagnostics equal or more
@@ -1013,8 +1330,8 @@ builtin.lsp_document_diagnostics({opts}) *builtin.lsp_document_diagnostics()*
{severity_bound} (string|number) keep diagnostics equal or less
severe wrt severity name (string) or
id (number)
- {no_sign} (bool) hide LspDiagnosticSigns from Results
- (default is false)
+ {no_sign} (boolean) hide LspDiagnosticSigns from Results
+ (default: false)
{line_width} (number) set length of diagnostic entry text
in Results
@@ -1033,7 +1350,7 @@ builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()*
Parameters: ~
{opts} (table) options to pass to the picker
- Fields: ~
+ Options: ~
{severity} (string|number) filter diagnostics by severity name
(string) or id (number)
{severity_limit} (string|number) keep diagnostics equal or more
@@ -1042,8 +1359,8 @@ builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()*
{severity_bound} (string|number) keep diagnostics equal or less
severe wrt severity name (string) or
id (number)
- {no_sign} (bool) hide LspDiagnosticSigns from Results
- (default is false)
+ {no_sign} (boolean) hide LspDiagnosticSigns from Results
+ (default: false)
{line_width} (number) set length of diagnostic entry text
in Results
@@ -1061,10 +1378,11 @@ themes.get_dropdown() *themes.get_dropdown()*
Dropdown style theme.
Usage:
-
+ >
`local builtin = require('telescope.builtin')`
`local themes = require('telescope.themes')`
`builtin.find_files(themes.get_dropdown())`
+<
@@ -1072,10 +1390,12 @@ themes.get_cursor() *themes.get_cursor()*
Cursor style theme.
Usage:
+ >
`local builtin = require('telescope.builtin')`
`local themes = require('telescope.themes')`
`builtin.lsp_code_actions(themes.get_cursor())`
+<
@@ -1083,10 +1403,11 @@ themes.get_ivy() *themes.get_ivy()*
Ivy style theme.
Usage:
-
+ >
`local builtin = require('telescope.builtin')`
`local themes = require('telescope.themes')`
`builtin.find_files(themes.get_ivy())`
+<
@@ -1098,6 +1419,7 @@ Layout strategies are different functions to position telescope.
All layout strategies are functions with the following signature:
+>
function(picker, columns, lines, layout_config)
-- Do some calculations here...
return {
@@ -1106,6 +1428,7 @@ All layout strategies are functions with the following signature:
prompt = prompt_configuration,
}
end
+<
Parameters: ~
- picker : A Picker object. (docs coming soon)
@@ -1773,18 +2096,21 @@ utils.map_entries({prompt_bufnr}, {f}) *utils.map_entries()*
- Indices are 1-indexed, whereas rows are 0-indexed.
- Warning: `map_entries` has no return value.
- The below example showcases how to collect results
+
Usage:
- local action_state = require "telescope.actions.state"
- local action_utils = require "telescope.actions.utils"
- function entry_value_by_row()
- local prompt_bufnr = vim.api.nvim_get_current_buf()
- local current_picker = action_state.get_current_picker(prompt_bufnr)
- local results = {}
- action_utils.map_entries(prompt_bufnr, function(entry, index, row)
- results[row] = entry.value
- end)
- return results
- end
+ >
+ local action_state = require "telescope.actions.state"
+ local action_utils = require "telescope.actions.utils"
+ function entry_value_by_row()
+ local prompt_bufnr = vim.api.nvim_get_current_buf()
+ local current_picker = action_state.get_current_picker(prompt_bufnr)
+ local results = {}
+ action_utils.map_entries(prompt_bufnr, function(entry, index, row)
+ results[row] = entry.value
+ end)
+ return results
+ end
+<
Parameters: ~
@@ -1802,18 +2128,21 @@ utils.map_selections({prompt_bufnr}, {f}) *utils.map_selections()*
- Selected entries are returned in order of their selection.
- Warning: `map_selections` has no return value.
- The below example showcases how to collect results
+
Usage:
- local action_state = require "telescope.actions.state"
- local action_utils = require "telescope.actions.utils"
- function selection_by_index()
- local prompt_bufnr = vim.api.nvim_get_current_buf()
- local current_picker = action_state.get_current_picker(prompt_bufnr)
- local results = {}
- action_utils.map_selections(prompt_bufnr, function(entry, index)
- results[index] = entry.value
- end)
- return results
- end
+ >
+ local action_state = require "telescope.actions.state"
+ local action_utils = require "telescope.actions.utils"
+ function selection_by_index()
+ local prompt_bufnr = vim.api.nvim_get_current_buf()
+ local current_picker = action_state.get_current_picker(prompt_bufnr)
+ local results = {}
+ action_utils.map_selections(prompt_bufnr, function(entry, index)
+ results[index] = entry.value
+ end)
+ return results
+ end
+<
Parameters: ~
@@ -1839,6 +2168,7 @@ Module for convenience to override defaults of corresponding
|telescope.actions| at |telescope.setup()|.
General usage:
+>
require("telescope").setup {
defaults = {
mappings = {
@@ -1853,6 +2183,7 @@ General usage:
},
},
}
+<
action_generate.which_key({opts}) *action_generate.which_key()*
Display the keymaps of registered actions similar to which-key.nvim.
@@ -1980,9 +2311,11 @@ previewers.new_termopen_previewer() *previewers.new_termopen_previewer()*
It requires you to specify one table entry `get_command(entry, status)`.
This `get_command` function has to return the terminal command that will be
executed for each entry. Example:
+ >
get_command = function(entry, status)
return { 'bat', entry.path }
end
+<
Additionally you can define:
- `title` a static title for example "File Preview"
@@ -2121,10 +2454,12 @@ previewers.new_buffer_previewer() *previewers.new_buffer_previewer()*
- `require('telescope.previewers.utils').ts_highlighter(bufnr, ft)`
- If you want to use `vim.fn.search` or similar you need to run it in
that specific buffer context. Do
+ >
vim.api.nvim_buf_call(bufnr, function()
-- for example `search` and `matchadd`
end)
to achieve that.
+<
- If you want to read a file into the buffer it's best to use
`buffer_previewer_maker`. But access this function with
`require('telescope.config').values.buffer_previewer_maker` because it
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()|.
---
---- <pre>
--- General usage:
+--- <code>
--- require("telescope").setup {
--- defaults = {
--- mappings = {
@@ -19,7 +19,7 @@
--- },
--- },
--- }
---- </pre>
+--- </code>
---@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
---- <pre>
+---
--- 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
---- </pre>
+--- <code>
+--- 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
+--- </code>
---@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
---- <pre>
+---
--- 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
---- </pre>
+--- <code>
+--- 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
+--- </code>
---@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:
---
---- <pre>
---- :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
---- })
---- </pre>
----
---- You can also pass default configurations to builtin pickers. These options will also be added if
---- the picker is executed with `Telescope find_files`.
----
---- <pre>
---- require("telescope").setup {
---- pickers = {
---- buffers = {
---- show_all_buffers = true,
---- sort_lastused = true,
---- theme = "dropdown",
---- previewer = false,
---- mappings = {
---- i = {
---- ["<c-d>"] = require("telescope.actions").delete_buffer,
---- -- or right hand side can also be the name of the action as string
---- ["<c-d>"] = "delete_buffer",
---- },
---- n = {
---- ["<c-d>"] = require("telescope.actions").delete_buffer,
---- }
---- }
---- }
---- }
---- }
---- </pre>
----
---- This will use the default configuration options. Other configuration options are still in flux at the moment
+--- <code>
+--- :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
+--- })
+--- </code>
---@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:
--- - `<C-l>`: 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:
--- - `<cr>`: 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
--- - `<C-r>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
--- - `<c-t>`: 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
--- - `<C-d>`: deletes the currently selected branch, with confirmation prompt before deletion
--- - `<C-y>`: 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
--- - `<Tab>`: stages or unstages the currently selected file
--- - `<cr>`: 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:
--- - `<cr>`: 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:
+--- - `<C-x>`: 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 `<cr>`
---@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 `<cr>`
---@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 `<cr>`
---@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 `<cr>`
@@ -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:
---- - `<C-x>`: 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 `<cr>`
---@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 `<cr>`
---@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 `<cr>`
---@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 `<cr>`
---@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 `<cr>`
---@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 `<cr>`
@@ -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 `<cr>`
---@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 `<cr>`
---@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 `<cr>`
---@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 `<cr>`
---@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 `<cr>`
---@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:
--- - `<C-l>`: 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:
--- - `<C-l>`: 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:
--- - `<C-l>`: 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 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,
- path_display can also be set to a function for custom formatting of
- the path display. Example:
+ Default: {}]]
+)
- -- 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,
+append(
+ "borderchars",
+ { "─", "│", "─", "│", "╭", "╮", "╯", "╰" },
+ [[
+ Set the borderchars of telescope floating windows. It has to be a
+ table of 8 string values.
- Default: {}]],
- },
+ Default: { "─", "│", "─", "│", "╭", "╮", "╯", "╰" }]]
+)
- borderchars = { { "─", "│", "─", "│", "╭", "╮", "╯", "╰" } },
+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
- 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
+ -- 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
- -- local status_icon
- -- if opts.completed then
- -- status_icon = "✔️"
- -- else
- -- status_icon = "*"
- -- end
+ Default: function that shows current count / all]]
+)
- return string.format("%s / %s ", xx, yy)
- end,
- },
+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.
- 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]]
+)
- 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.
- 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 = {
- ["<C-Down>"] = require('telescope.actions').cycle_history_next,
- ["<C-Up>"] = require('telescope.actions').cycle_history_prev,
- },
+ Currently mappings still need to be added, Example:
+ mappings = {
+ i = {
+ ["<C-Down>"] = require('telescope.actions').cycle_history_next,
+ ["<C-Up>"] = require('telescope.actions').cycle_history_prev,
},
+ },
- Fields:
- - path: The path to the telescope history as string.
- default: stdpath("data")/telescope_history
- - limit: The amount of entries that will be written in the
- history.
- Warning: If limit is set to nil it will grown unbound.
- default: 100
- - handler: A lua function that implements the history.
- This is meant as a developer setting for extensions to
- override the history handling, e.g.,
- https://github.com/nvim-telescope/telescope-smart-history.nvim,
- which allows context sensitive (cwd + picker) history.
-
- Default:
- require('telescope.actions.history').get_simple_history
- ]],
- },
+ 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,
- },
- [[
+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.
+
+ Default: {
+ "rg",
+ "--color=never",
+ "--no-heading",
+ "--with-filename",
+ "--line-number",
+ "--column",
+ "--smart-case"
+ }]]
+)
- -- 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" },
- },
+append(
+ "use_less",
+ true,
+ [[
+ Boolean if less should be enabled in term_previewer (deprecated and
+ currently no longer used in the builtin pickers).
+
+ Default: true]]
+)
- use_less = { true },
+append(
+ "set_env",
+ nil,
+ [[
+ Set an environment for term_previewer. A table of key values:
+ Example: { COLORTERM = "truecolor", ... }
+ Hint: Empty table is not allowed.
- color_devicons = { true },
+ Default: nil]]
+)
- set_env = { 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 = {
+ ["<esc>"] = 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 "<C-n>", just put
+ ...,
+ ["<C-n>"] = false,
+ ...,
+
+ Into your config.
+
+
+ otherwise, just set the mapping to the function that you want it to
+ be.
+
+ ...,
+ ["<C-i>"] = 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:
+
+ ...,
+ ["<C-i>"] = "select_default",
+ ...,
+
+ You can also add other mappings using tables with `type = "command"`.
For example:
- mappings = {
- i = {
- ["<esc>"] = require('telescope.actions').close,
- },
- }
+ ...,
+ ["jj"] = { "<esc>", type = "command" },
+ ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", 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 "<C-n>", just put
+ Will allow you to completely remove all of telescope's default maps
+ and use your own.
+ ]]
+)
- ...,
- ["<C-n>"] = 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]]
+)
- ...,
- ["<C-i>"] = 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]]
+)
+
+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
- ...,
- ["<C-i>"] = "select_default",
- ...,
+ Default: nil]]
+)
- You can also add other mappings using tables with `type = "command"`.
- For example:
+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
- ...,
- ["jj"] = { "<esc>", type = "command" },
- ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
- ...,
- ]],
- },
+ Default: require("telescope.previewers").vim_buffer_cat.new]]
+)
- default_mappings = {
- nil,
- [[
- Not recommended to use except for advanced users.
+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
- Will allow you to completely remove all of telescope's default maps
- and use your own.
- ]],
- },
+ Default: require("telescope.previewers").vim_buffer_vimgrep.new]]
+)
- generic_sorter = { sorters.get_generic_fuzzy_sorter },
- prefilter_sorter = { sorters.prefilter },
- file_sorter = { sorters.get_fuzzy_file },
+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_ignore_patterns = { nil },
+ Default: require("telescope.previewers").vim_buffer_vimgrep.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,
- },
-}
+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
+---
--- <pre>
--- 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
--- </pre>
---@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:
+--- <code>
+--- 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
+--- }
+--- }
+--- </code>
+---@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 = { "<pre>", "", "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:
---- <pre>
+--- <code>
--- 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
---- </pre>
+--- </code>
---
--- 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:
---
---- <pre>
+--- <code>
--- function(picker, columns, lines, layout_config)
--- -- Do some calculations here...
--- return {
@@ -15,7 +15,9 @@
--- prompt = prompt_configuration,
--- }
--- end
+--- </code>
---
+--- <pre>
--- 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:
---- <pre>
+--- <code>
--- get_command = function(entry, status)
--- return { 'bat', entry.path }
--- end
---- </pre>
+--- </code>
---
--- 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
---- <pre>
+--- <code>
--- vim.api.nvim_buf_call(bufnr, function()
--- -- for example `search` and `matchadd`
--- end)
--- to achieve that.
---- </pre>
+--- </code>
--- - 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.
---- <pre>
---
--- Usage:
----
+--- <code>
--- `local builtin = require('telescope.builtin')`
--- `local themes = require('telescope.themes')`
--- `builtin.find_files(themes.get_dropdown())`
---- </pre>
+--- </code>
function themes.get_dropdown(opts)
opts = opts or {}
@@ -59,14 +58,14 @@ function themes.get_dropdown(opts)
end
--- Cursor style theme.
---- <pre>
---
--- Usage:
+--- <code>
---
--- `local builtin = require('telescope.builtin')`
--- `local themes = require('telescope.themes')`
--- `builtin.lsp_code_actions(themes.get_cursor())`
---- </pre>
+--- </code>
function themes.get_cursor(opts)
opts = opts or {}
@@ -97,14 +96,13 @@ function themes.get_cursor(opts)
end
--- Ivy style theme.
---- <pre>
---
--- Usage:
----
+--- <code>
--- `local builtin = require('telescope.builtin')`
--- `local themes = require('telescope.themes')`
--- `builtin.find_files(themes.get_ivy())`
---- </pre>
+--- </code>
function themes.get_ivy(opts)
opts = opts or {}
generated by cgit v1.2.3 (git 2.25.1) at 2026-02-12 10:10:00 +0000