[mini.diff] Support truly empty (0-line) reference text

[zane]

Contributing guidelines

• I have read CONTRIBUTING.md
• I have read CODE_OF_CONDUCT.md

Module(s)

mini.diff

Description

Thanks for mini.nvim! My whole config is built on it, and mini.diff's pluggable sources made a custom Jujutsu source straightforward.

What it should be able to do

MiniDiff.set_ref_text() currently has no way to represent a reference of zero lines. All inputs normalize to at least one line, or unset the reference entirely:

• set_ref_text(buf, "") becomes "\n" after the trailing newline append, i.e. a one-blank-line reference, not an empty one.
• set_ref_text(buf, {}) converts to nil and unsets the reference (no hunks at all).
• set_ref_text(buf, { "" }) is the same as "".

The append is documented ("Appending '\n' makes more intuitive diffs at end-of-file"). The request is only an escape hatch for the empty case: some way to set a genuinely empty (0-line) reference so that the whole buffer reads as added.

Why

Custom sources for other VCS (e.g. the Jujutsu and Mercurial sources discussed in #1878) diff against a parent revision, where "file was just added" is a normal state to visualize. The natural encoding is an empty reference with the whole buffer shown as added. With the current behavior, the diff pairs the buffer's first blank line with the reference's phantom blank line, so that one line shows as unchanged context in the middle of an otherwise fully-added file.

Reproduction

-- nvim --clean, with 'mini.nvim' on 'runtimepath'
local diff = require('mini.diff')
diff.setup({ source = diff.gen_source.none() })

local buf = vim.api.nvim_create_buf(true, false)
vim.api.nvim_buf_set_lines(buf, 0, -1, false, { 'line A', '', 'line B' })
diff.enable(buf)
diff.set_ref_text(buf, '')

vim.defer_fn(function()
  local d = diff.get_buf_data(buf)
  print(vim.inspect(d.ref_text)) -- "\n" (one blank line, not zero)
  print(vim.inspect(d.hunks))
  -- add hunk for line 1, add hunk for line 3;
  -- blank line 2 is not part of any hunk
end, 100)

Version info

Reproduced on a 2025-11-20 build and confirmed the set_ref_text logic is unchanged on current main. Neovim 0.11.7, macOS (aarch64).

[echasnovski]

Thanks for the suggestion!

MiniDiff.set_ref_text() currently has no way to represent a reference of zero lines.

That was indeed intentional with the logic of "if there is no reference text, there is nothing to compare against".

Custom sources for other VCS (e.g. the Jujutsu and Mercurial sources discussed in #1878) diff against a parent revision, where "file was just added" is a normal state to visualize. The natural encoding is an empty reference with the whole buffer shown as added. With the current behavior, the diff pairs the buffer's first blank line with the reference's phantom blank line, so that one line shows as unchanged context in the middle of an otherwise fully-added file.

This sounds reasonable. If allowed, the most natural solution would be to: treat {} as "no lines" (opposed to '' which is one empty line) and nil as "unset current reference text". I worry, however, about backward compatibility for the first part, since {} is documented as "unset current reference text (results into no hunks shown)".

There is also a path of adding opts with something like opts.allow_empty. With default false this is backward compatible, but adding an option for this (relatively infrequent in my opinion) use case seems to be too much.

I'll think about it.