DOCSEARCHbyAlgolia
Submit Docs

mini.diff

repository·main·Indexed 42 days ago

https://github.com/nvim-mini/mini.diff

A Neovim module for interactive visualization of differences between a buffer's current text and a reference source, such as the Git index. It provides features for navigating, applying, and resetting diff hunks, as well as an overlay view for detailed word-level diffs and statusline integration for diff summaries.

Tokens
1.4K
Snippets
3
Records
5
Agent score
3%

What's inside mini.diff

  1. Use the overlay view for detailed diffs

    main

    The overlay view provides an enhanced, temporary view of diff details directly inside the text area. It can be toggled using MiniDiff.toggle_overlay().

    In overlay mode:

    • Added lines are highlighted with MiniDiffOverAdd.
    • Deleted reference lines appear as virtual text with MiniDiffOverDelete.
    • Changed reference lines appear as virtual text with MiniDiffOverChange.
    • Word diffs: If config.options.linematch is enabled and a change hunk has an equal number of buffer and reference lines, a word-level diff is shown. The reference line is displayed next to the buffer line, with changed parts highlighted by MiniDiffOverChange and the rest by MiniDiffOverContext.

  2. Manage diff hunks with mappings and textobjects

    main

    Mini.diff provides several ways to interact with hunks:

    Hunk Navigation

    Navigate between hunk ranges using:

    • [H / [h: First / Previous hunk
    • ]h / ]H: Next / Last hunk

    Applying and Resetting Hunks

    • Region-based: Use the apply and reset mappings (default gh and gH) combined with a visual selection or an operator. For example, vip followed by gh applies hunks inside a paragraph.
    • Operator form: Use ghip (apply) or gHip (reset) for dot-repeatable operations on a paragraph.
    • Line-based: gh_ or gH_ applies/resets the current line.
    • Hunk-based: ghgh or gHgh applies/resets the hunk range under the cursor.
    • Deletion: dgh deletes the hunk range under the cursor.

    Note: Some mappings must be configured manually. See :h MiniDiff.operator() for details.

  3. Install mini.diff

    main

    You can install mini.diff as part of the mini.nvim library (recommended) or as a standalone plugin. After installation, you must call require('mini.diff').setup() to enable its functionality.

    Installation via vim.pack (Neovim 0.12+)

    Standalone (Main branch):

    vim.pack.add({ 'https://github.com/nvim-mini/mini.diff' })

    Standalone (Stable branch):

    vim.pack.add({
  { src = 'https://github.com/nvim-mini/mini.diff', version = 'stable' },
})

    Installation via mini.deps

    Standalone (Main branch):

    add('nvim-mini/mini.diff')

    Standalone (Stable branch):

    add({ source = 'nvim-mini/mini.diff', checkout = 'stable' })

    Installation via lazy.nvim

    Standalone (Main branch):

    { 'nvim-mini/mini.diff', version = false }

    Standalone (Stable branch):

    { 'nvim-mini/mini.diff', version = '*' }

    Windows Note: If you encounter "Filename too long" errors, run git config --system core.longpaths true or install the plugin in a directory with a shorter path.

    require('mini.diff').setup()

  4. Configure mini.diff options

    main

    Use the setup() function to configure how hunks are visualized, which source is used for reference text, and how mappings behave.

    Key configuration sections:

    • view: Controls visualization style ('sign' or 'number') and sign characters.
    • source: Defines the reference text source (defaults to Git index).
    • delay: Sets the debounce delay for text changes (default 200 ms).
    • mappings: Defines keys for applying/resetting hunks and navigating them.
    • options: Configures the diff algorithm, indentation heuristics, and line matching.
    require('mini.diff').setup({
  view = {
    style = 'sign',
    signs = { add = '▒', change = '▒', delete = '▒' },
  },
  mappings = {
    apply = 'gh',
    reset = 'gH',
    textobject = 'gh',
    goto_first = '[H',
    goto_prev = '[h',
    goto_next = ']h',
    goto_last = ']H',
  },
  options = {
    algorithm = 'histogram',
    linematch = 60,
  },
})

  5. Access diff summary in statusline

    main

    Mini.diff provides buffer-local variables that can be used to display a diff summary in your statusline.

    vim.b.minidiff_summary is a table containing:

    • source_name: Name of the source.
    • n_ranges: Number of hunk ranges.
    • add: Number of added lines.
    • change: Number of changed lines.
    • delete: Number of deleted lines.

    vim.b.minidiff_summary_string is a pre-formatted string. To customize the format, listen for the MiniDiffUpdated User event and update vim.b[buf].minidiff_summary_string manually.

    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)