feat(commands): add :Greview for unified diff review with qflist/loclist

Problem: diffs.nvim provides `:Gdiff` for single-file diffs and
`gdiff_section()` for staged/unstaged sections, but has no way to
view a full unified diff against an arbitrary git ref with structured
navigation.

Solution: add `M.greview(base, opts)` which creates a unified diff
buffer (`diffs://review:{base}`), parses file/hunk positions, and
populates the qflist (files with `+N`/`-M` stats) and loclist (hunks
with filename and `@@` header). Add `M.review_file_at_line()` utility,
`read_buffer()` review label case, and `:Greview` command with git
ref tab completion.

Author: barrettruth

doc/diffs.nvim.txt

@@ -26,6 +26,7 @@ Features: ~
 - Optional diff prefix (`+`/`-`/` `) concealment
 - Gutter (line number) highlighting
 - |:Gdiff| unified diff against any revision
+- |:Greview| full-repo review diff with qflist/loclist navigation
 - Email quoting/patch syntax support (`> diff ...`)
 
 ==============================================================================
@@ -449,6 +450,46 @@ COMMANDS                                                      *diffs-commands*
 :Ghdiff [revision]                                                  *:Ghdiff*
     Like |:Gdiff| but explicitly opens in a horizontal split.
 
+:Greview {base}                                                    *:Greview*
+    Open a unified diff of the entire repository against {base} (a git ref
+    such as `origin/main`, `HEAD~5`, or a commit SHA). Displays in a
+    horizontal split.
+
+    Populates the quickfix list with file entries (one per changed file,
+    with `+N`/`-M` stats) and the location list with hunk entries (one per
+    `@@` header, with filename and hunk number). All entries point into the
+    diff buffer, so |:cnext|/|:cprev| navigate between files and
+    |:lnext|/|:lprev| navigate between hunks within the buffer.
+
+    The buffer is named `diffs://review:{base}`. Reloading with |:edit|
+    refreshes the diff content.
+
+    If a `diffs://` window already exists in the current tabpage, the new
+    diff replaces its buffer instead of creating another split.
+
+    Parameters: ~
+        {base}  (string) Git ref to diff against. Required.
+
+    Examples: >vim
+        :Greview origin/main
+        :Greview HEAD~10
+        :Greview abc1234
+<
+
+    Lua API: >lua
+        require('diffs.commands').greview('origin/main')
+        require('diffs.commands').greview('origin/main', { vertical = true })
+        require('diffs.commands').greview('origin/main', { repo_root = '/path/to/repo' })
+<
+    When called from async contexts (e.g., plugin callbacks where the
+    current buffer may not be in a git repo), pass `repo_root` explicitly
+    to avoid repo detection failures.
+
+    Utilities: ~
+        `require('diffs.commands').review_file_at_line(bufnr, lnum)` returns
+        the filename at a given line in a review buffer by walking backwards
+        to the nearest `diff --git` header.
+
 ==============================================================================
 MAPPINGS                                                     *diffs-mappings*
 

lua/diffs/commands.lua

@@ -362,6 +362,160 @@ function M.gdiff_section(repo_root, opts)
   end)
 end
 
