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

Docs for builtin pickers (#783)

Browse Source
This commit is contained in:
Ben Smith
2021-05-13 18:44:26 +00:00
committed by GitHub
parent 22a78a4636
commit e88864123b
5 changed files with 877 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
CONTRIBUTING.md
View File

@@ -1,4 +1,10 @@
# Documentation # Contributing
## Submitting a new feature
Thanks for taking the time to submit code to Telescope if you're reading this! We love having new contributors and love seeing the Neovim community come around this plugin and keep making it better If you are submitting a new PR with a feature addition, please make sure that you add the appropriate documentation. For examples of how to document a new picker for instance, check the `lua/telescope/builtin/init.lua` file to see how we write function headers for all of the pickers there. To learn how we go about writing documentation for this project, keep reading below!
## Documentation with treesitter
We are generating docs based on the tree sitter syntax tree. TJ wrote a grammar that includes the documentation in this syntax tree so we can do take this function header documentation and transform it into vim documentation. All documentation that is part of the returning module will be exported. So example: We are generating docs based on the tree sitter syntax tree. TJ wrote a grammar that includes the documentation in this syntax tree so we can do take this function header documentation and transform it into vim documentation. All documentation that is part of the returning module will be exported. So example:

116
README.md
View File

@@ -245,7 +245,7 @@ Many familiar mapping patterns are setup as defaults.
| `<C-n>/<Down>` | Next item | | `<C-n>/<Down>` | Next item |
| `<C-p>/<Up>` | Previous item | | `<C-p>/<Up>` | Previous item |
| `j/k` | Next/previous (in normal mode) | | `j/k` | Next/previous (in normal mode) |
| `<CR>` | Confirm selection | | `<cr>` | Confirm selection |
| `<C-x>` | go to file selection as a split | | `<C-x>` | go to file selection as a split |
| `<C-v>` | go to file selection as a vsplit | | `<C-v>` | go to file selection as a vsplit |
| `<C-t>` | go to a file in a new tab | | `<C-t>` | go to a file in a new tab |
@@ -292,10 +292,10 @@ require('telescope').setup{
["<C-i>"] = actions.select_horizontal, ["<C-i>"] = actions.select_horizontal,
-- Add up multiple actions -- Add up multiple actions
["<CR>"] = actions.select_default + actions.center, ["<cr>"] = actions.select_default + actions.center,
-- You can perform as many actions in a row as you like -- You can perform as many actions in a row as you like
["<CR>"] = actions.select_default + actions.center + my_cool_custom_action, ["<cr>"] = actions.select_default + actions.center + my_cool_custom_action,
}, },
n = { n = {
["<esc>"] = actions.close, ["<esc>"] = actions.close,
@@ -367,12 +367,12 @@ Built-in functions. Ready to be bound to any key you like. :smile:
### File Pickers ### File Pickers
| Functions | Description | | Functions | Description |
|-------------------------------------|---------------------------------------------------------------------------------------------| |-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| `builtin.find_files` | Lists Files in current directory. | | `builtin.find_files` | Lists files in your current working directory, respects .gitignore |
| `builtin.git_files` | Lists Git files in current directory. | | `builtin.git_files` | Fuzzy search through the output of `git ls-files` command, respects .gitignore, optionally ignores untracked files |
| `builtin.grep_string` | Searches for a string under the cursor in current directory. | | `builtin.grep_string` | Searches for the string under your cursor in your current working directory |
| `builtin.live_grep` | Searches in current directory files. (respecting .gitignore) | | `builtin.live_grep` | Search for a string in your current working directory and get results live as you type (respecting .gitignore) |
| `builtin.file_browser` | Ivy-like file explorer. Creates files by typing in filename and pressing `<C-e>`. Press `<C-e>` without prompt for more info | | `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 #### Options for builtin.live_grep
@@ -381,57 +381,65 @@ Built-in functions. Ready to be bound to any key you like. :smile:
| `grep_open_files` | Restrict live_grep to currently open files, mutually exclusive with `search_dirs` | boolean | | `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 | | `search_dirs` | List of directories to search in, mutually exclusive with `grep_open_files` | list |
### Vim Pickers ### Vim Pickers
| Functions | Description | | Functions | Description |
|-------------------------------------|---------------------------------------------------------------------------------------------| |-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `builtin.buffers` | Lists Open buffers in the current vim instance. | | `builtin.buffers` | Lists open buffers in current neovim instance |
| `builtin.oldfiles` | Lists Previously open files. | | `builtin.oldfiles` | Lists previously open files |
| `builtin.commands` | Lists Available plugin/user commands and run it. | | `builtin.commands` | Lists available plugin/user commands and runs them on `<cr>` |
| `builtin.tags` | Lists Tags in current directory with preview (ctags -R). | | `builtin.tags` | Lists tags in current directory with tag location file preview (users are required to run ctags -R to generate tags or update when introducing new changes) |
| `builtin.tagstack` | Lists Tagstack entries. | | `builtin.command_history` | Lists commands that were executed recently, and reruns them on `<cr>` |
| `builtin.command_history` | Lists Commands previously ran and run it on enter. | | `builtin.search_history` | Lists searches that were executed recently, and reruns them on `<cr>` |
| `builtin.search_history` | Lists Searches previously ran and run it on enter. | | `builtin.help_tags` | Lists available help tags and opens a new window with the relevant help info on `<cr>` |
| `builtin.help_tags` | Lists Available help tags and open help document. | | `builtin.man_pages` | Lists manpage entries, opens them in a help window on `<cr>` |
| `builtin.man_pages` | Lists Man entries. | | `builtin.marks` | Lists vim marks and their value |
| `builtin.marks` | Lists Markers and their value. | | `builtin.colorscheme` | Lists available colorschemes and applies them on `<cr>` |
| `builtin.colorscheme` | Lists Colorscheme and switch to it on enter. | | `builtin.quickfix` | Lists items in the quickfix list |
| `builtin.quickfix` | Lists items from quickfix. | | `builtin.loclist` | Lists items from the current window's location list |
| `builtin.loclist` | Lists items from current window's location list. | | `builtin.vim_options` | Lists vim options, allows you to edit the current value on `<cr>` |
| `builtin.jumplist` | Lists Jump List entries. | | `builtin.registers` | Lists vim registers, pastes the contents of the register on `<cr>` |
| `builtin.vim_options` | Lists vim options and on enter edit the options value. | | `builtin.autocommands` | Lists vim autocommands and goes to their declaration on `<cr>` |
| `builtin.registers` | Lists vim registers and edit or paste selection. | | `builtin.spell_suggest` | Lists spelling suggestions for the current word under the cursor, replaces word with selected suggestion on `<cr>` |
| `builtin.autocommands` | Lists vim autocommands and go to their declaration. | | `builtin.keymaps` | Lists normal mode keymappings |
| `builtin.spell_suggest` | Lists spelling suggestions for <cword>. | | `builtin.filetypes` | Lists all available filetypes |
| `builtin.keymaps` | Lists normal-mode mappings. | | `builtin.highlights` | Lists all available highlights |
| `builtin.filetypes` | Lists all filetypes. | | `builtin.current_buffer_fuzzy_find` | Live fuzzy search inside of the currently open buffer |
| `builtin.highlights` | Lists all highlights. | | `builtin.current_buffer_tags` | Lists all of the tags for the currently open buffer, with a preview |
| `builtin.current_buffer_fuzzy_find` | Searches in current buffer lines. |
| `builtin.current_buffer_tags` | Lists Tags in current buffer. |
### LSP Pickers ### Neovim LSP Pickers
| Functions | Description | | Functions | Description |
|-------------------------------------|---------------------------------------------------------------------------------------------| |---------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
| `builtin.lsp_references` | Searches in LSP references. | | `builtin.lsp_references` | Lists LSP references for word under the cursor |
| `builtin.lsp_document_symbols` | Searches in LSP Document Symbols in the current document. | | `builtin.lsp_document_symbols` | Lists LSP document symbols in the current buffer |
| `builtin.lsp_workspace_symbols` | Searches in LSP all workspace symbols. | | `builtin.lsp_workspace_symbols` | Lists LSP document symbols in the current workspace |
| `builtin.lsp_code_actions` | Lists LSP action to be trigged on enter. | | `builtin.lsp_dynamic_workspace_symbols` | Dynamically Lists LSP for all workspace symbols |
| `builtin.lsp_range_code_actions` | Lists LSP range code action to be trigged on enter. | | `builtin.lsp_code_actions` | Lists any LSP actions for the word under the cursor, that can be triggered with `<cr>` |
| `builtin.lsp_document_diagnostics` | Lists LSP Diagnostics in the current document. | | `builtin.lsp_range_code_actions` | Lists any LSP actions for a given range, that can be triggered with `<cr>` |
| `builtin.lsp_workspace_diagnostics` | Lists LSP Diagnostics in the workspace if supported and otherwise open buffers. | | `builtin.lsp_document_diagnostics` | Lists LSP diagnostics for the current buffer |
| `builtin.lsp_definitions` | Goto definition if there is only one. If there are multiple, open them up in telescope | | `builtin.lsp_workspace_diagnostics` | Lists LSP diagnostics for the current workspace if supported, otherwise searches in all open buffers |
| `builtin.lsp_implementations` | Goto the implementation of the word under the cursor if there's only one, otherwise show all options in Telescope |
| `builtin.lsp_definitions` | Goto the definition of the word under the cursor, if there's only one, otherwise show all options in Telescope |
#### Pre-filtering option for LSP pickers
For the `*_symbols` and `*_diagnostics` LSP pickers, there is a special filtering that you can use to specify your
search. When in insert mode while the picker is open, type `:` and then press `<C-l>` to get an autocomplete menu
filled with all of the possible filters you can use.
i.e. while using the `lsp_document_symbols` picker, adding `:methods:` to your query filters out any document
document symbols that are not recognized as methods by treesitter.
### Git Pickers ### Git Pickers
| Functions | Description | | Functions | Description |
|-------------------------------------|---------------------------------------------------------------------------------------------| |-------------------------------------|---------------------------------------------------------------------------------------------------------------|
| `builtin.git_commits` | Lists git commits with diff preview and on enter checkout the commit. | | `builtin.git_commits` | Lists git commits with diff preview and on enter checkout the commit. |
| `builtin.git_bcommits` | Lists buffer's git commits with diff preview and checkouts it out on enter. | | `builtin.git_bcommits` | Lists buffer's git commits with diff preview and checkouts it out on enter. |
| `builtin.git_branches` | Lists all branches with log preview, checkout action (<cr>), track action (<c-t>) and rebase action(<c-r>). | | `builtin.git_branches` | Lists all branches with log preview, checkout action `<cr>`, track action `<C-t>` and rebase action`<C-r>` |
| `builtin.git_status` | Lists current changes per file with diff preview and add action. (Multi-selection still WIP) | | `builtin.git_status` | Lists current changes per file with diff preview and add action. (Multi-selection still WIP) |
| `builtin.git_stash` | Lists stash items in current repository with ability to apply them on <CR> | | `builtin.git_stash` | Lists stash items in current repository with ability to apply them on `<cr>` |
### Treesitter Picker ### Treesitter Picker
@@ -442,8 +450,8 @@ Built-in functions. Ready to be bound to any key you like. :smile:
### Lists Picker ### Lists Picker
| Functions | Description | | Functions | Description |
|-------------------------------------|---------------------------------------------------------------------------------------------| |-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `builtin.planets` | Use the telescope. | | `builtin.planets` | Use the telescope... |
| `builtin.builtin` | Lists Built-in pickers and run them on enter. | | `builtin.builtin` | Lists Built-in pickers and run them on enter. |
| `builtin.reloader` | Lists lua modules and reload them on enter. | | `builtin.reloader` | Lists lua modules and reload them on enter. |
| `builtin.symbols` | Lists symbols inside a file `data/telescope-sources/*.json` found in your rtp. More info and symbol sources can be found [here](https://github.com/nvim-telescope/telescope-symbols.nvim) | | `builtin.symbols` | Lists symbols inside a file `data/telescope-sources/*.json` found in your rtp. More info and symbol sources can be found [here](https://github.com/nvim-telescope/telescope-symbols.nvim) |
@@ -611,8 +619,8 @@ function my_custom_picker(results)
finder = finders.new_table(results), finder = finders.new_table(results),
sorter = sorters.fuzzy_with_index_bias(), sorter = sorters.fuzzy_with_index_bias(),
attach_mappings = function(_, map) attach_mappings = function(_, map)
-- Map "<CR>" in insert mode to the function, actions.set_command_line -- Map "<cr>" in insert mode to the function, actions.set_command_line
map('i', '<CR>', actions.set_command_line) map('i', '<cr>', actions.set_command_line)
-- If the return value of `attach_mappings` is true, then the other -- If the return value of `attach_mappings` is true, then the other
-- default mappings are still applies. -- default mappings are still applies.
@@ -687,11 +695,11 @@ and some other functions can be easily changed in custom pickers or built-in fun
```lua ```lua
-- Disable preview for find files -- Disable preview for find files
nnoremap <leader>ff :lua require('telescope.builtin').find_files({previewer = false})<CR> nnoremap <leader>ff :lua require('telescope.builtin').find_files({previewer = false})<cr>
-- Change change prompt prefix for find_files builtin function: -- Change change prompt prefix for find_files builtin function:
nnoremap <leader>fg :lua require('telescope.builtin').live_grep({ prompt_prefix=🔍 })<CR> nnoremap <leader>fg :lua require('telescope.builtin').live_grep({ prompt_prefix=🔍 })<cr>
nnoremap <leader>fg :Telescope live_grep prompt_prefix=🔍<CR> nnoremap <leader>fg :Telescope live_grep prompt_prefix=🔍<cr>
``` ```
### How to change Telescope Highlights group? ### How to change Telescope Highlights group?

552
doc/telescope.txt
View File

@@ -269,21 +269,561 @@ actions.open_qflist() *actions.open_qflist()*
================================================================================ ================================================================================
*telescope.builtin* *telescope.builtin*
A collection of builtin pickers for telescope. Telescope Builtins is a collection of community maintained pickers to support
common workflows. It can be used as reference when writing PRs, Telescope
Meant for both example and for easy startup. extensions, your own custom pickers, or just as a discovery tool for all of the
amazing pickers already shipped with Telescope!
Any of these functions can just be called directly by doing: Any of these functions can just be called directly by doing:
:lua require('telescope.builtin').$NAME() :lua require('telescope.builtin').$NAME_OF_PICKER()
To use any of Telescope's default options or any picker-specific options, call
your desired picker by passing a lua table to the picker with all of the
options you want to use. Here's an example with the live_grep picker:
:lua require('telescope.builtin').live_grep({
prompt_title = 'find string in open buffers...',
grep_open_files = true
})
This will use the default configuration options. Other configuration options This will use the default configuration options. Other configuration options
are still in flux at the moment are still in flux at the moment
builtin.live_grep() *builtin.live_grep()* builtin.live_grep({opts}) *builtin.live_grep()*
Live grep means grep as you type. Search for a string in your current working directory and get results live
as you type (respecting .gitignore)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{grep_open_files} (boolean) if true, restrict search to open files
only, mutually exclusive with
`search_dirs`
{search_dirs} (table) directory/directories to search in,
mutually exclusive with `grep_open_files`
builtin.grep_string({opts}) *builtin.grep_string()*
Searches for the string under your cursor in your current working directory
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{search} (string) the query to search
{search_dirs} (table) directory/directories to search in
{use_regex} (boolean) if true, special characters won't be escaped,
allows for using regex (default is false)
builtin.find_files({opts}) *builtin.find_files()*
Lists files in your current working directory, respects .gitignore
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{find_command} (table) command line arguments for `find_files` to
use for the search, overrides default config
{follow} (boolean) if true, follows symlinks (i.e. uses `-L`
flag for the `find` command)
{hidden} (boolean) determines whether to show hidden files or
not (default is false)
{search_dirs} (table) directory/directories to search in
builtin.fd() *builtin.fd()*
This is an alias for the `find_files` picker
builtin.file_browser({opts}) *builtin.file_browser()*
Lists files and folders in your current working directory, open files,
navigate your filesystem, and create new files and folders
- Default keymaps:
- `<cr>`: opens the currently selected file, or navigates to the
currently selected directory
- `<C-e>`: creates new file in current directory, creates new directory
if the name contains a trailing '/'
- Note: you can create files nested into several directories with
`<C-e>`, i.e. `lua/telescope/init.lua` would 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
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{search_dirs} (table) directory/directories to search in
builtin.treesitter() *builtin.treesitter()*
Lists function names, variables, and other symbols from treesitter queries
Fields: ~
{show_line} (boolean) if true, shows the row:column that the result is
found at (default is true)
builtin.current_buffer_fuzzy_find({opts})*builtin.current_buffer_fuzzy_find()*
Live fuzzy search inside of the currently open buffer
Parameters: ~
{opts} (table) options to pass to the picker
builtin.tags({opts}) *builtin.tags()*
Lists tags in current directory with tag location file preview (users are
required to run ctags -R to generate tags or update when introducing new
changes)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{ctags_file} (string) specify a particular ctags file to use
{show_line} (boolean) if true, shows the content of the line the
tag is found on in the picker (default is
true)
{shorten_path} (boolean) if true, makes file paths shown in picker
use one letter for folders (default is true)
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is false)
builtin.current_buffer_tags({opts}) *builtin.current_buffer_tags()*
Lists all of the tags for the currently open buffer, with a preview
Parameters: ~
{opts} (table) options to pass to the picker
builtin.git_files({opts}) *builtin.git_files()*
Fuzzy search for files tracked by Git. This command lists the output of the
`git ls-files` command, respects .gitignore, and optionally ignores
untracked files
- Default keymaps:
- `<cr>`: opens the currently selected file
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{show_untracked} (boolean) if true, adds `--others` flag to
command and shows untracked files
(default is true)
{recurse_submodules} (boolean) if true, adds the
`--recurse-submodules` flag to command
(default is false)
builtin.git_commits({opts}) *builtin.git_commits()*
Lists commits for current directory with diff preview
- Default keymaps:
- `<cr>`: checks out the currently selected commit
Parameters: ~
{opts} (table) options to pass to the picker
builtin.git_bcommits({opts}) *builtin.git_bcommits()*
Lists commits for current buffer with diff preview
- Default keymaps:
- `<cr>`: checks out the currently selected commit
Parameters: ~
{opts} (table) options to pass to the picker
builtin.git_branches({opts}) *builtin.git_branches()*
List branches for current directory, with output from `git log --oneline`
shown in the preview window
- Default keymaps:
- `<cr>`: checks out the currently selected branch
- `<C-t>`: tracks currently selected branch
- `<C-r>`: rebases currently selected branch
- `<C-a>`: creates a new branch, with confirmation prompt before creation
- `<C-d>`: deletes the currently selected branch, with confirmation
prompt before deletion
Parameters: ~
{opts} (table) options to pass to the picker
builtin.git_status({opts}) *builtin.git_status()*
Lists git status for current directory
- Default keymaps:
- `<Tab>`: stages or unstages the currently selected file
- `<cr>`: opens the currently selected file
Parameters: ~
{opts} (table) options to pass to the picker
builtin.git_stash({opts}) *builtin.git_stash()*
Lists stash items in current repository
- Default keymaps:
- `<cr>`: runs `git apply` for currently selected stash
Parameters: ~
{opts} (table) options to pass to the picker
builtin.builtin({opts}) *builtin.builtin()*
Lists all of the community maintained pickers built into Telescope
Parameters: ~
{opts} (table) options to pass to the picker
builtin.planets({opts}) *builtin.planets()*
Use the telescope...
Parameters: ~
{opts} (table) options to pass to the picker
builtin.symbols({opts}) *builtin.symbols()*
Lists symbols inside of data/telescope-sources/*.json found in your runtime
path. Check README for more info
Parameters: ~
{opts} (table) options to pass to the picker
builtin.commands({opts}) *builtin.commands()*
Lists available plugin/user commands and runs them on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.quickfix({opts}) *builtin.quickfix()*
Lists items in the quickfix list, jumps to location on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.loclist({opts}) *builtin.loclist()*
Lists items from the current window's location list, jumps to location on
`<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.oldfiles({opts}) *builtin.oldfiles()*
Lists previously open files, opens on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.command_history({opts}) *builtin.command_history()*
Lists commands that were executed recently, and reruns them on `<cr>`
- Default keymaps:
- `<C-e>`: open the command line with the text of the currently selected
result populated in it
Parameters: ~
{opts} (table) options to pass to the picker
builtin.search_history({opts}) *builtin.search_history()*
Lists searches that were executed recently, and reruns them on `<cr>`
- Default keymaps:
- `<C-e>`: open a search window with the text of the currently selected
search result populated in it
Parameters: ~
{opts} (table) options to pass to the picker
builtin.vim_options({opts}) *builtin.vim_options()*
Lists vim options, allows you to edit the current value on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.help_tags({opts}) *builtin.help_tags()*
Lists available help tags and opens a new window with the relevant help
info on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.man_pages({opts}) *builtin.man_pages()*
Lists manpage entries, opens them in a help window on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.reloader({opts}) *builtin.reloader()*
Lists lua modules and reloads them on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.buffers({opts}) *builtin.buffers()*
Lists open buffers in current neovim instance, opens selected buffer on
`<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.colorscheme({opts}) *builtin.colorscheme()*
Lists available colorschemes and applies them on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.marks({opts}) *builtin.marks()*
Lists vim marks and their value, jumps to the mark on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.registers({opts}) *builtin.registers()*
Lists vim registers, pastes the contents of the register on `<cr>`
- Default keymaps:
- `<C-e>`: edit the contents of the currently selected register
Parameters: ~
{opts} (table) options to pass to the picker
builtin.keymaps({opts}) *builtin.keymaps()*
Lists normal mode keymappings, runs the selected keymap on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.filetypes({opts}) *builtin.filetypes()*
Lists all available filetypes, sets currently open buffer's filetype to
selected filetype in Telescope on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.highlights({opts}) *builtin.highlights()*
Lists all available highlights
Parameters: ~
{opts} (table) options to pass to the picker
builtin.autocommands({opts}) *builtin.autocommands()*
Lists vim autocommands and goes to their declaration on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.spell_suggest({opts}) *builtin.spell_suggest()*
Lists spelling suggestions for the current word under the cursor, replaces
word with selected suggestion on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.tagstack({opts}) *builtin.tagstack()*
Lists the tag stack for the current window, jumps to tag on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{shorten_path} (boolean) if true, makes file paths shown in picker
use one letter for folders (default is true)
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is true)
builtin.jumplist({opts}) *builtin.jumplist()*
Lists items from Vim's jumplist, jumps to location on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.lsp_references({opts}) *builtin.lsp_references()*
Lists LSP references for word under the cursor, jumps to reference on
`<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{shorten_path} (boolean) if true, makes file paths shown in picker use
one letter for folders (default is false)
builtin.lsp_definitions({opts}) *builtin.lsp_definitions()*
Goto the definition of the word under the cursor, if there's only one,
otherwise show all options in Telescope
Parameters: ~
{opts} (table) options to pass to the picker
builtin.lsp_implementations({opts}) *builtin.lsp_implementations()*
Goto the implementation of the word under the cursor if there's only one,
otherwise show all options in Telescope
Parameters: ~
{opts} (table) options to pass to the picker
builtin.lsp_code_actions({opts}) *builtin.lsp_code_actions()*
Lists any LSP actions for the word under the cursor which can be triggered
with `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.lsp_range_code_actions({opts}) *builtin.lsp_range_code_actions()*
Lists any LSP actions for a given range, that can be triggered with `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.lsp_document_symbols({opts}) *builtin.lsp_document_symbols()*
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:`)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{ignore_filename} (type) string with file to ignore
builtin.lsp_workspace_symbols({opts}) *builtin.lsp_workspace_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:`)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{shorten_path} (boolean) if true, makes file paths shown in picker
use one letter for folders (default is
false)
{ignore_filename} (string) file(s) to ignore
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is false)
builtin.lsp_dynamic_workspace_symbols({opts})*builtin.lsp_dynamic_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:`)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is false)
builtin.lsp_document_diagnostics({opts}) *builtin.lsp_document_diagnostics()*
Lists LSP diagnostics for the current buffer
- Default keymaps:
- `<C-l>`: show autocompletion menu to prefilter your query with the
diagnostic you want to see (i.e. `:warning:`)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is false)
builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()*
Lists LSP diagnostics for the current workspace if supported, otherwise
searches in all open buffers
- Default keymaps:
- `<C-l>`: show autocompletion menu to prefilter your query with the
diagnostic you want to see (i.e. `:warning:`)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is false)
================================================================================ ================================================================================

4
lua/telescope/builtin/files.lua
View File

@@ -93,7 +93,6 @@ files.live_grep = function(opts)
}):find() }):find()
end end
-- Special keys: -- Special keys:
-- opts.search -- the string to search. -- opts.search -- the string to search.
-- opts.search_dirs -- list of directory to search in -- opts.search_dirs -- list of directory to search in
@@ -135,7 +134,7 @@ files.grep_string = function(opts)
end end
-- TODO: Maybe just change this to `find`. -- TODO: Maybe just change this to `find`.
-- Support `find` and maybe let people do other stuff with it as well. -- TODO: Support `find` and maybe let people do other stuff with it as well.
files.find_files = function(opts) files.find_files = function(opts)
local find_command = opts.find_command local find_command = opts.find_command
local hidden = opts.hidden local hidden = opts.hidden
@@ -311,6 +310,7 @@ files.file_browser = function(opts)
}):find() }):find()
end end
-- TODO: finish docs for opts.show_line
files.treesitter = function(opts) files.treesitter = function(opts)
opts.show_line = utils.get_default(opts.show_line, true) opts.show_line = utils.get_default(opts.show_line, true)

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

@@ -1,16 +1,25 @@
---@tag telescope.builtin ---@tag telescope.builtin
---@brief [[ ---@brief [[
--- A collection of builtin pickers for telescope. --- 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
--- Meant for both example and for easy startup. --- the amazing pickers already shipped with Telescope!
--- ---
--- Any of these functions can just be called directly by doing: --- Any of these functions can just be called directly by doing:
--- ---
--- :lua require('telescope.builtin').$NAME() --- :lua require('telescope.builtin').$NAME_OF_PICKER()
--- ---
--- This will use the default configuration options. --- To use any of Telescope's default options or any picker-specific options, call your desired picker by passing a lua
--- Other configuration options are still in flux at the moment --- table to the picker with all of the options you want to use. Here's an example with the live_grep picker:
---
--- <pre>
--- :lua require('telescope.builtin').live_grep({
--- prompt_title = 'find string in open buffers...',
--- grep_open_files = true
--- })
--- </pre>
---
--- This will use the default configuration options. Other configuration options are still in flux at the moment
---@brief ]] ---@brief ]]
if 1 ~= vim.fn.has('nvim-0.5') then if 1 ~= vim.fn.has('nvim-0.5') then
@@ -21,60 +30,291 @@ end
local builtin = {} local builtin = {}
--- Live grep means grep as you type. --
--
-- File-related Pickers
--
--
--- Search for a string in your current working directory and get results live as you type (respecting .gitignore)
---@param opts table: options to pass to the picker
---@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`
builtin.live_grep = require('telescope.builtin.files').live_grep builtin.live_grep = require('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 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)
builtin.grep_string = require('telescope.builtin.files').grep_string builtin.grep_string = require('telescope.builtin.files').grep_string
--- Lists files in your current working directory, respects .gitignore
---@param opts table: options to pass to the picker
---@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 search_dirs table: directory/directories to search in
builtin.find_files = require('telescope.builtin.files').find_files builtin.find_files = require('telescope.builtin.files').find_files
--- This is an alias for the `find_files` picker
builtin.fd = builtin.find_files builtin.fd = builtin.find_files
--- Lists files and folders in your current working directory, open files, navigate your filesystem, and create new
--- files and folders
--- - Default keymaps:
--- - `<cr>`: opens the currently selected file, or navigates to the currently selected directory
--- - `<C-e>`: creates new file in current directory, creates new directory if the name contains a trailing '/'
--- - Note: you can create files nested into several directories with `<C-e>`, i.e. `lua/telescope/init.lua` would
--- 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 search_dirs table: directory/directories to search in
builtin.file_browser = require('telescope.builtin.files').file_browser builtin.file_browser = require('telescope.builtin.files').file_browser
--- Lists function names, variables, and other symbols from treesitter queries
---@field show_line boolean: if true, shows the row:column that the result is found at (default is true)
builtin.treesitter = require('telescope.builtin.files').treesitter builtin.treesitter = require('telescope.builtin.files').treesitter
--- Live fuzzy search inside of the currently open buffer
---@param opts table: options to pass to the picker
builtin.current_buffer_fuzzy_find = require('telescope.builtin.files').current_buffer_fuzzy_find builtin.current_buffer_fuzzy_find = require('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 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 shorten_path boolean: if true, makes file paths shown in picker use one letter for folders (default is true)
---@field hide_filename boolean: if true, hides the name of the file in the current picker (default is false)
builtin.tags = require('telescope.builtin.files').tags builtin.tags = require('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
builtin.current_buffer_tags = require('telescope.builtin.files').current_buffer_tags builtin.current_buffer_tags = require('telescope.builtin.files').current_buffer_tags
--
--
-- Git-related Pickers
--
--
--- Fuzzy search for files tracked by Git. This command lists the output of the `git ls-files` command, respects
--- .gitignore, and optionally ignores untracked 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)
builtin.git_files = require('telescope.builtin.git').files builtin.git_files = require('telescope.builtin.git').files
--- Lists commits for current directory with diff preview
--- - Default keymaps:
--- - `<cr>`: checks out the currently selected commit
---@param opts table: options to pass to the picker
builtin.git_commits = require('telescope.builtin.git').commits builtin.git_commits = require('telescope.builtin.git').commits
--- Lists commits for current buffer with diff preview
--- - Default keymaps:
--- - `<cr>`: checks out the currently selected commit
---@param opts table: options to pass to the picker
builtin.git_bcommits = require('telescope.builtin.git').bcommits builtin.git_bcommits = require('telescope.builtin.git').bcommits
--- List branches for current directory, with output from `git log --oneline` shown in the preview window
--- - Default keymaps:
--- - `<cr>`: checks out the currently selected branch
--- - `<C-t>`: tracks currently selected branch
--- - `<C-r>`: rebases currently selected branch
--- - `<C-a>`: creates a new branch, with confirmation prompt before creation
--- - `<C-d>`: deletes the currently selected branch, with confirmation prompt before deletion
---@param opts table: options to pass to the picker
builtin.git_branches = require('telescope.builtin.git').branches builtin.git_branches = require('telescope.builtin.git').branches
--- Lists git status for current directory
--- - Default keymaps:
--- - `<Tab>`: stages or unstages the currently selected file
--- - `<cr>`: opens the currently selected file
---@param opts table: options to pass to the picker
builtin.git_status = require('telescope.builtin.git').status builtin.git_status = require('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
builtin.git_stash = require('telescope.builtin.git').stash builtin.git_stash = require('telescope.builtin.git').stash
--
--
-- Internal and Vim-related Pickers
--
--
--- Lists all of the community maintained pickers built into Telescope
---@param opts table: options to pass to the picker
builtin.builtin = require('telescope.builtin.internal').builtin builtin.builtin = require('telescope.builtin.internal').builtin
--- Use the telescope...
---@param opts table: options to pass to the picker
builtin.planets = require('telescope.builtin.internal').planets builtin.planets = require('telescope.builtin.internal').planets
--- Lists symbols inside of data/telescope-sources/*.json found in your runtime path. Check README for more info
---@param opts table: options to pass to the picker
builtin.symbols = require('telescope.builtin.internal').symbols builtin.symbols = require('telescope.builtin.internal').symbols
--- Lists available plugin/user commands and runs them on `<cr>`
---@param opts table: options to pass to the picker
builtin.commands = require('telescope.builtin.internal').commands builtin.commands = require('telescope.builtin.internal').commands
--- Lists items in the quickfix list, jumps to location on `<cr>`
---@param opts table: options to pass to the picker
builtin.quickfix = require('telescope.builtin.internal').quickfix builtin.quickfix = require('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
builtin.loclist = require('telescope.builtin.internal').loclist builtin.loclist = require('telescope.builtin.internal').loclist
--- Lists previously open files, opens on `<cr>`
---@param opts table: options to pass to the picker
builtin.oldfiles = require('telescope.builtin.internal').oldfiles builtin.oldfiles = require('telescope.builtin.internal').oldfiles
--- Lists commands that were executed recently, and reruns them on `<cr>`
--- - Default keymaps:
--- - `<C-e>`: open the command line with the text of the currently selected result populated in it
---@param opts table: options to pass to the picker
builtin.command_history = require('telescope.builtin.internal').command_history builtin.command_history = require('telescope.builtin.internal').command_history
--- Lists searches that were executed recently, and reruns them on `<cr>`
--- - Default keymaps:
--- - `<C-e>`: open a search window with the text of the currently selected search result populated in it
---@param opts table: options to pass to the picker
builtin.search_history = require('telescope.builtin.internal').search_history builtin.search_history = require('telescope.builtin.internal').search_history
--- 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('telescope.builtin.internal').vim_options builtin.vim_options = require('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
builtin.help_tags = require('telescope.builtin.internal').help_tags builtin.help_tags = require('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
builtin.man_pages = require('telescope.builtin.internal').man_pages builtin.man_pages = require('telescope.builtin.internal').man_pages
--- Lists lua modules and reloads them on `<cr>`
---@param opts table: options to pass to the picker
builtin.reloader = require('telescope.builtin.internal').reloader builtin.reloader = require('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
builtin.buffers = require('telescope.builtin.internal').buffers builtin.buffers = require('telescope.builtin.internal').buffers
--- Lists available colorschemes and applies them on `<cr>`
---@param opts table: options to pass to the picker
builtin.colorscheme = require('telescope.builtin.internal').colorscheme builtin.colorscheme = require('telescope.builtin.internal').colorscheme
--- Lists vim marks and their value, jumps to the mark on `<cr>`
---@param opts table: options to pass to the picker
builtin.marks = require('telescope.builtin.internal').marks builtin.marks = require('telescope.builtin.internal').marks
--- Lists vim registers, pastes the contents of the register on `<cr>`
--- - Default keymaps:
--- - `<C-e>`: edit the contents of the currently selected register
---@param opts table: options to pass to the picker
builtin.registers = require('telescope.builtin.internal').registers builtin.registers = require('telescope.builtin.internal').registers
--- Lists normal mode keymappings, runs the selected keymap on `<cr>`
---@param opts table: options to pass to the picker
builtin.keymaps = require('telescope.builtin.internal').keymaps builtin.keymaps = require('telescope.builtin.internal').keymaps
--- Lists all available filetypes, sets currently open buffer's filetype to selected filetype in Telescope on `<cr>`
---@param opts table: options to pass to the picker
builtin.filetypes = require('telescope.builtin.internal').filetypes builtin.filetypes = require('telescope.builtin.internal').filetypes
--- Lists all available highlights
---@param opts table: options to pass to the picker
builtin.highlights = require('telescope.builtin.internal').highlights builtin.highlights = require('telescope.builtin.internal').highlights
--- Lists vim autocommands and goes to their declaration on `<cr>`
---@param opts table: options to pass to the picker
builtin.autocommands = require('telescope.builtin.internal').autocommands builtin.autocommands = require('telescope.builtin.internal').autocommands
--- Lists spelling suggestions for the current word under the cursor, replaces word with selected suggestion on `<cr>`
---@param opts table: options to pass to the picker
builtin.spell_suggest = require('telescope.builtin.internal').spell_suggest builtin.spell_suggest = require('telescope.builtin.internal').spell_suggest
--- Lists the tag stack for the current window, jumps to tag on `<cr>`
---@param opts table: options to pass to the picker
---@field shorten_path boolean: if true, makes file paths shown in picker use one letter for folders (default is true)
---@field hide_filename boolean: if true, hides the name of the file in the current picker (default is true)
builtin.tagstack = require('telescope.builtin.internal').tagstack builtin.tagstack = require('telescope.builtin.internal').tagstack
--- Lists items from Vim's jumplist, jumps to location on `<cr>`
---@param opts table: options to pass to the picker
builtin.jumplist = require('telescope.builtin.internal').jumplist builtin.jumplist = require('telescope.builtin.internal').jumplist
--
--
-- LSP-related Pickers
--
--
--- Lists LSP references for word under the cursor, jumps to reference on `<cr>`
---@param opts table: options to pass to the picker
---@field shorten_path boolean: if true, makes file paths shown in picker use one letter for folders (default is false)
builtin.lsp_references = require('telescope.builtin.lsp').references builtin.lsp_references = require('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
builtin.lsp_definitions = require('telescope.builtin.lsp').definitions builtin.lsp_definitions = require('telescope.builtin.lsp').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
builtin.lsp_implementations = require('telescope.builtin.lsp').implementations builtin.lsp_implementations = require('telescope.builtin.lsp').implementations
builtin.lsp_document_symbols = require('telescope.builtin.lsp').document_symbols
--- 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
builtin.lsp_code_actions = require('telescope.builtin.lsp').code_actions builtin.lsp_code_actions = require('telescope.builtin.lsp').code_actions
builtin.lsp_document_diagnostics = require('telescope.builtin.lsp').diagnostics
builtin.lsp_workspace_diagnostics = require('telescope.builtin.lsp').workspace_diagnostics --- Lists any LSP actions for a given range, that can be triggered with `<cr>`
---@param opts table: options to pass to the picker
builtin.lsp_range_code_actions = require('telescope.builtin.lsp').range_code_actions builtin.lsp_range_code_actions = require('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
builtin.lsp_document_symbols = require('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 shorten_path boolean: if true, makes file paths shown in picker use one letter for folders (default is false)
---@field ignore_filename string: file(s) to ignore
---@field hide_filename boolean: if true, hides the name of the file in the current picker (default is false)
builtin.lsp_workspace_symbols = require('telescope.builtin.lsp').workspace_symbols builtin.lsp_workspace_symbols = require('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 hide_filename boolean: if true, hides the name of the file in the current picker (default is false)
builtin.lsp_dynamic_workspace_symbols = require('telescope.builtin.lsp').dynamic_workspace_symbols builtin.lsp_dynamic_workspace_symbols = require('telescope.builtin.lsp').dynamic_workspace_symbols
--- Lists LSP diagnostics for the current buffer
--- - Default keymaps:
--- - `<C-l>`: show autocompletion menu to prefilter your query with the diagnostic you want to see (i.e. `:warning:`)
---@param opts table: options to pass to the picker
---@field hide_filename boolean: if true, hides the name of the file in the current picker (default is false)
builtin.lsp_document_diagnostics = require('telescope.builtin.lsp').diagnostics
--- Lists LSP diagnostics for the current workspace if supported, otherwise searches in all open buffers
--- - Default keymaps:
--- - `<C-l>`: show autocompletion menu to prefilter your query with the diagnostic you want to see (i.e. `:warning:`)
---@param opts table: options to pass to the picker
---@field hide_filename boolean: if true, hides the name of the file in the current picker (default is false)
builtin.lsp_workspace_diagnostics = require('telescope.builtin.lsp').workspace_diagnostics
return builtin return builtin