5a53ec5c2f
* feat: Consistent and sensible layout_config * [docgen] Update doc/telescope.txt skip-checks: true * [WIP]: Thu 17 Jun 2021 03:36:44 PM EDT * [WIP]: Thu 17 Jun 2021 03:38:11 PM EDT * layout_default -> layout_defaults * remove options from bug repot * Conni2461 suggestions: part 1 * [docgen] Update doc/telescope.txt skip-checks: true * Conni2461 suggestions: part 2 * [docgen] Update doc/telescope.txt skip-checks: true * Linting * Improve deprecation checks - Move `layout_defaults` handling to `deprecated.lua` - Check for "layout keys" outside of `layout_config` on `setup` * fixup: Just add a few more words Co-authored-by: Luke Kershaw <35707277+l-kershaw@users.noreply.github.com> Co-authored-by: Github Actions <actions@github>
1777 lines
65 KiB
Plaintext
1777 lines
65 KiB
Plaintext
================================================================================
|
|
*telescope.nvim*
|
|
|
|
Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search,
|
|
filter, find and pick things in Lua.
|
|
|
|
To find out more:
|
|
https://github.com/nvim-telescope/telescope.nvim
|
|
|
|
:h telescope.setup
|
|
:h telescope.builtin
|
|
:h telescope.layout
|
|
:h telescope.actions
|
|
|
|
telescope.setup({opts}) *telescope.setup()*
|
|
Setup function to be run by user. Configures the defaults, extensions and
|
|
other aspects of telescope.
|
|
|
|
|
|
Valid keys for {opts.defaults}
|
|
|
|
*telescope.defaults.border*
|
|
border: ~
|
|
Boolean defining if borders are added to Telescope windows.
|
|
|
|
Default: true
|
|
|
|
*telescope.defaults.default_mappings*
|
|
default_mappings: ~
|
|
Not recommended to use except for advanced users.
|
|
|
|
Will allow you to completely remove all of telescope's default maps
|
|
and use your own.
|
|
|
|
|
|
*telescope.defaults.dynamic_preview_title*
|
|
dynamic_preview_title: ~
|
|
Will change the title of the preview window dynamically, where it
|
|
is supported. Means the preview window will for example show the
|
|
full filename.
|
|
|
|
Default: false
|
|
|
|
|
|
*telescope.defaults.entry_prefix*
|
|
entry_prefix: ~
|
|
Prefix in front of each result entry. Current selection not included.
|
|
|
|
Default: ' '
|
|
|
|
*telescope.defaults.layout_config*
|
|
layout_config: ~
|
|
Determines the default configuration values for layout strategies.
|
|
See |telescope.layout| for details of the configurations options for
|
|
each strategy.
|
|
|
|
Allows setting defaults for all strategies as top level options and
|
|
for overriding for specific options.
|
|
For example, the default values below set the default width to 80% of
|
|
the screen width for all strategies except 'center', which has width
|
|
of 50% of the screen width.
|
|
|
|
Default: {
|
|
center = {
|
|
preview_cutoff = 40
|
|
},
|
|
height = 0.9,
|
|
horizontal = {
|
|
preview_cutoff = 120,
|
|
prompt_position = "bottom"
|
|
},
|
|
vertical = {
|
|
preview_cutoff = 40
|
|
},
|
|
width = 0.8
|
|
}
|
|
|
|
|
|
*telescope.defaults.layout_strategy*
|
|
layout_strategy: ~
|
|
Determines the default layout of Telescope pickers.
|
|
See |telescope.layout| for details of the available strategies.
|
|
|
|
Default: 'horizontal'
|
|
|
|
*telescope.defaults.mappings*
|
|
mappings: ~
|
|
Your mappings to override telescope's default mappings.
|
|
|
|
Format is:
|
|
{
|
|
mode = { ..keys }
|
|
}
|
|
|
|
where {mode} is the one character letter for a mode
|
|
('i' for insert, 'n' for normal).
|
|
|
|
For example:
|
|
|
|
mappings = {
|
|
i = {
|
|
["<esc>"] = require('telescope.actions').close,
|
|
},
|
|
}
|
|
|
|
|
|
To disable a keymap, put [map] = false
|
|
So, to not map "<C-n>", just put
|
|
|
|
...,
|
|
["<C-n>"] = false,
|
|
...,
|
|
|
|
Into your config.
|
|
|
|
|
|
otherwise, just set the mapping to the function that you want it to be.
|
|
|
|
...,
|
|
["<C-i>"] = require('telescope.actions').select_default,
|
|
...,
|
|
|
|
If the function you want is part of `telescope.actions`, then you can simply give a string.
|
|
For example, the previous option is equivalent to:
|
|
|
|
...,
|
|
["<C-i>"] = "select_default",
|
|
...,
|
|
|
|
You can also add other mappings using tables with `type = "command"`.
|
|
For example:
|
|
|
|
...,
|
|
["jj"] = { "<esc>", type = "command" },
|
|
["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
|
|
...,
|
|
|
|
|
|
*telescope.defaults.prompt_prefix*
|
|
prompt_prefix: ~
|
|
Will be shown in front of the prompt.
|
|
|
|
Default: '> '
|
|
|
|
*telescope.defaults.scroll_strategy*
|
|
scroll_strategy: ~
|
|
Determines what happens you try to scroll past view of the picker.
|
|
|
|
Available options are:
|
|
- "cycle" (default)
|
|
- "limit"
|
|
|
|
*telescope.defaults.selection_caret*
|
|
selection_caret: ~
|
|
Will be shown in front of the selection.
|
|
|
|
Default: '> '
|
|
|
|
*telescope.defaults.selection_strategy*
|
|
selection_strategy: ~
|
|
Determines how the cursor acts after each sort iteration.
|
|
|
|
Available options are:
|
|
- "reset" (default)
|
|
- "follow"
|
|
- "row"
|
|
|
|
*telescope.defaults.sorting_strategy*
|
|
sorting_strategy: ~
|
|
Determines the direction "better" results are sorted towards.
|
|
|
|
Available options are:
|
|
- "descending" (default)
|
|
- "ascending"
|
|
|
|
Parameters: ~
|
|
{opts} (table) Configuration opts. Keys: defaults, extensions
|
|
|
|
|
|
telescope.register_extension({mod}) *telescope.register_extension()*
|
|
Register an extension. To be used by plugin authors.
|
|
|
|
|
|
Parameters: ~
|
|
{mod} (table) Module
|
|
|
|
|
|
telescope.load_extension({name}) *telescope.load_extension()*
|
|
Load an extension.
|
|
|
|
|
|
Parameters: ~
|
|
{name} (string) Name of the extension
|
|
|
|
|
|
telescope.extensions() *telescope.extensions()*
|
|
Use telescope.extensions to reference any extensions within your
|
|
configuration.
|
|
While the docs currently generate this as a function, it's actually a
|
|
table. Sorry.
|
|
|
|
|
|
|
|
|
|
================================================================================
|
|
*telescope.themes*
|
|
|
|
Themes are ways to combine several elements of styling together.
|
|
|
|
They are helpful for managing the several differnt UI aspects for telescope and
|
|
provide a simple interface for users to get a particular "style" of picker.
|
|
|
|
themes.get_dropdown() *themes.get_dropdown()*
|
|
Dropdown style theme.
|
|
|
|
Usage:
|
|
|
|
`local builtin = require('telescope.builtin')`
|
|
`local themes = require('telescope.themes')`
|
|
`builtin.find_files(themes.get_dropdown())`
|
|
|
|
|
|
|
|
themes.get_ivy() *themes.get_ivy()*
|
|
Ivy style theme.
|
|
|
|
Usage:
|
|
|
|
`local builtin = require('telescope.builtin')`
|
|
`local themes = require('telescope.themes')`
|
|
`builtin.find_files(themes.get_ivy())`
|
|
|
|
|
|
|
|
|
|
================================================================================
|
|
*telescope.actions.set*
|
|
|
|
Telescope action sets are used to provide an interface for managing actions
|
|
that all primarily do the same thing, but with slight tweaks.
|
|
|
|
For example, when editing files you may want it in the current split, a
|
|
vertical split, etc. Instead of making users have to overwrite EACH of those
|
|
every time they want to change this behavior, they can instead replace the
|
|
`set` itself and then it will work great and they're done.
|
|
|
|
action_set.shift_selection({prompt_bufnr}, {change})*action_set.shift_selection()*
|
|
Move the current selection of a picker {change} rows. Handles not
|
|
overflowing / underflowing the list.
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
{change} (number) The amount to shift the selection by
|
|
|
|
|
|
action_set.select({prompt_bufnr}, {type}) *action_set.select()*
|
|
Select the current entry. This is the action set to overwrite common
|
|
actions by the user.
|
|
|
|
By default maps to editing a file.
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
{type} (string) The type of selection to make
|
|
|
|
|
|
action_set.edit({prompt_bufnr}, {command}) *action_set.edit()*
|
|
Edit a file based on the current selection.
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
{command} (string) The command to use to open the file.
|
|
|
|
|
|
action_set.scroll_previewer({prompt_bufnr}, {direction})*action_set.scroll_previewer()*
|
|
Scrolls the previewer up or down
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
{direction} (number) The direction of the scrolling
|
|
|
|
|
|
|
|
================================================================================
|
|
*telescope.actions*
|
|
|
|
Actions functions that are useful for people creating their own mappings.
|
|
|
|
actions.move_selection_next({prompt_bufnr}) *actions.move_selection_next()*
|
|
Move the selection to the next entry
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.move_selection_previous({prompt_bufnr})*actions.move_selection_previous()*
|
|
Move the selection to the previous entry
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.move_selection_worse({prompt_bufnr}) *actions.move_selection_worse()*
|
|
Move the selection to the entry that has a worse score
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.move_selection_better({prompt_bufnr})*actions.move_selection_better()*
|
|
Move the selection to the entry that has a better score
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.move_to_top({prompt_bufnr}) *actions.move_to_top()*
|
|
Move to the top of the picker
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.move_to_middle({prompt_bufnr}) *actions.move_to_middle()*
|
|
Move to the middle of the picker
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.move_to_bottom({prompt_bufnr}) *actions.move_to_bottom()*
|
|
Move to the bottom of the picker
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.add_selection({prompt_bufnr}) *actions.add_selection()*
|
|
Add current entry to multi select
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.remove_selection({prompt_bufnr}) *actions.remove_selection()*
|
|
Remove current entry from multi select
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.toggle_selection({prompt_bufnr}) *actions.toggle_selection()*
|
|
Toggle current entry status for multi select
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.git_create_branch({prompt_bufnr}) *actions.git_create_branch()*
|
|
Create and checkout a new git branch if it doesn't already exist
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.git_apply_stash({prompt_bufnr}) *actions.git_apply_stash()*
|
|
Applies an existing git stash
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.git_checkout({prompt_bufnr}) *actions.git_checkout()*
|
|
Checkout an existing git branch
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.git_switch_branch({prompt_bufnr}) *actions.git_switch_branch()*
|
|
Switch to git branch.
|
|
If the branch already exists in local, switch to that. If the branch is
|
|
only in remote, create new branch tracking remote and switch to new one.
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.git_track_branch({prompt_bufnr}) *actions.git_track_branch()*
|
|
Tell git to track the currently selected remote branch in Telescope
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.git_delete_branch({prompt_bufnr}) *actions.git_delete_branch()*
|
|
Delete the currently selected branch
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.git_rebase_branch({prompt_bufnr}) *actions.git_rebase_branch()*
|
|
Rebase to selected git branch
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.git_checkout_current_buffer({prompt_bufnr})*actions.git_checkout_current_buffer()*
|
|
Stage/unstage selected file
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.send_selected_to_qflist() *actions.send_selected_to_qflist()*
|
|
Sends the selected entries to the quickfix list, replacing the previous
|
|
entries.
|
|
|
|
|
|
|
|
actions.add_selected_to_qflist() *actions.add_selected_to_qflist()*
|
|
Adds the selected entries to the quickfix list, keeping the previous
|
|
entries.
|
|
|
|
|
|
|
|
actions.send_to_qflist() *actions.send_to_qflist()*
|
|
Sends all entries to the quickfix list, replacing the previous entries.
|
|
|
|
|
|
|
|
actions.add_to_qflist() *actions.add_to_qflist()*
|
|
Adds all entries to the quickfix list, keeping the previous entries.
|
|
|
|
|
|
|
|
actions.send_selected_to_loclist() *actions.send_selected_to_loclist()*
|
|
Sends the selected entries to the location list, replacing the previous
|
|
entries.
|
|
|
|
|
|
|
|
actions.add_selected_to_loclist() *actions.add_selected_to_loclist()*
|
|
Adds the selected entries to the location list, keeping the previous
|
|
entries.
|
|
|
|
|
|
|
|
actions.send_to_loclist() *actions.send_to_loclist()*
|
|
Sends all entries to the location list, replacing the previous entries.
|
|
|
|
|
|
|
|
actions.add_to_loclist() *actions.add_to_loclist()*
|
|
Adds all entries to the location list, keeping the previous entries.
|
|
|
|
|
|
|
|
actions.smart_send_to_qflist() *actions.smart_send_to_qflist()*
|
|
Sends the selected entries to the quickfix list, replacing the previous
|
|
entries. If no entry was selected, sends all entries.
|
|
|
|
|
|
|
|
actions.smart_add_to_qflist() *actions.smart_add_to_qflist()*
|
|
Adds the selected entries to the quickfix list, keeping the previous
|
|
entries. If no entry was selected, adds all entries.
|
|
|
|
|
|
|
|
actions.smart_send_to_loclist() *actions.smart_send_to_loclist()*
|
|
Sends the selected entries to the location list, replacing the previous
|
|
entries. If no entry was selected, sends all entries.
|
|
|
|
|
|
|
|
actions.smart_add_to_loclist() *actions.smart_add_to_loclist()*
|
|
Adds the selected entries to the location list, keeping the previous
|
|
entries. If no entry was selected, adds all entries.
|
|
|
|
|
|
|
|
actions.open_qflist() *actions.open_qflist()*
|
|
Open the quickfix list
|
|
|
|
|
|
|
|
actions.open_loclist() *actions.open_loclist()*
|
|
Open the location list
|
|
|
|
|
|
|
|
actions.delete_buffer({prompt_bufnr}) *actions.delete_buffer()*
|
|
Delete the selected buffer or all the buffers selected using multi
|
|
selection.
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.cycle_previewers_next({prompt_bufnr})*actions.cycle_previewers_next()*
|
|
Cycle to the next previewer if there is one available.
|
|
This action is not mapped on default.
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
actions.cycle_previewers_prev({prompt_bufnr})*actions.cycle_previewers_prev()*
|
|
Cycle to the previous previewer if there is one available.
|
|
This action is not mapped on default.
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
|
|
================================================================================
|
|
*telescope.builtin*
|
|
|
|
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_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
|
|
})
|
|
-- or with dropdown theme
|
|
:lua require('telescope.builtin').find_files(require('telescope.themes').get_dropdown{
|
|
previewer = false
|
|
})
|
|
|
|
You can also pass default configurations to builtin pickers. These options will
|
|
also be added if the picker is executed with `Telescope find_files`.
|
|
|
|
require("telescope").setup {
|
|
pickers = {
|
|
buffers = {
|
|
show_all_buffers = true,
|
|
sort_lastused = true,
|
|
theme = "dropdown",
|
|
previewer = false,
|
|
mappings = {
|
|
i = {
|
|
["<c-d>"] = require("telescope.actions").delete_buffer,
|
|
-- or right hand side can also be the name of the action as string
|
|
["<c-d>"] = "delete_buffer",
|
|
},
|
|
n = {
|
|
["<c-d>"] = require("telescope.actions").delete_buffer,
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
This will use the default configuration options. Other configuration options
|
|
are still in flux at the moment
|
|
|
|
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:
|
|
- `<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: ~
|
|
{cwd} (string) directory path to browse (default is cwd)
|
|
{depth} (number) file tree depth to display (default is 1)
|
|
|
|
|
|
builtin.treesitter() *builtin.treesitter()*
|
|
Lists function names, variables, and other symbols from treesitter queries
|
|
- Default keymaps:
|
|
- `<C-l>`: show autocompletion menu to prefilter your query by kind of ts
|
|
node you want to see (i.e. `:var:`)
|
|
|
|
|
|
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
|
|
|
|
Fields: ~
|
|
{cwd} (string) specify the path of the repo
|
|
|
|
|
|
builtin.git_bcommits({opts}) *builtin.git_bcommits()*
|
|
Lists commits for current buffer with diff preview
|
|
- Default keymaps or your overriden `select_` keys:
|
|
- `<cr>`: checks out the currently selected commit
|
|
- `<c-v>`: opens a diff in a vertical split
|
|
- `<c-x>`: opens a diff in a horizontal split
|
|
- `<c-t>`: opens a diff in a new tab
|
|
|
|
|
|
Parameters: ~
|
|
{opts} (table) options to pass to the picker
|
|
|
|
Fields: ~
|
|
{cwd} (string) specify the path of the repo
|
|
{current_file} (string) specify the current file that should be used
|
|
for bcommits (default: current buffer)
|
|
|
|
|
|
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
|
|
|
|
Fields: ~
|
|
{show_all_buffers} (boolean) if true, show all buffers, including
|
|
unloaded buffers (default true)
|
|
{ignore_current_buffer} (boolean) if true, don't show the current
|
|
buffer in the list (default false)
|
|
{only_cwd} (boolean) if true, only show buffers in the
|
|
current working directory (default
|
|
false)
|
|
{sort_lastused} (boolean) if true, sort the shown buffers so
|
|
that the last used one is selected
|
|
(default false)
|
|
{bufnr_width} (number) Defines the width of the buffer
|
|
numbers in front of the filenames
|
|
|
|
|
|
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
|
|
{symbols} (string|table) filter results by symbol kind(s)
|
|
|
|
|
|
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)
|
|
{symbols} (string|table) filter results by symbol kind(s)
|
|
|
|
|
|
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
|
|
- Fields:
|
|
- `All severity flags can be passed as `string` or `number` as per
|
|
`:vim.lsp.protocol.DiagnosticSeverity:`
|
|
- 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)
|
|
{severity} (string|number) filter diagnostics by severity name
|
|
(string) or id (number)
|
|
{severity_limit} (string|number) keep diagnostics equal or more severe
|
|
wrt severity name (string) or id
|
|
(number)
|
|
{severity_bound} (string|number) keep diagnostics equal or less severe
|
|
wrt severity name (string) or id
|
|
(number)
|
|
{no_sign} (bool) hide LspDiagnosticSigns from Results
|
|
(default is false)
|
|
{line_width} (number) set length of diagnostic entry text
|
|
in Results
|
|
|
|
|
|
builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()*
|
|
Lists LSP diagnostics for the current workspace if supported, otherwise
|
|
searches in all open buffers
|
|
- Fields:
|
|
- `All severity flags can be passed as `string` or `number` as per
|
|
`:vim.lsp.protocol.DiagnosticSeverity:`
|
|
- 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)
|
|
{severity} (string|number) filter diagnostics by severity name
|
|
(string) or id (number)
|
|
{severity_limit} (string|number) keep diagnostics equal or more severe
|
|
wrt severity name (string) or id
|
|
(number)
|
|
{severity_bound} (string|number) keep diagnostics equal or less severe
|
|
wrt severity name (string) or id
|
|
(number)
|
|
{no_sign} (bool) hide LspDiagnosticSigns from Results
|
|
(default is false)
|
|
{line_width} (number) set length of diagnostic entry text
|
|
in Results
|
|
|
|
|
|
|
|
================================================================================
|
|
*telescope.actions.state*
|
|
|
|
Functions to be used to determine the current state of telescope.
|
|
|
|
Generally used from within other |telescope.actions|
|
|
|
|
action_state.get_selected_entry() *action_state.get_selected_entry()*
|
|
Get the current entry
|
|
|
|
|
|
|
|
action_state.get_current_line() *action_state.get_current_line()*
|
|
Gets the current line
|
|
|
|
|
|
|
|
action_state.get_current_picker({prompt_bufnr})*action_state.get_current_picker()*
|
|
Gets the current picker
|
|
|
|
|
|
Parameters: ~
|
|
{prompt_bufnr} (number) The prompt bufnr
|
|
|
|
|
|
|
|
================================================================================
|
|
*telescope.resolve*
|
|
|
|
Provides "resolver functions" to allow more customisable inputs for options.
|
|
|
|
resolver.resolve_height() *resolver.resolve_height()*
|
|
Converts input to a function that returns the height. The input must take
|
|
one of four forms:
|
|
1. 0 <= number < 1
|
|
This means total height as a percentage.
|
|
2. 1 <= number
|
|
This means total height as a fixed number.
|
|
3. function
|
|
Must have signature: function(self, max_columns, max_lines): number
|
|
4. table of the form: {padding = `foo`}
|
|
where `foo` has one of the previous three forms.
|
|
The height is then set to be the remaining space after padding. For
|
|
example, if the window has height 50, and the input is {padding = 5},
|
|
the height returned will be `40 = 50 - 2*5`
|
|
|
|
The returned function will have signature: function(self, max_columns,
|
|
max_lines): number
|
|
|
|
|
|
|
|
resolver.resolve_width() *resolver.resolve_width()*
|
|
Converts input to a function that returns the width. The input must take
|
|
one of four forms:
|
|
1. 0 <= number < 1
|
|
This means total width as a percentage.
|
|
2. 1 <= number
|
|
This means total width as a fixed number.
|
|
3. function
|
|
Must have signature: function(self, max_columns, max_lines): number
|
|
4. table of the form: {padding = `foo`}
|
|
where `foo` has one of the previous three forms.
|
|
The width is then set to be the remaining space after padding. For
|
|
example, if the window has width 100, and the input is {padding = 5},
|
|
the width returned will be `90 = 100 - 2*5`
|
|
|
|
The returned function will have signature: function(self, max_columns,
|
|
max_lines): number
|
|
|
|
|
|
|
|
|
|
================================================================================
|
|
*telescope.previewers*
|
|
|
|
Provides a Previewer table that has to be implemented by each previewer. To
|
|
achieve this, this module also provides two wrappers that abstract most of the
|
|
work and make it really easy create new previewers.
|
|
- `previewers.new_termopen_previewer`
|
|
- `previewers.new_buffer_previewer`
|
|
|
|
Furthermore, there are a collection of previewers already defined which can be
|
|
used for every picker, as long as the entries of the picker provide the
|
|
necessary fields. The more important once are
|
|
- `previewers.cat`
|
|
- `previewers.vimgrep`
|
|
- `previewers.qflist`
|
|
- `previewers.vim_buffer_cat`
|
|
- `previewers.vim_buffer_vimgrep`
|
|
- `previewers.vim_buffer_qflist`
|
|
|
|
Previewers can be disabled for any builtin or custom picker by doing :Telescope
|
|
find_files previewer=false
|
|
|
|
previewers.Previewer() *previewers.Previewer()*
|
|
This is the base table all previewers have to implement. It's possible to
|
|
write a wrapper for this because most previewers need to have the same keys
|
|
set. Examples of wrappers are:
|
|
- `new_buffer_previewer`
|
|
- `new_termopen_previewer`
|
|
|
|
To create a new table do following:
|
|
- `local new_previewer = Previewer:new(opts)`
|
|
|
|
What `:new` expects is listed below
|
|
|
|
The interface provides following set of functions. All of them, besides
|
|
`new`, will be handled by telescope pickers.
|
|
- `:new(opts)`
|
|
- `:preview(entry, status)`
|
|
- `:teardown()`
|
|
- `:send_input(input)`
|
|
- `:scroll_fn(direction)`
|
|
|
|
`Previewer:new()` expects a table as input with following keys:
|
|
- `setup` function(self): Will be called the first time preview will be
|
|
called.
|
|
- `teardown` function(self): Will be called on cleanup.
|
|
- `preview_fn` function(self, entry, status): Will be called each time a
|
|
new entry was selected.
|
|
- `title` function(self): Will return the static title of the previewer.
|
|
- `dynamic_title` function(self, entry): Will return the dynamic title of
|
|
the previewer. Will only be called when config value
|
|
dynamic_preview_title is true.
|
|
- `send_input` function(self, input): This is meant for
|
|
`termopen_previewer` and it can be used to send input to the terminal
|
|
application, like less.
|
|
- `scroll_fn` function(self, direction): Used to make scrolling work.
|
|
|
|
|
|
|
|
previewers.new() *previewers.new()*
|
|
A shorthand for creating a new Previewer. The provided table will be
|
|
forwarded to `Previewer:new(...)`
|
|
|
|
|
|
|
|
previewers.new_termopen_previewer() *previewers.new_termopen_previewer()*
|
|
Is a wrapper around Previewer and helps with creating a new
|
|
`termopen_previewer`.
|
|
|
|
It requires you to specify one table entry `get_command(entry, status)`.
|
|
This `get_command` function has to return the terminal command that will be
|
|
executed for each entry. Example:
|
|
get_command = function(entry, status)
|
|
return { 'bat', entry.path }
|
|
end
|
|
|
|
Additionally you can define:
|
|
- `title` a static title for example "File Preview"
|
|
- `dyn_title(self, entry)` a dynamic title function which gets called when
|
|
config value `dynamic_preview_title = true`
|
|
|
|
It's an easy way to get your first previewer going and it integrates well
|
|
with `bat` and `less`. Providing out of the box scrolling if the command
|
|
uses less.
|
|
|
|
Furthermore, it will forward all `config.set_env` environment variables to
|
|
that terminal process.
|
|
|
|
While this interface is a good start, it was replaced with the way more
|
|
flexible `buffer_previewer` and is now deprecated.
|
|
|
|
|
|
|
|
previewers.cat() *previewers.cat()*
|
|
Provides a `termopen_previewer` which has the ability to display files. It
|
|
will always show the top of the file and has support for `bat`(prioritized)
|
|
and `cat`. Each entry has to provide either the field `path` or `filename`
|
|
in order to make this previewer work.
|
|
|
|
The preferred way of using this previewer is like this
|
|
`require('telescope.config').values.cat_previewer` This will respect user
|
|
configuration and will use `buffer_previewers` in case it's configured that
|
|
way.
|
|
|
|
|
|
|
|
previewers.vimgrep() *previewers.vimgrep()*
|
|
Provides a `termopen_previewer` which has the ability to display files at
|
|
the provided line. It has support for `bat`(prioritized) and `cat`. Each
|
|
entry has to provide either the field `path` or `filename` and a `lnum`
|
|
field in order to make this previewer work.
|
|
|
|
The preferred way of using this previewer is like this
|
|
`require('telescope.config').values.grep_previewer` This will respect user
|
|
configuration and will use `buffer_previewers` in case it's configured that
|
|
way.
|
|
|
|
|
|
|
|
previewers.qflist() *previewers.qflist()*
|
|
Provides a `termopen_previewer` which has the ability to display files at
|
|
the provided line or range. It has support for `bat`(prioritized) and
|
|
`cat`. Each entry has to provide either the field `path` or `filename`,
|
|
`lnum` and a `start` and `finish` range in order to make this previewer
|
|
work.
|
|
|
|
The preferred way of using this previewer is like this
|
|
`require('telescope.config').values.qflist_previewer` This will respect
|
|
user configuration and will use buffer previewers in case it's configured
|
|
that way.
|
|
|
|
|
|
|
|
previewers.new_buffer_previewer() *previewers.new_buffer_previewer()*
|
|
An interface to instantiate a new `buffer_previewer`. That means that the
|
|
content actually lives inside a vim buffer which enables us more control
|
|
over the actual content. For example, we can use `vim.fn.search` to jump to
|
|
a specific line or reuse buffers/already opened files more easily. This
|
|
interface is more complex than `termopen_previewer` but offers more
|
|
flexibility over your content. It was designed to display files but was
|
|
extended to also display the output of terminal commands.
|
|
|
|
In the following options, state table and general tips are mentioned to
|
|
make your experience with this previewer more seamless.
|
|
|
|
|
|
options:
|
|
- `define_preview = function(self, entry, status)` (required) Is called
|
|
for each selected entry, after each selection_move (up or down) and is
|
|
meant to handle things like reading file, jump to line or attach a
|
|
highlighter.
|
|
- `setup = function(self)` (optional) Is called once at the beginning,
|
|
before the preview for the first entry is displayed. You can return a
|
|
table of vars that will be available in `self.state` in each
|
|
`define_preview` call.
|
|
- `teardown = function(self)` (optional) Will be called at the end, when
|
|
the picker is being closed and is meant to cleanup everything that was
|
|
allocated by the previewer. The `buffer_previewer` will automatically
|
|
cleanup all created buffers. So you only need to handle things that
|
|
were introduced by you.
|
|
- `keep_last_buf = true` (optional) Will not delete the last selected
|
|
buffer. This would allow you to reuse that buffer in the select action.
|
|
For example, that buffer can be opened in a new split, rather than
|
|
recreating that buffer in an action. To access the last buffer number:
|
|
`require('telescope.state').get_global_key("last_preview_bufnr")`
|
|
- `get_buffer_by_name = function(self, entry)` Allows you to set a unique
|
|
name for each buffer. This is used for caching purpose.
|
|
`self.state.bufname` will be nil if the entry was never loaded or the
|
|
unique name when it was loaded once. For example, useful if you have
|
|
one file but multiple entries. This happens for grep and lsp builtins.
|
|
So to make the cache work only load content if `self.state.bufname ~=
|
|
entry.your_unique_key`
|
|
- `title` a static title for example "File Preview"
|
|
- `dyn_title(self, entry)` a dynamic title function which gets called
|
|
when config value `dynamic_preview_title = true`
|
|
|
|
`self.state` table:
|
|
- `self.state.bufnr` Is the current buffer number, in which you have to
|
|
write the loaded content. Don't create a buffer yourself, otherwise
|
|
it's not managed by the buffer_previewer interface and you will
|
|
probably be better off writing your own interface.
|
|
- self.state.winid Current window id. Useful if you want to set the
|
|
cursor to a provided line number.
|
|
- self.state.bufname Will return the current buffer name, if
|
|
`get_buffer_by_name` is defined. nil will be returned if the entry was
|
|
never loaded or when `get_buffer_by_name` is not set.
|
|
|
|
Tips:
|
|
- If you want to display content of a terminal job, use:
|
|
`require('telescope.previewers.utils').job_maker(cmd, bufnr, opts)`
|
|
- `cmd` table: for example { 'git', 'diff', entry.value }
|
|
- `bufnr` number: in which the content will be written
|
|
- `opts` table: with following keys
|
|
- `bufname` string: used for cache
|
|
- `value` string: used for cache
|
|
- `mode` string: either "insert" or "append". "insert" is default
|
|
- `env` table: define environment variables. Example:
|
|
- `{ ['PAGER'] = '', ['MANWIDTH'] = 50 }`
|
|
- `cwd` string: define current working directory for job
|
|
- `callback` function(bufnr, content): will be called when job is
|
|
done. Content will be nil if job is already loaded. So you can do
|
|
highlighting only the first time the previewer is created for
|
|
that entry. Use the returned `bufnr` and not `self.state.bufnr`
|
|
in callback, because state can already be changed at this point
|
|
in time.
|
|
- If you want to attach a highlighter use:
|
|
- `require('telescope.previewers.utils').highlighter(bufnr, ft)`
|
|
- This will prioritize tree sitter highlighting if available for
|
|
environment and language.
|
|
- `require('telescope.previewers.utils').regex_highlighter(bufnr, ft)`
|
|
- `require('telescope.previewers.utils').ts_highlighter(bufnr, ft)`
|
|
- If you want to use `vim.fn.search` or similar you need to run it in
|
|
that specific buffer context. Do
|
|
vim.api.nvim_buf_call(bufnr, function()
|
|
-- for example `search` and `matchadd`
|
|
end)
|
|
to achieve that.
|
|
- If you want to read a file into the buffer it's best to use
|
|
`buffer_previewer_maker`. But access this function with
|
|
`require('telescope.config').values.buffer_previewer_maker` because it
|
|
can be redefined by users.
|
|
|
|
|
|
|
|
previewers.buffer_previewer_maker({filepath}, {bufnr}, {opts})*previewers.buffer_previewer_maker()*
|
|
A universal way of reading a file into a buffer previewer. It handles async
|
|
reading, cache, highlighting, displaying directories and provides a
|
|
callback which can be used, to jump to a line in the buffer.
|
|
|
|
|
|
Parameters: ~
|
|
{filepath} (string) String to the filepath, will be expanded
|
|
{bufnr} (number) Where the content will be written
|
|
{opts} (table) keys: `use_ft_detect`, `bufname` and `callback`
|
|
|
|
|
|
previewers.vim_buffer_cat() *previewers.vim_buffer_cat()*
|
|
A previewer that is used to display a file. It uses the `buffer_previewer`
|
|
interface and won't jump to the line. To integrate this one into your own
|
|
picker make sure that the field `path` or `filename` is set for each entry.
|
|
The preferred way of using this previewer is like this
|
|
`require('telescope.config').values.file_previewer` This will respect user
|
|
configuration and will use `termopen_previewer` in case it's configured
|
|
that way.
|
|
|
|
|
|
|
|
previewers.vim_buffer_vimgrep() *previewers.vim_buffer_vimgrep()*
|
|
A previewer that is used to display a file and jump to the provided line.
|
|
It uses the `buffer_previewer` interface. To integrate this one into your
|
|
own picker make sure that the field `path` or `filename` and `lnum` is set
|
|
in each entry. If the latter is not present, it will default to the first
|
|
line. The preferred way of using this previewer is like this
|
|
`require('telescope.config').values.grep_previewer` This will respect user
|
|
configuration and will use `termopen_previewer` in case it's configured
|
|
that way.
|
|
|
|
|
|
|
|
previewers.vim_buffer_qflist() *previewers.vim_buffer_qflist()*
|
|
Is the same as `vim_buffer_vimgrep` and only exist for consistency with
|
|
`term_previewers`.
|
|
|
|
The preferred way of using this previewer is like this
|
|
`require('telescope.config').values.qflist_previewer` This will respect
|
|
user configuration and will use `termopen_previewer` in case it's
|
|
configured that way.
|
|
|
|
|
|
|
|
previewers.git_branch_log() *previewers.git_branch_log()*
|
|
A previewer that shows a log of a branch as graph
|
|
|
|
|
|
|
|
previewers.git_stash_diff() *previewers.git_stash_diff()*
|
|
A previewer that shows a diff of a stash
|
|
|
|
|
|
|
|
previewers.git_commit_diff_to_parent()*previewers.git_commit_diff_to_parent()*
|
|
A previewer that shows a diff of a commit to a parent commit.
|
|
The run command is `git --no-pager diff SHA^! -- $CURRENT_FILE`
|
|
|
|
The current file part is optional. So is only uses it with bcommits.
|
|
|
|
|
|
|
|
previewers.git_commit_diff_to_head() *previewers.git_commit_diff_to_head()*
|
|
A previewer that shows a diff of a commit to head.
|
|
The run command is `git --no-pager diff --cached $SHA -- $CURRENT_FILE`
|
|
|
|
The current file part is optional. So is only uses it with bcommits.
|
|
|
|
|
|
|
|
previewers.git_commit_diff_as_was() *previewers.git_commit_diff_as_was()*
|
|
A previewer that shows a diff of a commit as it was.
|
|
The run command is `git --no-pager show $SHA:$CURRENT_FILE` or `git
|
|
--no-pager show $SHA`
|
|
|
|
|
|
|
|
previewers.git_commit_message() *previewers.git_commit_message()*
|
|
A previewer that shows the commit message of a diff.
|
|
The run command is `git --no-pager log -n 1 $SHA`
|
|
|
|
|
|
|
|
previewers.git_file_diff() *previewers.git_file_diff()*
|
|
A previewer that shows the current diff of a file. Used in git_status.
|
|
The run command is `git --no-pager diff $FILE`
|
|
|
|
|
|
|
|
previewers.display_content() *previewers.display_content()*
|
|
A deprecated way of displaying content more easily. Was written at a time,
|
|
where the buffer_previewer interface wasn't present. Nowadays it's easier
|
|
to just use this. We will keep it around for backwards compatibility
|
|
because some extensions use it. It doesn't use cache or some other clever
|
|
tricks.
|
|
|
|
|
|
|
|
|
|
================================================================================
|
|
*telescope.layout*
|
|
|
|
Layout strategies are different functions to position telescope.
|
|
|
|
All layout strategies are functions with the following signature:
|
|
|
|
function(picker, columns, lines, layout_config)
|
|
-- Do some calculations here...
|
|
return {
|
|
preview = preview_configuration
|
|
results = results_configuration,
|
|
prompt = prompt_configuration,
|
|
}
|
|
end
|
|
|
|
Parameters: ~
|
|
- picker : A Picker object. (docs coming soon)
|
|
- columns : (number) Columns in the vim window
|
|
- lines : (number) Lines in the vim window
|
|
- layout_config : (table) The configuration values specific to the picker.
|
|
|
|
|
|
This means you can create your own layout strategy if you want! Just be aware
|
|
for now that we may change some APIs or interfaces, so they may break if you
|
|
create your own.
|
|
|
|
A good method for creating your own would be to copy one of the strategies that
|
|
most resembles what you want from
|
|
"./lua/telescope/pickers/layout_strategies.lua" in the telescope repo.
|
|
|
|
|
|
layout_strategies.horizontal() *layout_strategies.horizontal()*
|
|
Horizontal layout has two columns, one for the preview and one for the
|
|
prompt and results.
|
|
|
|
┌──────────────────────────────────────────────────┐
|
|
│ │
|
|
│ ┌───────────────────┐┌───────────────────┐ │
|
|
│ │ ││ │ │
|
|
│ │ ││ │ │
|
|
│ │ ││ │ │
|
|
│ │ Results ││ │ │
|
|
│ │ ││ Preview │ │
|
|
│ │ ││ │ │
|
|
│ │ ││ │ │
|
|
│ └───────────────────┘│ │ │
|
|
│ ┌───────────────────┐│ │ │
|
|
│ │ Prompt ││ │ │
|
|
│ └───────────────────┘└───────────────────┘ │
|
|
│ │
|
|
└──────────────────────────────────────────────────┘
|
|
|
|
`picker.layout_config` shared options:
|
|
- height:
|
|
- How tall to make Telescope's entire layout
|
|
- See |resolver.resolve_height()|
|
|
- mirror: Flip the location of the results/prompt and preview windows
|
|
- scroll_speed: The number of lines to scroll through the previewer
|
|
- width:
|
|
- How wide to make Telescope's entire layout
|
|
- See |resolver.resolve_width()|
|
|
|
|
`picker.layout_config` unique options:
|
|
- preview_cutoff: When columns are less than this value, the preview will be disabled
|
|
- preview_width:
|
|
- Change the width of Telescope's preview window
|
|
- See |resolver.resolve_width()|
|
|
- prompt_position:
|
|
- Where to place prompt window.
|
|
- Available Values: 'bottom', 'top'
|
|
|
|
|
|
layout_strategies.center() *layout_strategies.center()*
|
|
Centered layout with a combined block of the prompt and results aligned to
|
|
the middle of the screen. The preview window is then placed in the
|
|
remaining space above. Particularly useful for creating dropdown menus (see
|
|
|telescope.themes| and |themes.get_dropdown()|`).
|
|
|
|
┌──────────────────────────────────────────────────┐
|
|
│ ┌────────────────────────────────────────┐ │
|
|
│ | Preview | │
|
|
│ | Preview | │
|
|
│ └────────────────────────────────────────┘ │
|
|
│ ┌────────────────────────────────────────┐ │
|
|
│ | Prompt | │
|
|
│ ├────────────────────────────────────────┤ │
|
|
│ | Result | │
|
|
│ | Result | │
|
|
│ └────────────────────────────────────────┘ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
│ │
|
|
└──────────────────────────────────────────────────┘
|
|
|
|
`picker.layout_config` shared options:
|
|
- height:
|
|
- How tall to make Telescope's entire layout
|
|
- See |resolver.resolve_height()|
|
|
- mirror: Flip the location of the results/prompt and preview windows
|
|
- scroll_speed: The number of lines to scroll through the previewer
|
|
- width:
|
|
- How wide to make Telescope's entire layout
|
|
- See |resolver.resolve_width()|
|
|
|
|
`picker.layout_config` unique options:
|
|
- preview_cutoff: When lines are less than this value, the preview will be disabled
|
|
|
|
|
|
layout_strategies.vertical() *layout_strategies.vertical()*
|
|
Vertical layout stacks the items on top of each other. Particularly useful
|
|
with thinner windows.
|
|
|
|
┌──────────────────────────────────────────────────┐
|
|
│ │
|
|
│ ┌────────────────────────────────────────┐ │
|
|
│ | Preview | │
|
|
│ | Preview | │
|
|
│ | Preview | │
|
|
│ └────────────────────────────────────────┘ │
|
|
│ ┌────────────────────────────────────────┐ │
|
|
│ | Result | │
|
|
│ | Result | │
|
|
│ └────────────────────────────────────────┘ │
|
|
│ ┌────────────────────────────────────────┐ │
|
|
│ | Prompt | │
|
|
│ └────────────────────────────────────────┘ │
|
|
│ │
|
|
└──────────────────────────────────────────────────┘
|
|
|
|
`picker.layout_config` shared options:
|
|
- height:
|
|
- How tall to make Telescope's entire layout
|
|
- See |resolver.resolve_height()|
|
|
- mirror: Flip the location of the results/prompt and preview windows
|
|
- scroll_speed: The number of lines to scroll through the previewer
|
|
- width:
|
|
- How wide to make Telescope's entire layout
|
|
- See |resolver.resolve_width()|
|
|
|
|
`picker.layout_config` unique options:
|
|
- preview_cutoff: When lines are less than this value, the preview will be disabled
|
|
- preview_height:
|
|
- Change the height of Telescope's preview window
|
|
- See |resolver.resolve_height()|
|
|
- prompt_position:
|
|
- (unimplemented, but we plan on supporting)
|
|
|
|
|
|
layout_strategies.flex() *layout_strategies.flex()*
|
|
Flex layout swaps between `horizontal` and `vertical` strategies based on
|
|
the window width
|
|
- Supports |layout_strategies.vertical| or |layout_strategies.horizontal|
|
|
features
|
|
|
|
|
|
`picker.layout_config` shared options:
|
|
- height:
|
|
- How tall to make Telescope's entire layout
|
|
- See |resolver.resolve_height()|
|
|
- mirror: Flip the location of the results/prompt and preview windows
|
|
- scroll_speed: The number of lines to scroll through the previewer
|
|
- width:
|
|
- How wide to make Telescope's entire layout
|
|
- See |resolver.resolve_width()|
|
|
|
|
`picker.layout_config` unique options:
|
|
- flip_columns: The number of columns required to move to horizontal mode
|
|
- flip_lines: The number of lines required to move to horizontal mode
|
|
- horizontal: Options to pass when switching to horizontal layout
|
|
- vertical: Options to pass when switching to vertical layout
|
|
|
|
|
|
layout_strategies.bottom_pane() *layout_strategies.bottom_pane()*
|
|
Bottom pane can be used to create layouts similar to "ivy".
|
|
|
|
For an easy ivy configuration, see |themes.get_ivy()|
|
|
|
|
|
|
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|