feat(review): add ++untracked= to omit the review untracked section (#414)

Author: barrettruth

README.md

@@ -77,6 +77,11 @@ See the documentation for more information.
 Yes. Configure Git to open `$MERGED` with Neovim; diffs.nvim will detect
 conflict markers automatically. See `:help diffs.nvim-git-mergetool`.
 
+**Q: Can I exclude untracked files from `:Diff review`?**
+
+Yes. Run `:Diff review ++nountracked`. To make it the default, wrap it in your
+own command, e.g. `:command! Review Diff review ++nountracked`.
+
 ## Known Limitations
 
 - **Incomplete syntax context**: Treesitter parses each diff hunk in isolation.

doc/diffs.nvim.txt

@@ -540,7 +540,7 @@ Paired-window behavior: ~                          *diffs.nvim-paired-windows*
     the current row maps to worktree content.
 
 
-:Diff review [++layout=unified|stacked|split] [review-spec]     *:Diff-review*
+:Diff review [++layout=...] [++nountracked] [review-spec]       *:Diff-review*
     Open a repository review. `review` must be the first argument; a revision
     literally named `review` must be addressed another way (for example
     `refs/heads/review`).
@@ -555,6 +555,14 @@ Paired-window behavior: ~                          *diffs.nvim-paired-windows*
     using merge-base semantics. With `A..B`, reviews explicit target `B`
     against base `A` as a direct two-endpoint comparison.
 
+    A current-state review (no explicit target) ends with an Untracked
+    section listing files not yet tracked by git. Pass `++nountracked` to
+    omit it. To omit it every time, wrap the command, for example: >vim
+        command! Review Diff review ++nountracked
+<
+    Explicit-target reviews (`A...B`, `A..B`) never include untracked files,
+    so the option has no effect there.
+
     `++layout=unified` and `++layout=stacked` both create full generated review
     maps. Unified review maps use old and new line-number rails; stacked review
     maps use one context-aware line-number rail as described at
@@ -604,6 +612,8 @@ Paired-window behavior: ~                          *diffs.nvim-paired-windows*
                        context-aware line-number rail.
         ++layout=split (optional) Open the first renderable changed review file
                        as a paired side-by-side endpoint diff.
+        ++nountracked  (optional) Omit the Untracked section of a
+                       current-state review (shown by default).
         {review-spec}  (string, optional) One of:
                        - empty: review current repo state against the repo
                          default branch
@@ -613,12 +623,13 @@ Paired-window behavior: ~                          *diffs.nvim-paired-windows*
                        - `{base}..{target}`: direct review of explicit target
                          `{target}` against base `{base}`
 
-    Completion covers `++layout=...` and git refs.
+    Completion covers `++layout=...`, `++nountracked`, and git refs.
 
     Examples: >vim
         :Diff review
         :Diff review ++layout=stacked origin/main
         :Diff review ++layout=split
+        :Diff review ++nountracked
         :Diff review origin/main
         :vertical Diff review origin/main
         :Diff review origin/main...refs/forge/pr/42
@@ -645,6 +656,8 @@ Paired-window behavior: ~                          *diffs.nvim-paired-windows*
                   Use this from async/plugin contexts when the current buffer
                   is not a reliable repo hint.
         {vertical} (boolean, optional) Open the review in a vertical split.
+        {untracked} (boolean, optional) Include the Untracked section of a
+                  current-state review. Defaults to true.
 
     Utilities: ~
         `require('diffs.commands').review_split()` opens the currently

lua/diffs/commands.lua

@@ -643,6 +643,10 @@ local layout_options = {
   '++layout=split',
 }
 
+local untracked_options = {
+  '++nountracked',
+}
+
 ---@param layout? "unified"|"stacked"|"split"
 ---@return diffs.RailStyle
 local function rail_style_for_layout(layout)
@@ -739,28 +743,32 @@ end
 
 ---@param args string[]
 ---@param from? integer # first argument index to scan (defaults to 1)
----@return { has_layout: boolean, has_value: boolean }
+---@return { has_layout: boolean, has_untracked: boolean, has_value: boolean }
 local function args_context(args, from)
   local has_layout = false
+  local has_untracked = false
   local has_value = false
   for i = from or 1, #args do
     local token = args[i]
     if token:match('^%+%+layout=') then
       has_layout = true
+    elseif token == '++nountracked' then
+      has_untracked = true
     elseif not token:match('^%+%+') then
       has_value = true
     end
   end
   return {
     has_layout = has_layout,
+    has_untracked = has_untracked,
     has_value = has_value,
   }
 end
 
 ---@param arglead string
 ---@param cmdline? string
 ---@param cursorpos? integer
----@return { has_layout: boolean, has_value: boolean }
+---@return { has_layout: boolean, has_untracked: boolean, has_value: boolean }
 local function completion_context(arglead, cmdline, cursorpos)
   return args_context(command_arg_tokens(arglead, cmdline, cursorpos))
 end
@@ -789,7 +797,7 @@ local function complete_diff_args(arglead, cmdline, cursorpos)
 end
 
 ---@param arglead string
----@param context { has_layout: boolean, has_value: boolean }
+---@param context { has_layout: boolean, has_untracked: boolean, has_value: boolean }
 ---@return string[]
 local function complete_review_args(arglead, context)
   if context.has_value then
@@ -800,13 +808,19 @@ local function complete_review_args(arglead, context)
     if not context.has_layout then
       vim.list_extend(matches, prefix_matches(layout_options, arglead))
     end
+    if not context.has_untracked then
+      vim.list_extend(matches, prefix_matches(untracked_options, arglead))
+    end
     vim.list_extend(matches, review.complete(arglead))
     return matches
   end
   local matches = {}
   if arglead == '' and not context.has_layout then
     vim.list_extend(matches, layout_options)
   end
+  if arglead == '' and not context.has_untracked then
+    vim.list_extend(matches, untracked_options)
+  end
   vim.list_extend(matches, review.complete(arglead))
   return matches
 end
@@ -1106,6 +1120,7 @@ local function stored_review_spec(normalized)
     base = normalized.base,
     target = normalized.target,
     mode = normalized.mode,
+    untracked = normalized.untracked,
   }
 end
 

