leigh/telescope.nvim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
654b11aa08e54255a55625e6bca514b9659b7896
telescope.nvim/doc/telescope.txt
Ben Smith 654b11aa08 Change the show_all_buffers option to true by default for buffers picker (#858) 
* show_all_buffers true by default, added docs

* [docgen] Update doc/telescope.txt
skip-checks: true

* fix for docs, used param instead of field oops

* [docgen] Update doc/telescope.txt
skip-checks: true

Co-authored-by: Github Actions <actions@github>
2021-05-30 22:12:18 -04:00

1312 lines
44 KiB
Plaintext
Raw Blame History

================================================================================
*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.entry_prefix*
entry_prefix: ~
Prefix in front of each result entry. Current selection not included.
Default: ' '
*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_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.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.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.open_qflist() *actions.open_qflist()*
Open the quickfix list
================================================================================
*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
})
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: ~
{search_dirs} (table) directory/directories to search in
builtin.treesitter() *builtin.treesitter()*
Lists function names, variables, and other symbols from treesitter queries
Fields: ~
{show_line} (boolean) if true, shows the row:column that the result is
found at (default is true)
builtin.current_buffer_fuzzy_find({opts})*builtin.current_buffer_fuzzy_find()*
Live fuzzy search inside of the currently open buffer
Parameters: ~
{opts} (table) options to pass to the picker
builtin.tags({opts}) *builtin.tags()*
Lists tags in current directory with tag location file preview (users are
required to run ctags -R to generate tags or update when introducing new
changes)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{ctags_file} (string) specify a particular ctags file to use
{show_line} (boolean) if true, shows the content of the line the
tag is found on in the picker (default is
true)
{shorten_path} (boolean) if true, makes file paths shown in picker
use one letter for folders (default is true)
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is false)
builtin.current_buffer_tags({opts}) *builtin.current_buffer_tags()*
Lists all of the tags for the currently open buffer, with a preview
Parameters: ~
{opts} (table) options to pass to the picker
builtin.git_files({opts}) *builtin.git_files()*
Fuzzy search for files tracked by Git. This command lists the output of the
`git ls-files` command, respects .gitignore, and optionally ignores
untracked files
- Default keymaps:
- `<cr>`: opens the currently selected file
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{show_untracked} (boolean) if true, adds `--others` flag to
command and shows untracked files
(default is true)
{recurse_submodules} (boolean) if true, adds the
`--recurse-submodules` flag to command
(default is false)
builtin.git_commits({opts}) *builtin.git_commits()*
Lists commits for current directory with diff preview
- Default keymaps:
- `<cr>`: checks out the currently selected commit
Parameters: ~
{opts} (table) options to pass to the picker
builtin.git_bcommits({opts}) *builtin.git_bcommits()*
Lists commits for current buffer with diff preview
- Default keymaps:
- `<cr>`: checks out the currently selected commit
Parameters: ~
{opts} (table) options to pass to the picker
builtin.git_branches({opts}) *builtin.git_branches()*
List branches for current directory, with output from `git log --oneline`
shown in the preview window
- Default keymaps:
- `<cr>`: checks out the currently selected branch
- `<C-t>`: tracks currently selected branch
- `<C-r>`: rebases currently selected branch
- `<C-a>`: creates a new branch, with confirmation prompt before creation
- `<C-d>`: deletes the currently selected branch, with confirmation
prompt before deletion
Parameters: ~
{opts} (table) options to pass to the picker
builtin.git_status({opts}) *builtin.git_status()*
Lists git status for current directory
- Default keymaps:
- `<Tab>`: stages or unstages the currently selected file
- `<cr>`: opens the currently selected file
Parameters: ~
{opts} (table) options to pass to the picker
builtin.git_stash({opts}) *builtin.git_stash()*
Lists stash items in current repository
- Default keymaps:
- `<cr>`: runs `git apply` for currently selected stash
Parameters: ~
{opts} (table) options to pass to the picker
builtin.builtin({opts}) *builtin.builtin()*
Lists all of the community maintained pickers built into Telescope
Parameters: ~
{opts} (table) options to pass to the picker
builtin.planets({opts}) *builtin.planets()*
Use the telescope...
Parameters: ~
{opts} (table) options to pass to the picker
builtin.symbols({opts}) *builtin.symbols()*
Lists symbols inside of data/telescope-sources/*.json found in your runtime
path. Check README for more info
Parameters: ~
{opts} (table) options to pass to the picker
builtin.commands({opts}) *builtin.commands()*
Lists available plugin/user commands and runs them on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.quickfix({opts}) *builtin.quickfix()*
Lists items in the quickfix list, jumps to location on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.loclist({opts}) *builtin.loclist()*
Lists items from the current window's location list, jumps to location on
`<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.oldfiles({opts}) *builtin.oldfiles()*
Lists previously open files, opens on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.command_history({opts}) *builtin.command_history()*
Lists commands that were executed recently, and reruns them on `<cr>`
- Default keymaps:
- `<C-e>`: open the command line with the text of the currently selected
result populated in it
Parameters: ~
{opts} (table) options to pass to the picker
builtin.search_history({opts}) *builtin.search_history()*
Lists searches that were executed recently, and reruns them on `<cr>`
- Default keymaps:
- `<C-e>`: open a search window with the text of the currently selected
search result populated in it
Parameters: ~
{opts} (table) options to pass to the picker
builtin.vim_options({opts}) *builtin.vim_options()*
Lists vim options, allows you to edit the current value on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.help_tags({opts}) *builtin.help_tags()*
Lists available help tags and opens a new window with the relevant help
info on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.man_pages({opts}) *builtin.man_pages()*
Lists manpage entries, opens them in a help window on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.reloader({opts}) *builtin.reloader()*
Lists lua modules and reloads them on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.buffers({opts}) *builtin.buffers()*
Lists open buffers in current neovim instance, opens selected buffer on
`<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
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)
builtin.colorscheme({opts}) *builtin.colorscheme()*
Lists available colorschemes and applies them on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.marks({opts}) *builtin.marks()*
Lists vim marks and their value, jumps to the mark on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.registers({opts}) *builtin.registers()*
Lists vim registers, pastes the contents of the register on `<cr>`
- Default keymaps:
- `<C-e>`: edit the contents of the currently selected register
Parameters: ~
{opts} (table) options to pass to the picker
builtin.keymaps({opts}) *builtin.keymaps()*
Lists normal mode keymappings, runs the selected keymap on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.filetypes({opts}) *builtin.filetypes()*
Lists all available filetypes, sets currently open buffer's filetype to
selected filetype in Telescope on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.highlights({opts}) *builtin.highlights()*
Lists all available highlights
Parameters: ~
{opts} (table) options to pass to the picker
builtin.autocommands({opts}) *builtin.autocommands()*
Lists vim autocommands and goes to their declaration on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.spell_suggest({opts}) *builtin.spell_suggest()*
Lists spelling suggestions for the current word under the cursor, replaces
word with selected suggestion on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.tagstack({opts}) *builtin.tagstack()*
Lists the tag stack for the current window, jumps to tag on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{shorten_path} (boolean) if true, makes file paths shown in picker
use one letter for folders (default is true)
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is true)
builtin.jumplist({opts}) *builtin.jumplist()*
Lists items from Vim's jumplist, jumps to location on `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.lsp_references({opts}) *builtin.lsp_references()*
Lists LSP references for word under the cursor, jumps to reference on
`<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{shorten_path} (boolean) if true, makes file paths shown in picker use
one letter for folders (default is false)
builtin.lsp_definitions({opts}) *builtin.lsp_definitions()*
Goto the definition of the word under the cursor, if there's only one,
otherwise show all options in Telescope
Parameters: ~
{opts} (table) options to pass to the picker
builtin.lsp_implementations({opts}) *builtin.lsp_implementations()*
Goto the implementation of the word under the cursor if there's only one,
otherwise show all options in Telescope
Parameters: ~
{opts} (table) options to pass to the picker
builtin.lsp_code_actions({opts}) *builtin.lsp_code_actions()*
Lists any LSP actions for the word under the cursor which can be triggered
with `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.lsp_range_code_actions({opts}) *builtin.lsp_range_code_actions()*
Lists any LSP actions for a given range, that can be triggered with `<cr>`
Parameters: ~
{opts} (table) options to pass to the picker
builtin.lsp_document_symbols({opts}) *builtin.lsp_document_symbols()*
Lists LSP document symbols in the current buffer
- Default keymaps:
- `<C-l>`: show autocompletion menu to prefilter your query by type of
symbol you want to see (i.e. `:variable:`)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{ignore_filename} (type) string with file to ignore
builtin.lsp_workspace_symbols({opts}) *builtin.lsp_workspace_symbols()*
Lists LSP document symbols in the current workspace
- Default keymaps:
- `<C-l>`: show autocompletion menu to prefilter your query by type of
symbol you want to see (i.e. `:variable:`)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{shorten_path} (boolean) if true, makes file paths shown in picker
use one letter for folders (default is
false)
{ignore_filename} (string) file(s) to ignore
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is false)
builtin.lsp_dynamic_workspace_symbols({opts})*builtin.lsp_dynamic_workspace_symbols()*
Dynamically lists LSP for all workspace symbols
- Default keymaps:
- `<C-l>`: show autocompletion menu to prefilter your query by type of
symbol you want to see (i.e. `:variable:`)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is false)
builtin.lsp_document_diagnostics({opts}) *builtin.lsp_document_diagnostics()*
Lists LSP diagnostics for the current buffer
- Default keymaps:
- `<C-l>`: show autocompletion menu to prefilter your query with the
diagnostic you want to see (i.e. `:warning:`)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is false)
builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()*
Lists LSP diagnostics for the current workspace if supported, otherwise
searches in all open buffers
- Default keymaps:
- `<C-l>`: show autocompletion menu to prefilter your query with the
diagnostic you want to see (i.e. `:warning:`)
Parameters: ~
{opts} (table) options to pass to the picker
Fields: ~
{hide_filename} (boolean) if true, hides the name of the file in the
current picker (default is false)
================================================================================
*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.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.
- `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
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`
`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.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)
-- 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
TODO: I would like to make these link to `telescope.layout_strategies.*`, but
it's not yet possible.
Available layout strategies include:
- horizontal:
- See |layout_strategies.horizontal|
- vertical:
- See |layout_strategies.vertical|
- flex:
- See |layout_strategies.flex|
Available tweaks to the settings in layout defaults include (can be applied to
horizontal and vertical layouts):
- mirror (default is `false`):
- Flip the view of the current layout:
- If using horizontal: if `true`, swaps the location of the
results/prompt window and preview window
- If using vertical: if `true`, swaps the location of the results and
prompt windows
- width_padding:
- How many cells to pad the width of Telescope's layout window
- height_padding:
- How many cells to pad the height of Telescope's layout window
- preview_width:
- Change the width of Telescope's preview window
- scroll_speed:
- Change the scrolling speed of the previewer
layout_strategies.horizontal() *layout_strategies.horizontal()*
Horizontal previewer
+-------------+--------------+
| | |
| Results | |
| | Preview |
| | |
+-------------| |
| Prompt | |
+-------------+--------------+
layout_strategies.center() *layout_strategies.center()*
Centered layout wih smaller default sizes (I think)
+--------------+
| Preview |
+--------------+
| Prompt |
+--------------+
| Result |
| Result |
| Result |
+--------------+
layout_strategies.vertical() *layout_strategies.vertical()*
Vertical perviewer stacks the items on top of each other.
+-----------------+
| Previewer |
| Previewer |
| Previewer |
+-----------------+
| Result |
| Result |
| Result |
+-----------------+
| Prompt |
+-----------------+
layout_strategies.flex() *layout_strategies.flex()*
Swap between `horizontal` and `vertical` strategies based on the window
width
- Supports `vertical` or `horizontal` features
Uses:
- flip_columns
- flip_lines
vim:tw=78:ts=8:ft=help:norl:
Reference in New Issue View Git Blame Copy Permalink