retrovim 0.0.3

package/nvim/plugins/mini.nvim/doc/mini-diff.txt

@@ -0,0 +1,661 @@
+*mini.diff* Work with diff hunks
+
+MIT License Copyright (c) 2024 Evgeni Chasnovski
+
+------------------------------------------------------------------------------
+                                                                      *MiniDiff*
+Features:
+
+- Visualize difference between buffer text and its configurable reference
+  interactively (updates as you type). This is done per line showing whether
+  it is inside added, changed, or deleted part of difference (called hunk).
+  Visualization can be with customizable colored signs or line numbers.
+
+- Special toggleable overlay view with more hunk details inside text area.
+  See |MiniDiff.toggle_overlay()|.
+
+- Completely configurable per buffer source(s) of reference text used to keep
+  it up to date and define interactions with it. Can be array of sources which
+  are attempted to attach in order. See |MiniDiff-source-specification|.
+  By default uses Git source. See |MiniDiff.gen_source.git()|.
+
+- Configurable mappings to manage diff hunks:
+    - Apply and reset hunks inside region (selected visually or with
+      a dot-repeatable operator).
+    - "Hunk range under cursor" textobject to be used as operator target.
+    - Navigate to first/previous/next/last hunk. See |MiniDiff.goto_hunk()|.
+
+What it doesn't do:
+
+- Provide functionality to work directly with Git outside of visualizing
+  and staging (applying) hunks with (default) Git source. In particular,
+  unstaging hunks is not supported. See |MiniDiff.gen_source.git()|.
+
+Sources with more details:
+- |MiniDiff-overview|
+- |MiniDiff-source-specification|
+- |MiniDiff-hunk-specification|
+- |MiniDiff-diff-summary|
+
+# Setup ~
+
+This module needs a setup with `require('mini.diff').setup({})` (replace
+`{}` with your `config` table). It will create global Lua table `MiniDiff`
+which you can use for scripting or manually (with `:lua MiniDiff.*`).
+
+See |MiniDiff.config| for `config` structure and default values.
+
+You can override runtime config settings locally to buffer inside
+`vim.b.minidiff_config` which should have same structure as
+`MiniDiff.config`. See |mini.nvim-buffer-local-config| for more details.
+
+# Comparisons ~
+
+- [lewis6991/gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim):
+    - Main inspiration for this module, so there are many similarities.
+    - Can display only Git hunks, while this module has extensible design.
+    - Provides more functionality to work with Git outside of hunks.
+      This module does not (by design).
+
+# Highlight groups ~
+*MiniDiff-hl-groups*
+
+- `MiniDiffSignAdd`        - "add" hunk lines visualization.
+- `MiniDiffSignChange`     - "change" hunk lines visualization.
+- `MiniDiffSignDelete`     - "delete" hunk lines visualization.
+- `MiniDiffOverAdd`        - added buffer text shown in overlay.
+- `MiniDiffOverChange`     - changed reference text shown in overlay.
+- `MiniDiffOverChangeBuf`  - changed buffer text shown in overlay.
+- `MiniDiffOverContext`    - context of a change shown in reference overlay.
+- `MiniDiffOverContextBuf` - context of a change shown in buffer overlay.
+- `MiniDiffOverDelete`     - deleted reference text shown in overlay.
+
+To change any highlight group, set it directly with |nvim_set_hl()|.
+
+# Disabling ~
+
+To temporarily disable features without relying on |MiniDiff.disable()|,
+set `vim.g.minidiff_disable` (globally) or `vim.b.minidiff_disable` (for
+a buffer) to `true`. Considering high number of different scenarios and
+customization intentions, writing exact rules for disabling module's
+functionality is left to user.
+See |mini.nvim-disabling-recipes| for common recipes.
+
+------------------------------------------------------------------------------
+                                                             *MiniDiff-overview*
+# Diffs and hunks ~
+
+The "diff" (short for "difference") is a result of computing how two text
+strings differ from one another. This is done on per line basis, i.e. the
+goal is to compute sequences of lines common to both files, interspersed
+with groups of differing lines (called "hunks").
+
+Although computing diff is a general concept (used on its own, in Git, etc.),
+this module computes difference between current text in a buffer and some
+reference text which is kept up to date specifically for that buffer.
+For example, default reference text is computed as file content in Git index.
+This can be customized in `config.source` (see |MiniDiff-source-specification|).
+
+# Hunk specification ~
+*MiniDiff-hunk-specification*
+
+Hunk describes two sets (one from buffer text, one - from reference) of
+consecutive lines which are different. In this module hunk is stored as
+a table with the following fields:
+
+- <buf_start> `(number)` - start of hunk buffer lines. First line is 1.
+  Can be 0 if first reference lines are deleted.
+
+- <buf_count> `(number)` - number of consecutive buffer lines. Can be 0 in
+  case reference lines are deleted.
+
+- <ref_start> `(number)` - start of hunk reference lines. First line is 1.
+  Can be 0 if lines are added before first reference line.
+
+- <ref_count> `(number)` - number of consecutive reference lines. Can be 0 in
+  case buffer lines are added.
+
+- <type> `(string)` - hunk type. Can be one of:
+    - "add" - lines are present in buffer but absent in reference.
+    - "change" - lines are present in both buffer and reference.
+    - "delete" - lines are absent in buffer but present in reference.
+
+# Life cycle ~
+
+- When entering proper (not already enabled, valid, showing text) buffer,
+  it is attempted to be enabled for diff processing.
+- During enabling, attempt attaching the source. This should set up how
+  reference text is kept up to date.
+- On every text change, diff computation is scheduled in debounced fashion
+  after customizable delay (200 ms by default).
+- After the diff is computed, do the following:
+    - Update visualization based on configurable style: either by placing
+      colored text in sign column or coloring line numbers. Colors for both
+      styles are defined per hunk type in corresponding `MiniDiffSign*`
+      highlight group (see |mini.diff|) and sign text for "sign" style can
+      be configured in `view.signs` of |MiniDiff.config|.
+    - Update overlay view (if it is enabled).
+    - Update `vim.b.minidiff_summary` and `vim.b.minidiff_summary_string`
+      buffer-local variables. These can be used, for example, in statusline.
+    - *MiniDiff-update-event* Trigger `MiniDiffUpdated` `User` event.
+      See |MiniDiff-diff-summary| for example of how to use it.
+
+Notes:
+- Use |:edit| to reset (disable and re-enable) current buffer.
+- To work with BOM bytes, set |'bomb'| and have `ucs-bom` in |'fileencodings'|.
+
+# Overlay ~
+
+Along with basic visualization, there is a special view called "overlay".
+Although it is meant for temporary overview of diff details and can be
+manually toggled via |MiniDiff.toggle_overlay()|, text can be changed with
+overlay reacting accordingly.
+
+It shows more diff details inside text area:
+
+- Added buffer lines are highlighted with `MiniDiffOverAdd` highlight group.
+
+- Deleted reference lines are shown as virtual lines and highlighted with
+  `MiniDiffOverDelete` highlight group.
+
+- "Change" hunks with equal number of buffer/reference lines show "word diff".
+  This is usually the case when `options.linematch` is enabled (as by default).
+  Reference line is shown next to its buffer counterpart. Changed parts are
+  highlighted with `MiniDiffOverChange` and `MiniDiffOverChangeBuf` in reference
+  and buffer lines. The rest of lines have `MiniDiffOverContext`
+  and `MiniDiffOverContextBuf` highlighting.
+
+  Change with unequal number of buffer/reference lines is shown with reference
+  part as virtual lines highlighted with `MiniDiffOverChange` group.
+  Corresponding buffer lines are treated as context for the change and are
+  highlighted with `MiniDiffOverContextBuf` group.
+
+Notes:
+- Word diff has non-zero context width. This means if changed characters
+  are close enough, whole range between them is also colored. This usually
+  reduces visual noise.
+- Virtual lines above line 1 (like deleted or changed lines) need manual
+  scroll to become visible (with |CTRL-Y|).
+
+# Mappings ~
+
+This module provides mappings for common actions with diffs, like:
+- Apply and reset hunks.
+- "Hunk range under cursor" textobject.
+- Go to first/previous/next/last hunk range.
+
+Examples:
+- `vip` followed by `gh` / `gH` applies/resets hunks inside current paragraph.
+  Same can be achieved in operator form `ghip` / `gHip`, which has the
+  advantage of being dot-repeatable (see |single-repeat|).
+- `gh_` / `gH_` applies/resets current line (even if it is not a full hunk).
+- `ghgh` / `gHgh` applies/resets hunk range under cursor.
+- `dgh` deletes hunk range under cursor.
+- `[H` / `[h` / `]h` / `]H` navigate cursor to the first / previous / next / last
+  hunk range of the current buffer.
+
+Mappings for some functionality are assumed to be done manually.
+See |MiniDiff.operator()|.
+
+# Buffer-local variables ~
+*MiniDiff-diff-summary*
+
+Each enabled buffer has the following buffer-local variables which can be
+used in custom statusline to show an overview of hunks in current buffer:
+
+- `vim.b.minidiff_summary` is a table with the following fields:
+    - `source_name` - name of the active source. This is the only present field
+      if buffer's reference text is not (yet) set.
+    - `n_ranges` - number of hunk ranges (sequences of contiguous hunks).
+    - `add` - number of added lines.
+    - `change` - number of changed lines.
+    - `delete` - number of deleted lines.
+
+- `vim.b.minidiff_summary_string` is a string representation of summary
+  with a fixed format. Empty string if there is no reference text (yet).
+  It is expected to be used as is. To achieve different formatting, use
+  `vim.b.minidiff_summary` to construct one. The best way to do this is by
+  overriding `vim.b.minidiff_summary_string` inside |MiniDiff-update-event|: >lua
+
+  local format_summary = function(data)
+    local summary = vim.b[data.buf].minidiff_summary
+    local t = {}
+    if summary.add > 0 then table.insert(t, '+' .. summary.add) end
+    if summary.change > 0 then table.insert(t, '~' .. summary.change) end
+    if summary.delete > 0 then table.insert(t, '-' .. summary.delete) end
+    vim.b[data.buf].minidiff_summary_string = table.concat(t, ' ')
+  end
+  local au_opts = { pattern = 'MiniDiffUpdated', callback = format_summary }
+  vim.api.nvim_create_autocmd('User', au_opts)
+<
+------------------------------------------------------------------------------
+                                                              *MiniDiff.setup()*
+                           `MiniDiff.setup`({config})
+Module setup
+
+Parameters ~
+{config} `(table|nil)` Module config table. See |MiniDiff.config|.
+
+Usage ~
+>lua
+  require('mini.diff').setup() -- use default config
+  -- OR
+  require('mini.diff').setup({}) -- replace {} with your config table
+<
+------------------------------------------------------------------------------
+                                                               *MiniDiff.config*
+                               `MiniDiff.config`
+Defaults ~
+>lua
+  MiniDiff.config = {
+    -- Options for how hunks are visualized
+    view = {
+      -- Visualization style. Possible values are 'sign' and 'number'.
+      -- Default: 'number' if line numbers are enabled, 'sign' otherwise.
+      style = vim.go.number and 'number' or 'sign',
+
+      -- Signs used for hunks with 'sign' view
+      signs = { add = '▒', change = '▒', delete = '▒' },
+
+      -- Priority of used visualization extmarks
+      priority = 199,
+    },
+
+    -- Source(s) for how reference text is computed/updated/etc
+    -- Uses content from Git index by default
+    source = nil,
+
+    -- Delays (in ms) defining asynchronous processes
+    delay = {
+      -- How much to wait before update following every text change
+      text_change = 200,
+    },
+
+    -- Module mappings. Use `''` (empty string) to disable one.
+    mappings = {
+      -- 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.text.diff()`)
+      algorithm = 'histogram',
+
+      -- Whether to use "indent heuristic" (see `:h vim.text.diff()`)
+      indent_heuristic = true,
+
+      -- The amount of second-stage diff to align lines
+      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 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.hl.priorities|) to have higher priority than automated
+extmarks but not as in user enabled ones.
+
+# Source ~
+*MiniDiff-source-specification*
+
+`config.source` is a table with single source or array of them. Single source
+defines how reference text is managed in a particular buffer. Sources in array
+are attempted to attach in order; call |MiniDiff.disable()| if none attaches.
+
+A single source table can have the following fields:
+
+- <attach> `(function)` - callable which defines how and when reference text
+  is updated inside a particular buffer. It is used 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 indicate that attach has failed. If attach fail can
+  not be inferred immediately (for example, due to asynchronous execution),
+  should explicitly call |MiniDiff.fail_attach()| with appropriate arguments.
+  This is important to properly process array of sources.
+
+  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: a single |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 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.text.diff()| (|vim.diff()| on Neovim<=0.11)
+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.text.diff()| (|vim.diff()| on Neovim<=0.11) 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: