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

Repository navigation

mini-diff.txt

Latest commit

 

History

History
638 lines (495 loc) · 26.2 KB

mini-diff.txt

File metadata and controls

638 lines (495 loc) · 26.2 KB
Raw
-- Apply hunks inside a visual/operator region
apply = 'gh',
-- Reset hunks inside a visual/operator region
reset = 'gH',
-- Hunk range textobject to be used inside operator
-- Works also in Visual mode if mapping differs from apply and reset
textobject = 'gh',
-- Go to hunk range in corresponding direction
goto_first = '[H',
goto_prev = '[h',
goto_next = ']h',
goto_last = ']H',
},
-- Various options
options = {
-- Diff algorithm. See `:h vim.diff()`.
algorithm = 'histogram',
-- Whether to use "indent heuristic". See `:h vim.diff()`.
indent_heuristic = true,
-- The amount of second-stage diff to align lines (in Neovim>=0.9)
linematch = 60,
-- Whether to wrap around edges during hunk navigation
wrap_goto = false,
},
}
<
# View ~
`config.view` contains settings for how diff hunks are visualized.
Example of using custom signs: >lua
require('mini.diff').setup({
view = {
style = 'sign',
signs = { add = '+', change = '~', delete = '-' },
},
})
<
`view.style` is a string defining visualization style. Can be one of "sign"
(as a colored sign in a |sign-column|) or "number" (colored line number).
Default: "number" if |number| option is enabled, "sign" otherwise.
Note: with "sign" style it is usually better to have |signcolumn| always shown.
`view.signs` is a table with one or two character strings used as signs for
corresponding ("add", "change", "delete") hunks.
Default: all hunks use "▒" character resulting in a contiguous colored lines.
`view.priority` is a number with priority used for visualization and
overlay |extmarks|.
Default: 199 which is one less than `user` in |vim.hl.priorities| (on Neovim<0.11
see |vim.highlight.priorities|) to have higher priority than automated
extmarks but not as in user enabled ones.
*MiniDiff-source-specification*
# Source ~
`config.source` is a table defining how reference text is managed in
a particular buffer. It can have the following fields:
- <attach> `(function)` - callable which defines how and when reference text
should be updated inside a particular buffer. It is called
inside |MiniDiff.enable()| with a buffer identifier as a single argument.
Should execute logic which results into calling |MiniDiff.set_ref_text()|
when reference text for buffer needs to be updated. Like inside callback
for an |autocommand| or file watcher (see |watch-file|).
For example, default Git source watches when ".git/index" file is changed
and computes reference text as the one from Git index for current file.
Can return `false` to force buffer to not be enabled. If this can not be
inferred immediately (for example, due to asynchronous execution), should
call |MiniDiff.disable()| later to disable buffer.
No default value, should be always supplied.
- <name> `(string|nil)` - source name. String `"unknown"` is used if not supplied.
- <detach> `(function|nil)` - callable with cleanup action to be done when
buffer is disabled. It is called inside |MiniDiff.disable()| with a buffer
identifier as a single argument.
If not supplied, nothing is done during detaching.
- <apply_hunks> `(function|nil)` - callable which defines how hunks are applied.
It is called with buffer identifier as first argument and array of hunks
(see |MiniDiff-hunk-specification|) as second. It should eventually update
reference text: either by explicitly calling |MiniDiff.set_ref_text()| or
performing action triggering its call.
For example, default Git source computes patch based on the hunks and
applies it inside file's git repo.
If not supplied, applying hunks throws an error.
Default: |MiniDiff.gen_source.git()|.
# Delay ~
`config.delay` contains settings for delays in asynchronous processes.
`delay.text_change` is a number (in ms) defining how long to wait after latest
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 a 8000 s 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.
Note: present only in Neovim>=0.9.
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.
Example of using |MiniDiff.gen_source.save()|: >lua
local diff = require('mini.diff')
diff.setup({ source = 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.
vim:tw=78:ts=8:noet:ft=help:norl:
0