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

mini-diff.txt

Latest commit

 

History

History
658 lines (508 loc) · 27 KB

mini-diff.txt

File metadata and controls

658 lines (508 loc) · 27 KB
Raw
text change (in debounced fashion) before updating diff and visualization.
Default: 200.
# Mappings ~
`config.mappings` contains keys which are mapped during |MiniDiff.setup()|.
`mappings.apply` keys can be used to apply hunks inside visual/operator region.
What exactly "apply hunks" means depends on the source and its `apply_hunks()`.
For example, in default Git source it means stage hunks.
`mappings.reset` keys can be used to reset hunks inside visual/operator region.
Reset means replacing buffer text in region with corresponding reference text.
`mappings.textobject` keys define "hunk range under cursor" textobject
which can be used in Operator-pending mode as target for operator (like
|d|, |y|, apply/reset hunks, etc.). It is also set up in Visual mode if
keys do not conflict with `mappings.apply` and `mappings.reset`.
"Hunk range" is used in a sense that contiguous (back-to-back) hunks are
considered as parts of a same hunk range.
`mappings.goto_first` / `mappings.goto_prev` / `mappings.goto_next` /
`mappings.goto_last` keys can be used to navigate to first / previous / next /
last hunk range in the current buffer.
# Options ~
`config.options` contains various customization options.
`options.algorithm` is a string defining which diff algorithm to use.
Default: "histogram". See |vim.diff()| for possible values.
`options.indent_heuristic` is a boolean defining whether to use indent
heuristic for a (possibly) more naturally aligned hunks.
Default: `true`.
`options.linematch` is a number defining hunk size for which a second
stage diff is executed for a better aligned and more granular hunks.
Default: 60. See |vim.diff()| and 'diffopt' for more details.
`options.wrap_goto` is a boolean indicating whether to wrap around edges during
hunk navigation (with |MiniDiff.goto_hunk()| or `goto_*` mappings). Like if
cursor is after the last hunk, going "next" will put cursor on the first hunk.
Default: `false`.
------------------------------------------------------------------------------
*MiniDiff.enable()*
`MiniDiff.enable`({buf_id})
Enable diff processing in buffer
Parameters ~
{buf_id} `(number)` Target buffer identifier. Default: 0 for current buffer.
------------------------------------------------------------------------------
*MiniDiff.disable()*
`MiniDiff.disable`({buf_id})
Disable diff processing in buffer
Parameters ~
{buf_id} `(number)` Target buffer identifier. Default: 0 for current buffer.
------------------------------------------------------------------------------
*MiniDiff.toggle()*
`MiniDiff.toggle`({buf_id})
Toggle diff processing in buffer
Enable if disabled, disable if enabled.
Parameters ~
{buf_id} `(number)` Target buffer identifier. Default: 0 for current buffer.
------------------------------------------------------------------------------
*MiniDiff.toggle_overlay()*
`MiniDiff.toggle_overlay`({buf_id})
Toggle overlay view in buffer
Parameters ~
{buf_id} `(number)` Target buffer identifier. Default: 0 for current buffer.
------------------------------------------------------------------------------
*MiniDiff.export()*
`MiniDiff.export`({format}, {opts})
Export hunks
Get and convert hunks from current/all buffers. Example of using it: >lua
-- Set quickfix list from all available hunks
vim.fn.setqflist(MiniDiff.export('qf'))
<
Parameters ~
{format} `(string)` Output format. Currently only `'qf'` value is supported.
{opts} `(table|nil)` Options. Possible fields:
- <scope> `(string)` - scope defining from which buffers to use hunks.
One of "all" (all enabled buffers) or "current".
Return ~
`(table)` Result of export. Depends on the `format`:
- If "qf", an array compatible with |setqflist()| and |setloclist()|.
------------------------------------------------------------------------------
*MiniDiff.get_buf_data()*
`MiniDiff.get_buf_data`({buf_id})
Get buffer data
Parameters ~
{buf_id} `(number)` Target buffer identifier. Default: 0 for current buffer.
Return ~
`(table|nil)` Table with buffer diff data or `nil` if buffer is not enabled.
Table has the following fields:
- <config> `(table)` - config used for this particular buffer.
- <hunks> `(table)` - array of hunks. See |MiniDiff-hunk-specification|.
- <overlay> `(boolean)` - whether an overlay view is shown.
- <ref_text> `(string|nil)` - current value of reference text. Lines are
separated with newline character (`'\n'`). Can be `nil` indicating that
reference text was not yet set (for example, if source did not yet react).
- <summary> `(table)` - overall diff summary. See |MiniDiff-diff-summary|.
------------------------------------------------------------------------------
*MiniDiff.set_ref_text()*
`MiniDiff.set_ref_text`({buf_id}, {text})
Set reference text for the buffer
Note: this will call |MiniDiff.enable()| for target buffer if it is not
already enabled.
Parameters ~
{buf_id} `(number)` Target buffer identifier. Default: 0 for current buffer.
{text} `(string|table)` New reference text. Either a string with `\n` used to
separate lines or array of lines. Use empty table to unset current
reference text (results into no hunks shown). Default: `{}`.
Note: newline character is appended at the end (if it is not there already)
for better diffs.
------------------------------------------------------------------------------
*MiniDiff.gen_source*
`MiniDiff.gen_source`
Generate builtin sources
This is a table with function elements. Call to actually get source.
Examples: >lua
local diff = require('mini.diff')
-- Single `save` source
diff.setup({ source = diff.gen_source.save() })
-- Multiple sources (attempted to attach in order)
diff.setup({ source = { diff.gen_source.git(), diff.gen_source.save() } })
<
------------------------------------------------------------------------------
*MiniDiff.gen_source.git()*
`MiniDiff.gen_source.git`()
Git source
Default source. Uses file text from Git index as reference. This results in:
- "Add" hunks represent text present in current buffer, but not in index.
- "Change" hunks represent modified text already present in index.
- "Delete" hunks represent text deleted from index.
Applying hunks means staging, a.k.a adding to index.
Notes:
- Requires Git version at least 2.38.0.
- There is no capability for unstaging hunks. Use full Git client for that.
Return ~
`(table)` Source. See |MiniDiff-source-specification|.
------------------------------------------------------------------------------
*MiniDiff.gen_source.none()*
`MiniDiff.gen_source.none`()
"Do nothing" source
Allows buffers to be enabled while not setting any reference text.
Use this if the goal is to rely on manual |MiniDiff.set_ref_text()| calls.
Return ~
`(table)` Source. See |MiniDiff-source-specification|.
------------------------------------------------------------------------------
*MiniDiff.gen_source.save()*
`MiniDiff.gen_source.save`()
Latest save source
Uses text at latest save as the reference. This results into diff showing
difference after the latest save.
Return ~
`(table)` Source. See |MiniDiff-source-specification|.
------------------------------------------------------------------------------
*MiniDiff.do_hunks()*
`MiniDiff.do_hunks`({buf_id}, {action}, {opts})
Perform action on hunks in region
Compute hunks inside a target region (even for hunks only partially inside it)
and perform apply/reset/yank operation on them.
The "yank" action yanks all reference lines of target hunks into
a specified register (should be one of |registers|).
Notes:
- Whether hunk is inside a region is computed based on position of its
buffer lines.
- If "change" or "delete" is only partially inside a target region, all
reference lines are used in computed "intersection" hunk.
Used directly in `config.mappings.apply` and `config.mappings.reset`.
Usually there is no need to use this function manually.
See |MiniDiff.operator()| for how to set up a mapping for "yank".
Parameters ~
{buf_id} `(number)` Target buffer identifier. Default: 0 for current buffer.
{action} `(string)` One of "apply", "reset", "yank".
{opts} `(table|nil)` Options. Possible fields:
- <line_start> `(number)` - start line of the region. Default: 1.
- <line_end> `(number)` - start line of the region. Default: last buffer line.
- <register> `(string)` - register to yank reference lines into.
Default: |v:register|.
------------------------------------------------------------------------------
*MiniDiff.goto_hunk()*
`MiniDiff.goto_hunk`({direction}, {opts})
Go to hunk range in current buffer
Parameters ~
{direction} `(string)` One of "first", "prev", "next", "last".
{opts} `(table|nil)` Options. A table with fields:
- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.
- <line_start> `(number)` - Line number to start from for directions
"prev" and "next". Default: cursor line.
- <wrap> `(boolean)` - Whether to wrap around edges.
Default: `options.wrap` value of the config.
------------------------------------------------------------------------------
*MiniDiff.operator()*
`MiniDiff.operator`({mode})
Perform action over region
Perform action over region defined by marks. Used in mappings.
Example of a mapping to yank reference lines of hunk range under cursor
(assuming default 'config.mappings.textobject'): >lua
local rhs = function() return MiniDiff.operator('yank') .. 'gh' end
vim.keymap.set('n', 'ghy', rhs, { expr = true, remap = true })
<
Parameters ~
{mode} `(string)` One of "apply", "reset", "yank", or the ones used in |g@|.
------------------------------------------------------------------------------
*MiniDiff.textobject()*
`MiniDiff.textobject`()
Select hunk range textobject
Selects all contiguous lines adjacent to cursor line which are in any (not
necessarily same) hunk (if cursor line itself is in hunk).
Used in default mappings.
------------------------------------------------------------------------------
*MiniDiff.fail_attach()*
`MiniDiff.fail_attach`({buf_id})
Indicate source attach fail
Try to attach next source; if there is none - call |MiniDiff.disable()|.
Parameters ~
{buf_id} `(integer)` Buffer identifier for which attach has failed.
vim:tw=78:ts=8:noet:ft=help:norl:
0