+---@class diffs.GreviewOpts
+---@field vertical? boolean
+---@field repo_root? string
+
+---@param base string
+---@param opts? diffs.GreviewOpts
+---@return integer?
+function M.greview(base, opts)
+  opts = opts or {}
+
+  if not base or base == '' then
+    vim.notify('[diffs.nvim]: greview requires a base ref', vim.log.levels.ERROR)
+    return nil
+  end
+
+  local repo_root = opts.repo_root
+  if not repo_root then
+    local bufnr = vim.api.nvim_get_current_buf()
+    local filepath = vim.api.nvim_buf_get_name(bufnr)
+    repo_root = git.get_repo_root(filepath ~= '' and filepath or nil)
+  end
+  if not repo_root then
+    local cwd = vim.fn.getcwd()
+    repo_root = git.get_repo_root(cwd .. '/.')
+  end
+  if not repo_root then
+    vim.notify('[diffs.nvim]: not in a git repository', vim.log.levels.ERROR)
+    return nil
+  end
+
+  local target_name = 'diffs://review:' .. base
+  local existing_buf = vim.fn.bufnr(target_name)
+  if existing_buf ~= -1 then
+    pcall(vim.api.nvim_buf_delete, existing_buf, { force = true })
+  end
+
+  local cmd = { 'git', '-C', repo_root, 'diff', '--no-ext-diff', '--no-color', base }
+  local result = vim.fn.systemlist(cmd)
+  if vim.v.shell_error ~= 0 then
+    vim.notify('[diffs.nvim]: git diff failed', vim.log.levels.ERROR)
+    return nil
+  end
+  result = replace_combined_diffs(result, repo_root)
+  if #result == 0 then
+    vim.notify('[diffs.nvim]: no diff against ' .. base, vim.log.levels.INFO)
+    return nil
+  end
+
+  local diff_buf = vim.api.nvim_create_buf(false, true)
+  vim.api.nvim_buf_set_lines(diff_buf, 0, -1, false, result)
+  vim.api.nvim_set_option_value('buftype', 'nowrite', { buf = diff_buf })
+  vim.api.nvim_set_option_value('bufhidden', 'delete', { buf = diff_buf })
+  vim.api.nvim_set_option_value('swapfile', false, { buf = diff_buf })
+  vim.api.nvim_set_option_value('modifiable', false, { buf = diff_buf })
+  vim.api.nvim_set_option_value('filetype', 'diff', { buf = diff_buf })
+  vim.api.nvim_buf_set_name(diff_buf, 'diffs://review:' .. base)
+  vim.api.nvim_buf_set_var(diff_buf, 'diffs_repo_root', repo_root)
+
+  local qf_items = {}
+  local loc_items = {}
+  local current_file = nil
+  local file_adds, file_dels = {}, {}
+  local file_hunk_count = {}
+
+  for i, line in ipairs(result) do
+    local file = line:match('^diff %-%-git a/.+ b/(.+)$')
+    if file then
+      current_file = file
+      file_adds[file] = 0
+      file_dels[file] = 0
+      file_hunk_count[file] = 0
+      table.insert(qf_items, {
+        bufnr = diff_buf,
+        lnum = i,
+        text = file,
+      })
+    elseif current_file and line:match('^@@') then
+      file_hunk_count[current_file] = file_hunk_count[current_file] + 1
+      local header = line:match('^(@@.-@@)')
+      table.insert(loc_items, {
+        bufnr = diff_buf,
+        lnum = i,
+        text = ('%s (hunk %d) %s'):format(
+          current_file,
+          file_hunk_count[current_file],
+          header or ''
+        ),
+      })
+    elseif current_file then
+      local ch = line:sub(1, 1)
+      if ch == '+' and not line:match('^%+%+%+') then
+        file_adds[current_file] = file_adds[current_file] + 1
+      elseif ch == '-' and not line:match('^%-%-%-') then
+        file_dels[current_file] = file_dels[current_file] + 1
+      end
+    end
+  end
+
+  for _, item in ipairs(qf_items) do
+    local file = item.text
+    local a = file_adds[file] or 0
+    local d = file_dels[file] or 0
+    local parts = { file }
+    if a > 0 then
+      parts[#parts + 1] = '+' .. a
+    end
+    if d > 0 then
+      parts[#parts + 1] = '-' .. d
+    end
+    item.text = table.concat(parts, ' ')
+  end
+
+  vim.fn.setqflist({}, ' ', {
+    title = 'review: ' .. base,
+    items = qf_items,
+  })
+  vim.fn.setloclist(0, {}, ' ', {
+    title = 'review hunks: ' .. base,
+    items = loc_items,
+  })
+
+  local existing_win = M.find_diffs_window()
+  if existing_win then
+    vim.api.nvim_set_current_win(existing_win)
+    vim.api.nvim_win_set_buf(existing_win, diff_buf)
+  else
+    vim.cmd(opts.vertical and 'vsplit' or 'split')
+    vim.api.nvim_win_set_buf(0, diff_buf)
+  end
+
+  M.setup_diff_buf(diff_buf)
+  dbg('opened review buffer %d against %s', diff_buf, base)
+
+  vim.schedule(function()
+    require('diffs').attach(diff_buf)
+  end)
+
+  return diff_buf
+end
+
+---@param buf integer
+---@param lnum integer
+---@return string?
+function M.review_file_at_line(buf, lnum)
+  local lines = vim.api.nvim_buf_get_lines(buf, 0, lnum, false)
+  for i = #lines, 1, -1 do
+    local file = lines[i]:match('^diff %-%-git a/.+ b/(.+)$')
+    if file then
+      return file
+    end
+  end
+  return nil
+end
+
 ---@param bufnr integer
 function M.read_buffer(bufnr)
   local name = vim.api.nvim_buf_get_name(bufnr)
@@ -392,6 +546,13 @@ function M.read_buffer(bufnr)
       diff_lines = {}
     end
 
+    diff_lines = replace_combined_diffs(diff_lines, repo_root)
+  elseif label == 'review' then
+    local cmd = { 'git', '-C', repo_root, 'diff', '--no-ext-diff', '--no-color', path }
+    diff_lines = vim.fn.systemlist(cmd)
+    if vim.v.shell_error ~= 0 then
+      diff_lines = {}
+    end
     diff_lines = replace_combined_diffs(diff_lines, repo_root)
   else
     local abs_path = repo_root .. '/' .. path
@@ -459,6 +620,32 @@ function M.setup()
     nargs = '?',
     desc = 'Show unified diff against git revision in horizontal split',
   })
