leigh/telescope.nvim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite readme and add missing config values + builtin opts

Browse Source
This commit is contained in:
Simon Hauser
2021-09-13 22:03:41 +02:00
parent aaffa84ebb
commit 5131df7df1
17 changed files with 1822 additions and 1165 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
.github/ISSUE_TEMPLATE/bug_report.yml vendored
View File

@@ -28,6 +28,24 @@ body:
placeholder: "macOS 11.5"
validations:
required: true
- type: textarea
attributes:
label: "checkhealth telescope"
description: "Output of `:checkhealth telescope`"
placeholder: |
health#telescope#check
========================================================================
## Checking for required plugins
- OK: plenary installed.
- OK: nvim-treesitter installed.
## Checking external dependencies
- OK: rg: found ripgrep 13.0.0
- OK: fd: found fd 8.2.1
## ===== Installed extensions =====
validations:
required: true
- type: textarea
attributes:
label: "Steps to reproduce"

2
LICENSE
View File

@@ -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

678
README.md
View File

@@ -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.
- **Global Customization** affecting all pickers can be done through the main
`setup()` method (see defaults below)
- **Individual Customization** affecting a single picker by passing `opts` to
builtin pickers (e.g. `builtin.find_files(opts)`) see
[Configuration recipes](https://github.com/nvim-telescope/telescope.nvim/wiki/Configuration-Recipes)
wiki page for ideas.
### Telescope Defaults
As an example of using the `setup()` method, the following code configures
`telescope.nvim` to its default settings:
### Telescope setup structure
```lua
require('telescope').setup{
defaults = {
vimgrep_arguments = {
'rg',
'--color=never',
'--no-heading',
'--with-filename',
'--line-number',
'--column',
'--smart-case'
-- Default configuration for telescope goes here:
-- config_key = value,
-- ..
},
prompt_prefix = "> ",
selection_caret = "> ",
entry_prefix = " ",
initial_mode = "insert",
selection_strategy = "reset",
sorting_strategy = "descending",
layout_strategy = "horizontal",
layout_config = {
horizontal = {
mirror = false,
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
},
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
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,99 +177,18 @@ 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 |
| `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 |
@@ -284,113 +197,41 @@ Many familiar mapping patterns are setup as defaults.
| `<C-/>/?` | Show picker mappings (in insert & normal mode, respectively) |
| `<C-c>` | Close telescope |
| `<Esc>` | Close telescope (in normal mode) |
To see the full list of mappings, check out `lua/telescope/mappings.lua` and
the `default_mappings` table.
| `<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 |
Much like [built-in pickers](#pickers), there are a number of
To see the full list of mappings, check out `lua/telescope/mappings.lua` and the
`default_mappings` table.
Much like [builtin pickers](#pickers), there are a number of
[actions](https://github.com/nvim-telescope/telescope.nvim/blob/master/lua/telescope/actions/init.lua)
you can pick from to remap your telescope buffer mappings, or create a new custom action:
you can pick from to remap your telescope buffer mappings, or create a new
custom action:
<!-- 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,162 +362,16 @@ A `Sorter` is called by the `Picker` on each item returned by the `Finder`. It
returns a number, which is equivalent to the "distance" between the current
`prompt` and the `entry` returned by a `finder`.
<!-- 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. -->
## Themes
Common groups of settings can be set up to allow for themes.
We have some built in themes but are looking for more cool options.
![dropdown](https://i.imgur.com/SorAcXv.png)
| Themes | Description |
|--------------------------|---------------------------------------------------------------------------------------------|
| `themes.get_dropdown` | A list like centered list. [dropdown](https://i.imgur.com/SorAcXv.png) |
| `themes.get_cursor` | [A cursor relative list.](https://github.com/nvim-telescope/telescope.nvim/pull/878) |
| `themes.get_ivy` | Bottom panel overlay. [Ivy #771](https://github.com/nvim-telescope/telescope.nvim/pull/771) |
To use a theme, simply append it to a built-in function:
```vim
nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({}))<cr>
" Change an option
nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({ winblend = 10 }))<cr>
```
Or use with a command:
```vim
Telescope find_files theme=get_dropdown
```
Themes should work with every `telescope.builtin` function. If you wish to make a theme,
check out `lua/telescope/themes.lua`.
## Autocmds
Telescope user autocmds:
| Event | Description |
|---------------------------------|---------------------------------------------------------|
| `User TelescopeFindPre` | Do it before Telescope creates all the floating windows |
| `User TelescopePreviewerLoaded` | Do it after Telescope previewer window is created |
## Extensions
Telescope provides the capabilities to create & register extensions, which improve telescope in a
variety of ways.
Some extensions provide integration with external tools, outside of the scope of `builtins`.
Others provide performance enhancements by using compiled C and interfacing directly with Lua.
### Loading extensions
To load an extension, use the `load_extension` function as shown in the example below:
```lua
-- This will load fzy_native and have it override the default file sorter
require('telescope').load_extension('fzy_native')
```
You may skip explicitly loading extensions (they will then be lazy-loaded), but tab completions will
not be available right away.
### Accessing pickers from extensions
Pickers from extensions are added to the `:Telescope` command under their respective name.
For example:
```viml
" Run the `configurations` picker from nvim-dap
:Telescope dap configurations
```
They can also be called directly from Lua:
```lua
-- Run the `configurations` picker from nvim-dap
require('telescope').extensions.dap.configurations()
```
### Community Extensions
For a list of community extensions, please consult the Wiki: [Extensions](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions)
## API
<!-- 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 (display)
Layout can be configured by choosing a specific `layout_strategy` and
specifying a particular `layout_config` for that strategy.
For more details on available strategies and configuration options,
see `:help telescope.layout`.
Some options for configuring sizes in layouts are "resolvable".
This means that they can take different forms, and will be interpreted differently according
to which form they take.
Some options for configuring sizes in layouts are "resolvable". This means that
they can take different forms, and will be interpreted differently according to
which form they take.
For example, if we wanted to set the `width` of a picker using the `vertical`
layout strategy to 50% of the screen width, we would specify that width
as `0.5`, but if we wanted to specify the `width` to be exactly 80
@@ -719,6 +401,54 @@ require('telescope').setup({
})
```
## Themes
Common groups of settings can be set up to allow for themes.
We have some built in themes but are looking for more cool options.
![dropdown](https://i.imgur.com/SorAcXv.png)
| Themes | Description |
|--------------------------|---------------------------------------------------------------------------------------------|
| `themes.get_dropdown` | A list like centered list. [dropdown](https://i.imgur.com/SorAcXv.png) |
| `themes.get_cursor` | [A cursor relative list.](https://github.com/nvim-telescope/telescope.nvim/pull/878) |
| `themes.get_ivy` | Bottom panel overlay. [Ivy #771](https://github.com/nvim-telescope/telescope.nvim/pull/771) |
To use a theme, simply append it to a builtin function:
```vim
nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({}))<cr>
" Change an option
nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({ winblend = 10 }))<cr>
```
Or use with a command:
```vim
Telescope find_files theme=dropdown
```
Or you can configure it in the pickers table in `telescope.setup`:
```lua
require('telescope').setup{
defaults = {
-- ...
},
pickers = {
find_files = {
theme = "dropdown",
}
},
extensions = {
-- ...
}
}
```
Themes should work with every `telescope.builtin` function. If you wish to make
a theme, check out `lua/telescope/themes.lua`.
## Vim Commands
All `telescope.nvim` functions are wrapped in `vim` commands for easy access,
@@ -735,64 +465,80 @@ tab completions and setting options.
" Setting options
:Telescope find_files prompt_prefix=🔍
" If option is table type in Lua code, you can use `,` to connect each command string, e.g.:
" find_command,vimgrep_arguments are both table type. So configure it on command-line like so:
" If the option accepts a Lua table as its value, you can use, to connect each
" command string, e.g.: find_command, vimgrep_arguments are both options that
" accept a Lua table as a value. So, you can configure them on the command line
"like so:
:Telescope find_files find_command=rg,--ignore,--hidden,--files prompt_prefix=🔍
```
for more information and how to realize more complex commands please read
`:help telescope.command`.
## Autocmds
Telescope user autocmds:
| Event | Description |
|---------------------------------|---------------------------------------------------------|
| `User TelescopeFindPre` | Do it before Telescope creates all the floating windows |
| `User TelescopePreviewerLoaded` | Do it after Telescope previewer window is created |
## Extensions
Telescope provides the capabilities to create & register extensions, which
improve telescope in a variety of ways.
Some extensions provide integration with external tools, outside of the scope of
`builtins`. Others provide performance enhancements by using compiled C and
interfacing directly with Lua over LuaJIT's FFI library.
A list of community extensions can be found in the
[Extensions](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions)
wiki. Always read the README of the extension you want to install, but here is a
general overview of how most extensions work.
### Loading extensions
To load an extension, use the `load_extension` function as shown in the example
below:
```lua
-- This will load fzy_native and have it override the default file sorter
require('telescope').load_extension('fzy_native')
```
You may skip explicitly loading extensions (they will then be lazy-loaded), but
tab completions will not be available right away.
### Accessing pickers from extensions
Pickers from extensions are added to the `:Telescope` command under their
respective name. For example:
```viml
" Run the `configurations` picker from nvim-dap
:Telescope dap configurations
```
They can also be called directly from Lua:
```lua
-- Run the `configurations` picker from nvim-dap
require('telescope').extensions.dap.configurations()
```
## API
For writing your own picker and for information about the API please read the
[Developers Documentation](developers.md).
## Media
- [What is Telescope? (Video)](https://www.twitch.tv/teej_dv/clip/RichDistinctPlumberPastaThat)
- [More advanced configuration (Video)](https://www.twitch.tv/videos/756229115)
- [Example video](https://www.youtube.com/watch?v=65AVwHZflsU)
## FAQ
<!-- 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.

312
developers.md
View File

@@ -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`

871
doc/telescope.txt
View File

File diff suppressed because it is too large Load Diff

4
lua/telescope/actions/generate.lua
View File

@@ -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"

10
lua/telescope/actions/utils.lua
View File

@@ -16,8 +16,9 @@ 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:
--- <code>
--- local action_state = require "telescope.actions.state"
--- local action_utils = require "telescope.actions.utils"
--- function entry_value_by_row()
@@ -29,7 +30,7 @@ local utils = {}
--- end)
--- return results
--- end
--- </pre>
--- </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,8 +53,9 @@ 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:
--- <code>
--- local action_state = require "telescope.actions.state"
--- local action_utils = require "telescope.actions.utils"
--- function selection_by_index()
@@ -65,7 +67,7 @@ end
--- end)
--- return results
--- end
--- </pre>
--- </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)

174
lua/telescope/builtin/init.lua
View File

@@ -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,7 +14,7 @@
--- 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>
--- <code>
--- :lua require('telescope.builtin').live_grep({
--- prompt_title = 'find string in open buffers...',
--- grep_open_files = true
@@ -21,35 +23,7 @@
--- :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>
---@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

7
lua/telescope/builtin/internal.lua
View File

@@ -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",

3
lua/telescope/command.lua
View File

@@ -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

335
lua/telescope/config.lua
View File

@@ -120,19 +120,26 @@ 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 = {
append(
"sorting_strategy",
"descending",
[[
Determines the direction "better" results are sorted towards.
Available options are:
- "descending" (default)
- "ascending"]],
},
- "ascending"]]
)
selection_strategy = {
append(
"selection_strategy",
"reset",
[[
Determines how the cursor acts after each sort iteration.
@@ -141,58 +148,92 @@ local telescope_defaults = {
- "reset" (default)
- "follow"
- "row"
- "closest"]],
},
- "closest"]]
)
scroll_strategy = {
append(
"scroll_strategy",
"cycle",
[[
Determines what happens you try to scroll past view of the picker.
Determines what happens if you try to scroll past the view of the
picker.
Available options are:
- "cycle" (default)
- "limit"]],
},
- "limit"]]
)
layout_strategy = {
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 = {
Default: '> ']]
)
append(
"entry_prefix",
" ",
[[
Prefix in front of each result entry. Current selection not included.
Default: ' ']],
},
Default: ' ']]
)
initial_mode = { "insert" },
append(
"initial_mode",
"insert",
[[
Determines in which mode telescope starts. Valid Keys:
`insert` and `normal`.
border = { true, [[
Default: "insert"]]
)
append(
"border",
true,
[[
Boolean defining if borders are added to Telescope windows.
Default: true]] },
Default: true]]
)
path_display = {
append(
"path_display",
{},
[[
Determines how file paths are displayed
@@ -226,13 +267,22 @@ local telescope_defaults = {
return string.format("%s (%s)", tail, path)
end,
Default: {}]],
},
Default: {}]]
)
borderchars = { { "─", "│", "─", "│", "╭", "╮", "╯", "╰" } },
append(
"borderchars",
{ "─", "│", "─", "│", "╭", "╮", "╯", "╰" },
[[
Set the borderchars of telescope floating windows. It has to be a
table of 8 string values.
get_status_text = {
function(self, opts)
Default: { "─", "│", "─", "│", "╭", "╮", "╯", "╰" }]]
)
append(
"get_status_text",
function(self)
local xx = (self.stats.processed or 0) - (self.stats.filtered or 0)
local yy = self.stats.processed or 0
if xx == 0 and yy == 0 then
@@ -245,22 +295,28 @@ local telescope_defaults = {
-- else
-- status_icon = "*"
-- end
return string.format("%s / %s ", xx, yy)
return string.format("%s / %s", xx, yy)
end,
},
[[
A function that determines what the virtual text looks like.
Signature: function(picker) -> str
dynamic_preview_title = {
Default: function that shows current count / all]]
)
append(
"dynamic_preview_title",
false,
[[
Will change the title of the preview window dynamically, where it
is supported. Means the preview window will for example show the
full filename.
is supported. For example, the preview window's title could show up as
the full filename.
Default: false]],
},
Default: false]]
)
history = {
append(
"history",
{
path = vim.fn.stdpath "data" .. os_sep .. "telescope_history",
limit = 100,
@@ -295,11 +351,11 @@ local telescope_defaults = {
which allows context sensitive (cwd + picker) history.
Default:
require('telescope.actions.history').get_simple_history
]],
},
require('telescope.actions.history').get_simple_history]]
)
cache_picker = {
append(
"cache_picker",
{
num_pickers = 1,
limit_entries = 1000,
@@ -323,24 +379,65 @@ local telescope_defaults = {
Default: 1
- limit_entries: The amount of entries that will be written in the
Default: 1000
]],
},
]]
)
-- Builtin configuration
-- List that will be executed.
-- Last argument will be the search term (passed in during execution)
vimgrep_arguments = {
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.
use_less = { true },
Default: {
"rg",
"--color=never",
"--no-heading",
"--with-filename",
"--line-number",
"--column",
"--smart-case"
}]]
)
color_devicons = { true },
append(
"use_less",
true,
[[
Boolean if less should be enabled in term_previewer (deprecated and
currently no longer used in the builtin pickers).
set_env = { nil },
Default: true]]
)
mappings = {
append(
"set_env",
nil,
[[
Set an environment for term_previewer. A table of key values:
Example: { COLORTERM = "truecolor", ... }
Hint: Empty table is not allowed.
Default: nil]]
)
append(
"color_devicons",
true,
[[
Boolean if devicons should be enabled or not.
Hint: Coloring only works if |termguicolors| is enabled.
Default: true]]
)
append(
"mappings",
{},
[[
Your mappings to override telescope's default mappings.
@@ -394,46 +491,127 @@ local telescope_defaults = {
["jj"] = { "<esc>", type = "command" },
["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
...,
]],
},
]]
)
default_mappings = {
append(
"default_mappings",
nil,
[[
Not recommended to use except for advanced users.
Will allow you to completely remove all of telescope's default maps
and use your own.
]],
},
]]
)
generic_sorter = { sorters.get_generic_fuzzy_sorter },
prefilter_sorter = { sorters.prefilter },
file_sorter = { sorters.get_fuzzy_file },
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.
file_ignore_patterns = { nil },
Default: require("telescope.sorters").get_fzy_sorter]]
)
file_previewer = {
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.
Default: require("telescope.sorters").get_fzy_sorter]]
)
--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
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
Default: nil]]
)
append(
"file_previewer",
function(...)
return require("telescope.previewers").vim_buffer_cat.new(...)
end,
},
grep_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: require("telescope.previewers").vim_buffer_cat.new]]
)
append(
"grep_previewer",
function(...)
return require("telescope.previewers").vim_buffer_vimgrep.new(...)
end,
},
qflist_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
Default: require("telescope.previewers").vim_buffer_vimgrep.new]]
)
append(
"qflist_previewer",
function(...)
return require("telescope.previewers").vim_buffer_qflist.new(...)
end,
},
buffer_previewer_maker = {
[[
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
Default: require("telescope.previewers").vim_buffer_vimgrep.new]]
)
append(
"buffer_previewer_maker",
function(...)
return require("telescope.previewers").buffer_previewer_maker(...)
end,
},
}
[[
Developer option that defines the underlining functionality
of the buffer previewer.
For interesting configuration examples take a look at
https://github.com/nvim-telescope/telescope.nvim/wiki/Configuration-Recipes
Default: require("telescope.previewers").buffer_previewer_maker]]
)
-- @param user_defaults table: a table where keys are the names of options,
-- and values are the ones the user wants
@@ -470,8 +648,7 @@ function config.set_defaults(user_defaults, tele_defaults)
end
local function set(name, default_val, description)
-- TODO(doc): Once we have descriptions for all of these, then we can add this back in.
-- assert(description, "Config values must always have a description")
assert(description, "Config values must always have a description")
config.values[name] = get(name, default_val)
if description then

57
lua/telescope/init.lua
View File

@@ -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]

8
lua/telescope/make_entry.lua
View File

@@ -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 = {

4
lua/telescope/pickers.lua
View File

@@ -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()`

4
lua/telescope/pickers/layout_strategies.lua
View File

@@ -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

8
lua/telescope/previewers/init.lua
View File

@@ -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`

14
lua/telescope/themes.lua
View File

@@ -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 {}