8000 mini.nvim/doc/mini-extra.txt at main · tomkennedy513/mini.nvim · GitHub
[go: up one dir, main page]
Skip to content

mini-extra.txt

Latest commit

 

History

History
809 lines (650 loc) · 31.2 KB

mini-extra.txt

File metadata and controls

809 lines (650 loc) · 31.2 KB
Raw
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <cwd> `(string)` - initial directory to explore. Should be a valid
directory path. Default: `nil` for |current-directory|.
- <filter> `(function)` - callable predicate to filter items to show.
Will be called for every item and should return `true` if it should be
shown. Each item is a table with the following fields:
- <fs_type> `(string)` - path type. One of "directory" or "file".
- <path> `(string)` - item path.
- <text> `(string)` - shown text (path's basename).
- <sort> `(function)` - callable item sorter. Will be called with array
of items (each element with structure as described above) and should
return sorted array of items.
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.git_branches()*
`MiniExtra.pickers.git_branches`({local_opts}, {opts})
Git branches picker
Pick from Git branches using `git branch`.
Notes:
- Requires executable `git`.
- Requires target path to be part of git repository.
- Present for exploration and navigation purposes. Doing any Git operations
is suggested to be done in a dedicated Git client and is not planned.
- On choose opens scratch buffer with branch's history.
Examples ~
- `MiniExtra.pickers.git_branches({ scope = 'local' })` - local branches of
the |current-directory| parent Git repository.
- `:Pick git_branches path='%'` - all branches of the current file parent
Git repository.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <path> `(string|nil)` - target path for Git operation (if required). Also
used to find Git repository inside which to construct items.
Default: `nil` for root of Git repository containing |current-directory|.
- <scope> `(string)` - branch scope to show. One of "all", "local", "remotes".
Default: "all".
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.git_commits()*
`MiniExtra.pickers.git_commits`({local_opts}, {opts})
Git commits picker
Pick from Git commits using `git log`.
Notes:
- Requires executable `git`.
- Requires target path to be part of git repository.
- Present for exploration and navigation purposes. Doing any Git operations
is suggested to be done in a dedicated Git client and is not planned.
- On choose opens scratch buffer with commit's diff.
Examples ~
- `MiniExtra.pickers.git_commits()` - all commits from parent Git
repository of |current-directory|.
- `MiniExtra.pickers.git_commits({ path = 'subdir' })` - commits affecting
files from 'subdir' subdirectory.
- `:Pick git_commits path='%'` commits affecting current file.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <path> `(string|nil)` - target path for Git operation (if required). Also
used to find Git repository inside which to construct items.
Default: `nil` for root of Git repository containing |current-directory|.
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.git_files()*
`MiniExtra.pickers.git_files`({local_opts}, {opts})
Git files picker
Pick from Git files using `git ls-files`.
Notes:
- Requires executable `git`.
- Requires target path to be part of git repository.
- Present for exploration and navigation purposes. Doing any Git operations
is suggested to be done in a dedicated Git client and is not planned.
Examples ~
- `MiniExtra.pickers.git_files({ scope = 'ignored' })` - ignored files from
parent Git repository of |current-directory|.
- `:Pick git_files path='subdir' scope='modified'` - files from 'subdir'
subdirectory which are ignored by Git.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <path> `(string|nil)` - target path for Git operation (if required). Also
used to find Git repository inside which to construct items.
Default: `nil` for root of Git repository containing |current-directory|.
- <scope> `(string)` - files scope to show. One of
- "tracked" (`--cached` Git flag).
- "modified" (`--modified` Git flag).
- "untracked" (`--others` Git flag).
- "ignored" (`--ignored` Git flag).
- "deleted" (`--deleted` Git flag).
Default: "tracked".
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.gi 8BD0 t_hunks()*
`MiniExtra.pickers.git_hunks`({local_opts}, {opts})
Git hunks picker
Pick from Git hunks using `git diff`.
Notes:
- Requires executable `git`.
- Requires target path to be part of git repository.
- Present for exploration and navigation purposes. Doing any Git operations
is suggested to be done in a dedicated Git client and is not planned.
- On choose navigates to hunk's first change.
Examples ~
- `MiniExtra.pickers.git_hunks({ scope = 'staged' })` - staged hunks from
parent Git repository of |current-directory|.
- `:Pick git_hunks path='%' n_context=0` - hunks from current file computed
with no context.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <n_context> `(number)` - number of context lines to show in hunk's preview.
Default: 3.
- <path> `(string|nil)` - target path for Git operation (if required). Also
used to find Git repository inside which to construct items.
Default: `nil` for root of Git repository containing |current-directory|.
- <scope> `(string)` - hunks scope to show. One of "unstaged" or "staged".
Default: "unstaged".
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.hipatterns()*
`MiniExtra.pickers.hipatterns`({local_opts}, {opts})
Matches from 'mini.hipatterns' picker
Pick from |MiniHipatterns| matches using |MiniHipatterns.get_matches()|.
Notes:
- Requires 'mini.hipatterns'.
- Highlighter identifier is highlighted with its highlight group.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <scope> `(string)` - one of "all" (buffers with enabled 'mini.hipatterns')
or "current" (buffer). Default: "all".
- <highlighters> `(table|nil)` - highlighters for which to find matches.
Forwarded to |MiniHipatterns.get_matches()|. Default: `nil`.
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.history()*
`MiniExtra.pickers.history`({local_opts}, {opts})
Neovim history picker
Pick from output of |:history|.
Notes:
- Has no preview.
- Choosing action depends on scope:
- For "cmd" / ":" scopes, the command is executed.
- For "search" / "/" / "?" scopes, search is redone.
- For other scopes nothing is done (but chosen item is still returned).
Examples ~
- Command history: `MiniExtra.pickers.history({ scope = ':' })`
- Search history: `:Pick history scope='/'`
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <scope> `(string)` - any allowed {name} flag of |:history| command.
Note: word abbreviations are not allowed. Default: "all".
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.hl_groups()*
`MiniExtra.pickers.hl_groups`({local_opts}, {opts})
Highlight groups picker
Pick and preview highlight groups.
Notes:
- Item line is colored with same highlight group it represents.
- Preview shows highlight's definition (as in |:highlight| with {group-name}).
- Choosing places highlight definition in Command line to update and apply.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Not used at the moment.
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.keymaps()*
`MiniExtra.pickers.keymaps`({local_opts}, {opts})
Neovim keymaps picker
Pick and preview data about Neovim keymaps.
Notes:
- Item line contains data about keymap mode, whether it is buffer local, its
left hand side, and inferred description.
- Preview shows keymap data or callback source (if present and reachable).
- Choosing emulates pressing the left hand side of the keymap.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <mode> `(string)` - modes to show. One of "all" or appropriate mode
for |nvim_set_keymap()|. Default: "all".
- <scope> `(string)` - scope to show. One of "all", "global", "buf".
Default: "all".
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.list()*
`MiniExtra.pickers.list`({local_opts}, {opts})
Neovim lists picker
Pick and navigate to elements of the following Neovim lists:
- |quickfix| list.
- |location-list| of current window.
- |jumplist|.
- |changelist|.
Note: it requires explicit `scope`.
Examples ~
- `MiniExtra.pickers.list({ scope = 'quickfix' })` - quickfix list.
- `:Pick list scope='jump'` - jump list.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <scope> `(string)` - type of list to show. One of "quickfix", "location",
"jump", "change". Default: `nil` which means explicit scope is needed.
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.lsp()*
`MiniExtra.pickers.lsp`({local_opts}, {opts})
LSP picker
Pick and navigate with LSP methods.
Notes:
- Needs an explicit scope from a list of supported ones:
- "declaration".
- "definition".
- "document_symbol".
- "implementation".
- "references".
- "type_definition".
- "workspace_symbol".
- Directly relies on `vim.lsp.buf` methods which support |lsp-on-list-handler|.
In particular, it means that picker is started only if LSP server returns
list of locations and not a single location.
- Doesn't return anything due to async nature of `vim.lsp.buf` methods.
- Requires set up |mini.icons| to show extra icons and highlighting in
"document_symbol" and "workspace_symbol" scopes.
Examples ~
- `MiniExtra.pickers.lsp({ scope = 'references' })` - references of the symbol
under cursor.
- `:Pick lsp scope='document_symbol'` - symbols in current file.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <scope> `(string)` - LSP method to use. One of the supported ones (see
list above). Default: `nil` which means explicit scope is needed.
- <symbol_query> `(string)` - query for |vim.lsp.buf.workspace_symbol()|.
Default: empty string for all symbols (according to LSP specification).
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(nil)` Nothing is returned.
------------------------------------------------------------------------------
*MiniExtra.pickers.marks()*
`MiniExtra.pickers.marks`({local_opts}, {opts})
Neovim marks picker
Pick and preview position of Neovim |mark|s.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <scope> `(string)` - scope to show. One of "all", "global", "buf".
Default: "all".
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.oldfiles()*
`MiniExtra.pickers.oldfiles`({local_opts}, {opts})
Old files picker
Pick from |v:oldfiles| entries representing readable files.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <current_dir> `(boolean)` - whether to return files only from current
working directory and its subdirectories. Default: `false`.
- <preserve_order> `(boolean)` - whether to preserve original order
during query. Default: `false`.
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.options()*
`MiniExtra.pickers.options`({local_opts}, {opts})
Neovim options picker
Pick and preview data about Neovim options.
Notes:
- Item line is colored based on whether it was set (dimmed if wasn't).
- Preview shows option value in target window and its general information.
- Choosing places option name in Command line to update and apply.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <scope> `(string)` - options to show. One of "all", "global", "win", "buf".
Default: "all".
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.registers()*
`MiniExtra.pickers.registers`({local_opts}, {opts})
Neovim registers picker
Pick from Neovim |registers|.
Notes:
- There is no preview (all information is in the item's text).
- Choosing pastes content of a register: with |i_CTRL-R| in Insert mode,
|c_CTRL-R| in Command-line mode, and |P| otherwise.
Expression register |quote=| is reevaluated (if present) and pasted.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Not used at the moment.
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.spellsuggest()*
`MiniExtra.pickers.spellsuggest`({local_opts}, {opts})
Neovim spell suggestions picker
Pick and apply spell suggestions.
Notes:
- No preview is available.
- Choosing replaces current word (|<cword>|) with suggestion.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <n_suggestions> `(number)` - number of spell suggestions. Default: 25.
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.treesitter()*
`MiniExtra.pickers.treesitter`({local_opts}, {opts})
Tree-sitter nodes picker
Pick and navigate to |treesitter| nodes of current buffer.
Notes:
- Requires active tree-sitter parser in the current buffer.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Not used at the moment.
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.visit_paths()*
`MiniExtra.pickers.visit_paths`({local_opts}, {opts})
Visit paths from 'mini.visits' picker
Pick paths from |MiniVisits| using |MiniVisits.list_paths()|.
Notes:
- Requires 'mini.visits'.
Examples ~
- `MiniExtra.pickers.visit_paths()` - visits registered for |current-directory|
and ordered by "robust frecency".
- `:Pick visit_paths cwd='' recency_weight=1 filter='core'` - all visits with
"core" label ordered from most to least recent.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <cwd> `(string)` - forwarded to |MiniVisits.list_paths()|.
Default: `nil` to get paths registered for |current-directory|.
- <filter> `(function|string)` - forwarded to |MiniVisits.list_paths()|.
Default: `nil` to use all paths.
- <preserve_order> `(boolean)` - whether to preserve original order
during query. Default: `false`.
- <recency_weight> `(number)` - forwarded to |MiniVisits.gen_sort.default()|.
Default: 0.5 to use "robust frecency" sorting.
- <sort> `(function)` - forwarded to |MiniVisits.list_paths()|.
Default: `nil` to use "robust frecency".
Note: if supplied, has precedence over `recency_weight`.
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
`(any)` Output of the called picker.
------------------------------------------------------------------------------
*MiniExtra.pickers.visit_labels()*
`MiniExtra.pickers.visit_labels`({local_opts}, {opts})
Visit labels from 'mini.visits' picker
Pick labels from |MiniVisits| using |MiniVisits.list_labels()|
and |MiniVisits.list_paths()|.
Notes:
- Requires 'mini.visits'.
- Preview shows target visit paths filtered to those having previewed label.
- Choosing essentially starts |MiniExtra.pickers.visit_paths()| for paths
with the chosen label.
Examples ~
- `MiniExtra.pickers.visit_labels()` - labels from visits registered
for |current-directory|.
- `:Pick visit_labels cwd=''` - labels from all visits.
Parameters ~
{local_opts} `(table|nil)` Options defining behavior of this particular picker.
Possible fields:
- <cwd> `(string)` - forwarded to |MiniVisits.list_labels()|.
Default: `nil` to get labels from visits registered for |current-directory|.
- <filter> `(function|string)` - forwarded to |MiniVisits.list_labels()|.
Default: `nil` to use all visits.
- <path> `(string)` - forwarded to |MiniVisits.list_labels()|.
Default: `""` to get labels from all visits for target `cwd`.
- <sort> `(function)` - forwarded to |MiniVisits.list_paths()| for
preview and choose. Default: `nil` to use "robust frecency".
{opts} `(table|nil)` Options forwarded to |MiniPick.start()|.
Return ~
Chosen path.
vim:tw=78:ts=8:noet:ft=help:norl:
0