lua/diffs/review.lua

@@ -17,6 +17,7 @@ local notify = log.notify
 ---@field repo? string
 ---@field mode? string
 ---@field vertical? boolean
+---@field untracked? boolean
 
 ---@class diffs.ReviewCommandParseResult
 ---@field spec diffs.ReviewSpec
@@ -28,6 +29,7 @@ local notify = log.notify
 ---@field repo_root string
 ---@field mode string?
 ---@field vertical boolean
+---@field untracked boolean
 ---@field display string
 ---@field exec_args string[]
 
@@ -179,17 +181,28 @@ function M.parse_command_args(args)
   local tokens = split_args(args)
   local layout = 'unified'
   local has_layout = false
-
-  while tokens[1] and tokens[1]:match('^%+%+layout=') do
-    if has_layout then
-      return nil, 'repeated ++layout option'
-    end
-    local value = tokens[1]:match('^%+%+layout=(.+)$')
-    if value ~= 'unified' and value ~= 'stacked' and value ~= 'split' then
-      return nil, 'unsupported layout ' .. tostring(value)
+  local untracked = nil
+  local has_untracked = false
+
+  while tokens[1] and (tokens[1]:match('^%+%+layout=') or tokens[1] == '++nountracked') do
+    local token = tokens[1]
+    if token:match('^%+%+layout=') then
+      if has_layout then
+        return nil, 'repeated ++layout option'
+      end
+      local value = token:match('^%+%+layout=(.+)$')
+      if value ~= 'unified' and value ~= 'stacked' and value ~= 'split' then
+        return nil, 'unsupported layout ' .. tostring(value)
+      end
+      has_layout = true
+      layout = value
+    else
+      if has_untracked then
+        return nil, 'repeated ++nountracked option'
+      end
+      has_untracked = true
+      untracked = false
     end
-    has_layout = true
-    layout = value
     table.remove(tokens, 1)
   end
 
@@ -201,6 +214,9 @@ function M.parse_command_args(args)
   if not spec then
     return nil, err
   end
