diff options
Diffstat (limited to 'lua')
| -rw-r--r-- | lua/telescope/builtin/files.lua | 4 | ||||
| -rw-r--r-- | lua/telescope/builtin/init.lua | 260 |
2 files changed, 252 insertions, 12 deletions
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() +--- +--- 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: --- ---- This will use the default configuration options. ---- Other configuration options are still in flux at the moment +--- <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 ]] 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: +--- - `<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 + +--- 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: +--- - `<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 + +--- 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 + +--- 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 + +--- 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 + +--- 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 + +--- 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 +-- +-- +-- 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 `<cr>` +---@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 `<cr>` +---@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 `<cr>` +---@param opts table: options to pass to the picker 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 + +--- 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 + +--- 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 + +--- 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 + +--- 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 + +--- 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 + +--- Lists lua modules and reloads them on `<cr>` +---@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 `<cr>` +---@param opts table: options to pass to the picker 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 + +--- 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 + +--- 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 + +--- 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 + +--- 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 + +--- 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 `<cr>` +---@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 `<cr>` +---@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 `<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 + +--- 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 +-- +-- +-- 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 + +--- 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 `<cr>` +---@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 `<cr>` +---@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: +--- - `<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 + +--- 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 +--- 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 |