diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7706c09..e6ae7a5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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: diff --git a/README.md b/README.md index 1077886..0996c94 100644 --- a/README.md +++ b/README.md @@ -245,7 +245,7 @@ Many familiar mapping patterns are setup as defaults. | `/` | Next item | | `/` | Previous item | | `j/k` | Next/previous (in normal mode) | -| `` | Confirm selection | +| `` | Confirm selection | | `` | go to file selection as a split | | `` | go to file selection as a vsplit | | `` | go to a file in a new tab | @@ -292,10 +292,10 @@ require('telescope').setup{ [""] = actions.select_horizontal, -- Add up multiple actions - [""] = actions.select_default + actions.center, + [""] = actions.select_default + actions.center, -- You can perform as many actions in a row as you like - [""] = actions.select_default + actions.center + my_cool_custom_action, + [""] = actions.select_default + actions.center + my_cool_custom_action, }, n = { [""] = actions.close, @@ -366,13 +366,13 @@ Built-in functions. Ready to be bound to any key you like. :smile: ### File Pickers -| Functions | Description | -|-------------------------------------|---------------------------------------------------------------------------------------------| -| `builtin.find_files` | Lists Files in current directory. | -| `builtin.git_files` | Lists Git files in current directory. | -| `builtin.grep_string` | Searches for a string under the cursor in current directory. | -| `builtin.live_grep` | Searches in current directory files. (respecting .gitignore) | -| `builtin.file_browser` | Ivy-like file explorer. Creates files by typing in filename and pressing ``. Press `` without prompt for more info | +| Functions | Description | +|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| `builtin.find_files` | Lists files in your current working directory, respects .gitignore | +| `builtin.git_files` | Fuzzy search through the output of `git ls-files` command, respects .gitignore, optionally ignores untracked files | +| `builtin.grep_string` | Searches for the string under your cursor in your current working directory | +| `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 @@ -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 | | `search_dirs` | List of directories to search in, mutually exclusive with `grep_open_files` | list | - ### Vim Pickers -| Functions | Description | -|-------------------------------------|---------------------------------------------------------------------------------------------| -| `builtin.buffers` | Lists Open buffers in the current vim instance. | -| `builtin.oldfiles` | Lists Previously open files. | -| `builtin.commands` | Lists Available plugin/user commands and run it. | -| `builtin.tags` | Lists Tags in current directory with preview (ctags -R). | -| `builtin.tagstack` | Lists Tagstack entries. | -| `builtin.command_history` | Lists Commands previously ran and run it on enter. | -| `builtin.search_history` | Lists Searches previously ran and run it on enter. | -| `builtin.help_tags` | Lists Available help tags and open help document. | -| `builtin.man_pages` | Lists Man entries. | -| `builtin.marks` | Lists Markers and their value. | -| `builtin.colorscheme` | Lists Colorscheme and switch to it on enter. | -| `builtin.quickfix` | Lists items from quickfix. | -| `builtin.loclist` | Lists items from current window's location list. | -| `builtin.jumplist` | Lists Jump List entries. | -| `builtin.vim_options` | Lists vim options and on enter edit the options value. | -| `builtin.registers` | Lists vim registers and edit or paste selection. | -| `builtin.autocommands` | Lists vim autocommands and go to their declaration. | -| `builtin.spell_suggest` | Lists spelling suggestions for . | -| `builtin.keymaps` | Lists normal-mode mappings. | -| `builtin.filetypes` | Lists all filetypes. | -| `builtin.highlights` | Lists all highlights. | -| `builtin.current_buffer_fuzzy_find` | Searches in current buffer lines. | -| `builtin.current_buffer_tags` | Lists Tags in current buffer. | +| Functions | Description | +|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `builtin.buffers` | Lists open buffers in current neovim instance | +| `builtin.oldfiles` | Lists previously open files | +| `builtin.commands` | Lists available plugin/user commands and runs them on `` | +| `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.command_history` | Lists commands that were executed recently, and reruns them on `` | +| `builtin.search_history` | Lists searches that were executed recently, and reruns them on `` | +| `builtin.help_tags` | Lists available help tags and opens a new window with the relevant help info on `` | +| `builtin.man_pages` | Lists manpage entries, opens them in a help window on `` | +| `builtin.marks` | Lists vim marks and their value | +| `builtin.colorscheme` | Lists available colorschemes and applies them on `` | +| `builtin.quickfix` | Lists items in the quickfix list | +| `builtin.loclist` | Lists items from the current window's location list | +| `builtin.vim_options` | Lists vim options, allows you to edit the current value on `` | +| `builtin.registers` | Lists vim registers, pastes the contents of the register on `` | +| `builtin.autocommands` | Lists vim autocommands and goes to their declaration on `` | +| `builtin.spell_suggest` | Lists spelling suggestions for the current word under the cursor, replaces word with selected suggestion on `` | +| `builtin.keymaps` | Lists normal mode keymappings | +| `builtin.filetypes` | Lists all available filetypes | +| `builtin.highlights` | Lists all available highlights | +| `builtin.current_buffer_fuzzy_find` | Live fuzzy search inside of the currently open buffer | +| `builtin.current_buffer_tags` | Lists all of the tags for the currently open buffer, with a preview | -### LSP Pickers +### Neovim LSP Pickers -| Functions | Description | -|-------------------------------------|---------------------------------------------------------------------------------------------| -| `builtin.lsp_references` | Searches in LSP references. | -| `builtin.lsp_document_symbols` | Searches in LSP Document Symbols in the current document. | -| `builtin.lsp_workspace_symbols` | Searches in LSP all workspace symbols. | -| `builtin.lsp_code_actions` | Lists LSP action to be trigged on enter. | -| `builtin.lsp_range_code_actions` | Lists LSP range code action to be trigged on enter. | -| `builtin.lsp_document_diagnostics` | Lists LSP Diagnostics in the current document. | -| `builtin.lsp_workspace_diagnostics` | Lists LSP Diagnostics in the workspace if supported and otherwise open buffers. | -| `builtin.lsp_definitions` | Goto definition if there is only one. If there are multiple, open them up in telescope | +| Functions | Description | +|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------| +| `builtin.lsp_references` | Lists LSP references for word under the cursor | +| `builtin.lsp_document_symbols` | Lists LSP document symbols in the current buffer | +| `builtin.lsp_workspace_symbols` | Lists LSP document symbols in the current workspace | +| `builtin.lsp_dynamic_workspace_symbols` | Dynamically Lists LSP for all workspace symbols | +| `builtin.lsp_code_actions` | Lists any LSP actions for the word under the cursor, that can be triggered with `` | +| `builtin.lsp_range_code_actions` | Lists any LSP actions for a given range, that can be triggered with `` | +| `builtin.lsp_document_diagnostics` | Lists LSP diagnostics for the current buffer | +| `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 `` 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 -| Functions | Description | -|-------------------------------------|---------------------------------------------------------------------------------------------| -| `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_branches` | Lists all branches with log preview, checkout action (), track action () and rebase action(). | -| `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 | +| Functions | Description | +|-------------------------------------|---------------------------------------------------------------------------------------------------------------| +| `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_branches` | Lists all branches with log preview, checkout action ``, track action `` and rebase action`` | +| `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 `` | ### Treesitter Picker @@ -441,11 +449,11 @@ Built-in functions. Ready to be bound to any key you like. :smile: ### Lists Picker -| Functions | Description | -|-------------------------------------|---------------------------------------------------------------------------------------------| -| `builtin.planets` | Use the telescope. | -| `builtin.builtin` | Lists Built-in pickers and run them on enter. | -| `builtin.reloader` | Lists lua modules and reload them on enter. | +| Functions | Description | +|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `builtin.planets` | Use the telescope... | +| `builtin.builtin` | Lists Built-in pickers and run 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) | ## Previewers @@ -611,8 +619,8 @@ function my_custom_picker(results) finder = finders.new_table(results), sorter = sorters.fuzzy_with_index_bias(), attach_mappings = function(_, map) - -- Map "" in insert mode to the function, actions.set_command_line - map('i', '', actions.set_command_line) + -- Map "" in insert mode to the function, actions.set_command_line + map('i', '', actions.set_command_line) -- If the return value of `attach_mappings` is true, then the other -- default mappings are still applies. @@ -687,11 +695,11 @@ and some other functions can be easily changed in custom pickers or built-in fun ```lua -- Disable preview for find files -nnoremap ff :lua require('telescope.builtin').find_files({previewer = false}) +nnoremap ff :lua require('telescope.builtin').find_files({previewer = false}) -- Change change prompt prefix for find_files builtin function: -nnoremap fg :lua require('telescope.builtin').live_grep({ prompt_prefix=🔍 }) -nnoremap fg :Telescope live_grep prompt_prefix=🔍 +nnoremap fg :lua require('telescope.builtin').live_grep({ prompt_prefix=🔍 }) +nnoremap fg :Telescope live_grep prompt_prefix=🔍 ``` ### How to change Telescope Highlights group? diff --git a/doc/telescope.txt b/doc/telescope.txt index e82bfb4..56cb6c8 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -269,21 +269,561 @@ actions.open_qflist() *actions.open_qflist()* ================================================================================ *telescope.builtin* -A collection of builtin pickers for telescope. - -Meant for both example and for easy startup. +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 the +amazing pickers already shipped with Telescope! 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 are still in flux at the moment -builtin.live_grep() *builtin.live_grep()* - Live grep means grep as you type. +builtin.live_grep({opts}) *builtin.live_grep()* + 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: + - ``: opens the currently selected file, or navigates to the + currently selected directory + - ``: 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 + ``, 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: + - ``: 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: + - ``: 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: + - ``: 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: + - ``: checks out the currently selected branch + - ``: tracks currently selected branch + - ``: rebases currently selected branch + - ``: creates a new branch, with confirmation prompt before creation + - ``: 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: + - ``: stages or unstages the currently selected file + - ``: 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: + - ``: 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 `` + + + Parameters: ~ + {opts} (table) options to pass to the picker + + +builtin.quickfix({opts}) *builtin.quickfix()* + Lists items in the quickfix list, jumps to location on `` + + + 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 + `` + + + Parameters: ~ + {opts} (table) options to pass to the picker + + +builtin.oldfiles({opts}) *builtin.oldfiles()* + Lists previously open files, opens on `` + + + 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 `` + - Default keymaps: + - ``: 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 `` + - Default keymaps: + - ``: 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 `` + + + 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 `` + + + 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 `` + + + Parameters: ~ + {opts} (table) options to pass to the picker + + +builtin.reloader({opts}) *builtin.reloader()* + Lists lua modules and reloads them on `` + + + 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 + `` + + + Parameters: ~ + {opts} (table) options to pass to the picker + + +builtin.colorscheme({opts}) *builtin.colorscheme()* + Lists available colorschemes and applies them on `` + + + 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 `` + + + Parameters: ~ + {opts} (table) options to pass to the picker + + +builtin.registers({opts}) *builtin.registers()* + Lists vim registers, pastes the contents of the register on `` + - Default keymaps: + - ``: 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 `` + + + 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 `` + + + 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 `` + + + 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 `` + + + 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 `` + + + 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 `` + + + 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 + `` + + + 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 `` + + + 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 `` + + + 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: + - ``: 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: + - ``: 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: + - ``: 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: + - ``: 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: + - ``: 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) + ================================================================================ diff --git a/lua/telescope/builtin/files.lua b/lua/telescope/builtin/files.lua index d77895a..321e156 100644 --- a/lua/telescope/builtin/files.lua +++ b/lua/telescope/builtin/files.lua @@ -93,7 +93,6 @@ files.live_grep = function(opts) }):find() end - -- Special keys: -- opts.search -- the string to search. -- opts.search_dirs -- list of directory to search in @@ -135,7 +134,7 @@ files.grep_string = function(opts) end -- 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) local find_command = opts.find_command local hidden = opts.hidden @@ -311,6 +310,7 @@ files.file_browser = function(opts) }):find() end +-- TODO: finish docs for opts.show_line files.treesitter = function(opts) opts.show_line = utils.get_default(opts.show_line, true) diff --git a/lua/telescope/builtin/init.lua b/lua/telescope/builtin/init.lua index 8499c5c..2dd384a 100644 --- a/lua/telescope/builtin/init.lua +++ b/lua/telescope/builtin/init.lua @@ -1,16 +1,25 @@ ---@tag telescope.builtin ---@brief [[ ---- A collection of builtin pickers for telescope. ---- ---- Meant for both example and for easy startup. +--- 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 +--- the amazing pickers already shipped with Telescope! --- --- 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. ---- Other configuration options are still in flux at the moment +--- 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 are still in flux at the moment ---@brief ]] if 1 ~= vim.fn.has('nvim-0.5') then @@ -21,60 +30,291 @@ end 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 +--- 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 + +--- 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 + +--- This is an alias for the `find_files` picker 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: +--- - ``: opens the currently selected file, or navigates to the currently selected directory +--- - ``: 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 ``, 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 + +--- 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 + +--- 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 + +--- 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 + +--- 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 +-- +-- +-- 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: +--- - ``: 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 + +--- Lists commits for current directory with diff preview +--- - Default keymaps: +--- - ``: checks out the currently selected commit +---@param opts table: options to pass to the picker builtin.git_commits = require('telescope.builtin.git').commits + +--- Lists commits for current buffer with diff preview +--- - Default keymaps: +--- - ``: checks out the currently selected commit +---@param opts table: options to pass to the picker 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: +--- - ``: checks out the currently selected branch +--- - ``: tracks currently selected branch +--- - ``: rebases currently selected branch +--- - ``: creates a new branch, with confirmation prompt before creation +--- - ``: 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 + +--- Lists git status for current directory +--- - Default keymaps: +--- - ``: stages or unstages the currently selected file +--- - ``: opens the currently selected file +---@param opts table: options to pass to the picker builtin.git_status = require('telescope.builtin.git').status + +--- Lists stash items in current repository +--- - Default keymaps: +--- - ``: runs `git apply` for currently selected stash +---@param opts table: options to pass to the picker 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 +--- Use the telescope... +---@param opts table: options to pass to the picker 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 + +--- Lists available plugin/user commands and runs them on `` +---@param opts table: options to pass to the picker builtin.commands = require('telescope.builtin.internal').commands + +--- Lists items in the quickfix list, jumps to location on `` +---@param opts table: options to pass to the picker builtin.quickfix = require('telescope.builtin.internal').quickfix + +--- Lists items from the current window's location list, jumps to location on `` +---@param opts table: options to pass to the picker builtin.loclist = require('telescope.builtin.internal').loclist + +--- Lists previously open files, opens on `` +---@param opts table: options to pass to the picker builtin.oldfiles = require('telescope.builtin.internal').oldfiles + +--- Lists commands that were executed recently, and reruns them on `` +--- - Default keymaps: +--- - ``: 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 + +--- Lists searches that were executed recently, and reruns them on `` +--- - Default keymaps: +--- - ``: 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 + +--- Lists vim options, allows you to edit the current value on `` +---@param opts table: options to pass to the picker builtin.vim_options = require('telescope.builtin.internal').vim_options + +--- Lists available help tags and opens a new window with the relevant help info on `` +---@param opts table: options to pass to the picker builtin.help_tags = require('telescope.builtin.internal').help_tags + +--- Lists manpage entries, opens them in a help window on `` +---@param opts table: options to pass to the picker builtin.man_pages = require('telescope.builtin.internal').man_pages + +--- Lists lua modules and reloads them on `` +---@param opts table: options to pass to the picker builtin.reloader = require('telescope.builtin.internal').reloader + +--- Lists open buffers in current neovim instance, opens selected buffer on `` +---@param opts table: options to pass to the picker builtin.buffers = require('telescope.builtin.internal').buffers + +--- Lists available colorschemes and applies them on `` +---@param opts table: options to pass to the picker builtin.colorscheme = require('telescope.builtin.internal').colorscheme + +--- Lists vim marks and their value, jumps to the mark on `` +---@param opts table: options to pass to the picker builtin.marks = require('telescope.builtin.internal').marks + +--- Lists vim registers, pastes the contents of the register on `` +--- - Default keymaps: +--- - ``: edit the contents of the currently selected register +---@param opts table: options to pass to the picker builtin.registers = require('telescope.builtin.internal').registers + +--- Lists normal mode keymappings, runs the selected keymap on `` +---@param opts table: options to pass to the picker builtin.keymaps = require('telescope.builtin.internal').keymaps + +--- Lists all available filetypes, sets currently open buffer's filetype to selected filetype in Telescope on `` +---@param opts table: options to pass to the picker 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 + +--- Lists vim autocommands and goes to their declaration on `` +---@param opts table: options to pass to the picker builtin.autocommands = require('telescope.builtin.internal').autocommands + +--- Lists spelling suggestions for the current word under the cursor, replaces word with selected suggestion on `` +---@param opts table: options to pass to the picker builtin.spell_suggest = require('telescope.builtin.internal').spell_suggest + +--- Lists the tag stack for the current window, jumps to tag on `` +---@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 + +--- Lists items from Vim's jumplist, jumps to location on `` +---@param opts table: options to pass to the picker builtin.jumplist = require('telescope.builtin.internal').jumplist +-- +-- +-- LSP-related Pickers +-- +-- + +--- Lists LSP references for word under the cursor, jumps to reference on `` +---@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 + +--- 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 + +--- 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_document_symbols = require('telescope.builtin.lsp').document_symbols + +--- Lists any LSP actions for the word under the cursor which can be triggered with `` +---@param opts table: options to pass to the picker 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 `` +---@param opts table: options to pass to the picker builtin.lsp_range_code_actions = require('telescope.builtin.lsp').range_code_actions + +--- Lists LSP document symbols in the current buffer +--- - Default keymaps: +--- - ``: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`) +---@param opts table: options to pass to the picker +---@field ignore_filename type: string with file to ignore +builtin.lsp_document_symbols = require('telescope.builtin.lsp').document_symbols + +--- Lists LSP document symbols in the current workspace +--- - Default keymaps: +--- - ``: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`) +---@param opts table: options to pass to the picker +---@field 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 + +--- Dynamically lists LSP for all workspace symbols +--- - Default keymaps: +--- - ``: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`) +---@param opts table: options to pass to the picker +---@field 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 +--- Lists LSP diagnostics for the current buffer +--- - Default keymaps: +--- - ``: 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: +--- - ``: 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