+  if has_untracked then
+    spec.untracked = untracked
+  end
 
   return {
     spec = spec,
@@ -231,6 +247,9 @@ function M.normalize(spec, repo_root_override)
   if spec.vertical ~= nil and type(spec.vertical) ~= 'boolean' then
     error('diffs: review.vertical must be a boolean')
   end
+  if spec.untracked ~= nil and type(spec.untracked) ~= 'boolean' then
+    error('diffs: review.untracked must be a boolean')
+  end
 
   local repo_root = repo_root_override or resolve_repo_root(spec.repo)
   if not repo_root then
@@ -278,12 +297,18 @@ function M.normalize(spec, repo_root_override)
     return nil, ref_err
   end
 
+  local untracked = true
+  if spec.untracked ~= nil then
+    untracked = spec.untracked
+  end
+
   return {
     base = base,
     target = target,
     repo_root = repo_root,
     mode = mode,
     vertical = spec.vertical or false,
+    untracked = untracked,
     display = display,
     exec_args = exec_args,
   },
@@ -575,36 +600,38 @@ local function run_current_state(review, deps)
     lines = unstaged_rendered,
   }, unstaged_specs, state)
 
-  local untracked, untracked_err = untracked_paths(review)
-  if not untracked then
-    return nil,
-      untracked_err ~= '' and untracked_err or 'git ls-files failed for review Untracked section',
-      nil
-  end
-  local untracked_lines = {}
-  local untracked_specs = {}
-  for _, path in ipairs(untracked) do
-    if is_untracked_binary(review.repo_root, path) then
-      dbg('skipping binary untracked %s', path)
-    else
-      local spec = diffspec.index_to_worktree(path)
-      local rendered, render_err = render.file(spec, review.repo_root)
-      if rendered then
-        for _, line in ipairs(rendered) do
-          untracked_lines[#untracked_lines + 1] = line
+  if review.untracked then
+    local untracked, untracked_err = untracked_paths(review)
+    if not untracked then
+      return nil,
+        untracked_err ~= '' and untracked_err or 'git ls-files failed for review Untracked section',
+        nil
+    end
+    local untracked_lines = {}
+    local untracked_specs = {}
+    for _, path in ipairs(untracked) do
+      if is_untracked_binary(review.repo_root, path) then
+        dbg('skipping binary untracked %s', path)
+      else
+        local spec = diffspec.index_to_worktree(path)
+        local rendered, render_err = render.file(spec, review.repo_root)
+        if rendered then
+          for _, line in ipairs(rendered) do
+            untracked_lines[#untracked_lines + 1] = line
+          end
+          untracked_specs[path] = spec
+        elseif render_err then
+          dbg('skipping untracked %s: %s', path, render_err)
         end
-        untracked_specs[path] = spec
-      elseif render_err then
-        dbg('skipping untracked %s: %s', path, render_err)
       end
     end
+    append_section(lines, {
+      id = 'untracked',
+      label = 'Untracked',
+      description = 'empty -> worktree',
+      lines = untracked_lines,
+    }, untracked_specs, state)
   end
-  append_section(lines, {
-    id = 'untracked',
-    label = 'Untracked',
-    description = 'empty -> worktree',
-    lines = untracked_lines,
-  }, untracked_specs, state)
 
   return lines,
     nil,
@@ -779,12 +806,14 @@ function M.open(spec, deps)
       base = review.base,
       target = review.target,
       mode = review.mode,
+      untracked = review.untracked,
     }),
     rail_style = deps.rail_style,
     vars = {
       diffs_review_base = review.base,
       diffs_review_target = review.target,
       diffs_review_mode = review.mode,
+      diffs_review_untracked = review.untracked,
     },
   })
 
@@ -847,13 +876,15 @@ function M.reload(bufnr, repo_root, path, deps)
   local stored_base = get_buf_var(bufnr, 'diffs_review_base')
   local stored_target = get_buf_var(bufnr, 'diffs_review_target')
   local stored_mode = get_buf_var(bufnr, 'diffs_review_mode')
+  local stored_untracked = get_buf_var(bufnr, 'diffs_review_untracked')
 
   local review_spec
   if stored_base then
     review_spec = {
       base = stored_base,
       target = stored_target,
       mode = stored_mode,
+      untracked = stored_untracked,
     }
   else
     local parse_err