+
+  vim.api.nvim_create_user_command('Greview', function(opts)
+    M.greview(opts.args ~= '' and opts.args or nil)
+  end, {
+    nargs = 1,
+    complete = function(arglead)
+      local refs = vim.fn.systemlist({
+        'git', 'for-each-ref', '--format=%(refname:short)',
+        'refs/heads/', 'refs/remotes/', 'refs/tags/',
+      })
+      if vim.v.shell_error ~= 0 then
+        return {}
+      end
+      if arglead == '' then
+        return refs
+      end
+      local matches = {}
+      for _, ref in ipairs(refs) do
+        if ref:find(arglead, 1, true) == 1 then
+          table.insert(matches, ref)
+        end
+      end
+      return matches
+    end,
+    desc = 'Show unified diff against a git ref with qflist/loclist',
+  })
 end
 
 return M

spec/commands_spec.lua

@@ -112,6 +112,79 @@ describe('commands', function()
     end)
   end)
 
+  describe('setup registers Greview command', function()
+    it('registers Greview command', function()
+      commands.setup()
+      local cmds = vim.api.nvim_get_commands({})
+      assert.is_not_nil(cmds.Greview)
+    end)
+  end)
+
+  describe('review_file_at_line', function()
+    local test_buffers = {}
+
+    after_each(function()
+      for _, bufnr in ipairs(test_buffers) do
+        if vim.api.nvim_buf_is_valid(bufnr) then
+          vim.api.nvim_buf_delete(bufnr, { force = true })
+        end
+      end
+      test_buffers = {}
+    end)
+
+    it('returns filename at cursor line', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      table.insert(test_buffers, bufnr)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, {
+        'diff --git a/foo.lua b/foo.lua',
+        '--- a/foo.lua',
+        '+++ b/foo.lua',
+        '@@ -1,3 +1,4 @@',
+        ' local M = {}',
+        '+local x = 1',
+        ' return M',
+      })
+
+      assert.are.equal('foo.lua', commands.review_file_at_line(bufnr, 6))
+    end)
+
+    it('returns correct file in multi-file diff', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      table.insert(test_buffers, bufnr)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, {
+        'diff --git a/foo.lua b/foo.lua',
+        '@@ -1 +1 @@',
+        '-old',
+        '+new',
+        'diff --git a/bar.lua b/bar.lua',
+        '@@ -1 +1 @@',
+        '-old',
+        '+new',
+      })
+
+      assert.are.equal('foo.lua', commands.review_file_at_line(bufnr, 3))
+      assert.are.equal('bar.lua', commands.review_file_at_line(bufnr, 7))
+    end)
+
+    it('returns nil before any diff header', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      table.insert(test_buffers, bufnr)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, {
+        'some preamble text',
+        'diff --git a/foo.lua b/foo.lua',
+      })
+
+      assert.is_nil(commands.review_file_at_line(bufnr, 1))
+    end)
+
+    it('returns nil on empty buffer', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      table.insert(test_buffers, bufnr)
+
+      assert.is_nil(commands.review_file_at_line(bufnr, 1))
+    end)
+  end)
+
   describe('find_hunk_line', function()
     it('finds matching @@ header and returns target line', function()
       local diff_lines = {

spec/read_buffer_spec.lua

@@ -286,6 +286,35 @@ describe('read_buffer', function()
 
       assert.is_truthy(vim.tbl_contains(captured_cmd, '--cached'))
     end)
+
+    it('runs git diff with base ref for review label', function()
+      local captured_cmd
+      mock_systemlist(function(cmd)
+        captured_cmd = cmd
+        return {
+          'diff --git a/file.lua b/file.lua',
+          '--- a/file.lua',
+          '+++ b/file.lua',
+          '@@ -1 +1 @@',
+          '-old',
+          '+new',
+        }
+      end)
+
+      local bufnr = create_diffs_buffer('diffs://review:origin/main', {
+        diffs_repo_root = '/home/test/repo',
+      })
+      commands.read_buffer(bufnr)
+
+      assert.is_not_nil(captured_cmd)
+      assert.are.equal('git', captured_cmd[1])
+      assert.are.equal('/home/test/repo', captured_cmd[3])
+      assert.are.equal('diff', captured_cmd[4])
+      assert.are.equal('origin/main', captured_cmd[#captured_cmd])
+
+      local lines = vim.api.nvim_buf_get_lines(bufnr, 0, -1, false)
+      assert.are.equal('diff --git a/file.lua b/file.lua', lines[1])
+    end)
   end)
 
   describe('content', function()