feat(difftool): replace old "nvim -d" automatically #38057

Problem:
"nvim -d" doesn't leverage nvim.difftool.

Solution:
If nvim.difftool was enabled via :packadd, automatically
handle "nvim -d" on startup.

    nvim -c "packadd nvim.difftool" -d dir1/ dir2/

runtime/doc/plugins.txt

@@ -48,14 +48,14 @@ Builtin plugin: difftool                                            *difftool*
 :DiffTool {left} {right}                                           *:DiffTool*
 Compares two directories or files side-by-side.
 Supports directory diffing, rename detection, and highlights changes
-in quickfix list.
+in quickfix list. Replaces the built-in `nvim -d` diff mode with this interface.
 
 The plugin is not loaded by default; use `:packadd nvim.difftool` before
 invoking `:DiffTool`.
 
-Example `git difftool -d` integration using `DiffTool` command: >ini
+Example `git difftool -d` integration using `nvim -d` replacement: >ini
     [difftool "nvim_difftool"]
-      cmd = nvim -c \"packadd nvim.difftool\" -c \"DiffTool $LOCAL $REMOTE\"
+      cmd = nvim -c \"packadd nvim.difftool\" -d \"$LOCAL\" \"$REMOTE\"
     [diff]
       tool = nvim_difftool
 <

runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua

@@ -3,16 +3,16 @@
 ---:DiffTool {left} {right}                                           *:DiffTool*
 ---Compares two directories or files side-by-side.
 ---Supports directory diffing, rename detection, and highlights changes
----in quickfix list.
+---in quickfix list. Replaces the built-in `nvim -d` diff mode with this interface.
 ---</pre>
 ---
 --- The plugin is not loaded by default; use `:packadd nvim.difftool` before invoking `:DiffTool`.
 ---
---- Example `git difftool -d` integration using `DiffTool` command:
+--- Example `git difftool -d` integration using `nvim -d` replacement:
 ---
 --- ```ini
 --- [difftool "nvim_difftool"]
----   cmd = nvim -c \"packadd nvim.difftool\" -c \"DiffTool $LOCAL $REMOTE\"
+---   cmd = nvim -c \"packadd nvim.difftool\" -d \"$LOCAL\" \"$REMOTE\"
 --- [diff]
 ---   tool = nvim_difftool
 --- ```

runtime/pack/dist/opt/nvim.difftool/plugin/difftool.lua

@@ -10,3 +10,23 @@ vim.api.nvim_create_user_command('DiffTool', function(opts)
     vim.notify('Usage: DiffTool <left> <right>', vim.log.levels.ERROR)
   end
 end, { nargs = '*', complete = 'file' })
+
+-- If we are in diff mode (e.g. `nvim -d file1 file2`), open the difftool automatically.
+local function start_diff()
+  if not vim.o.diff then
+    return
+  end
+  local args = vim.v.argf
+  if #args == 2 then
+    vim.schedule(function()
+      require('difftool').open(args[1], args[2])
+    end)
+  end
+end
+if vim.v.vim_did_enter > 0 then
+  start_diff()
+  return
+end
+vim.api.nvim_create_autocmd('VimEnter', {
+  callback = start_diff,
+})

test/functional/plugin/difftool_spec.lua

@@ -115,4 +115,35 @@ describe('nvim.difftool', function()
     local autocmds = fn.nvim_get_autocmds({ group = 'nvim.difftool.events' })
     assert(#autocmds > 0, 'autocmds should still exist after closing quickfix window')
   end)
+
+  it('opens difftool automatically when started with nvim -d', function()
+    -- Start Neovim with -d flag for directory diff
+    clear({
+      args = {
+        '--cmd',
+        'packadd nvim.difftool',
+        '-d',
+        testdir_left,
+        testdir_right,
+      },
+    })
+
+    -- Wait for difftool to open
+    n.poke_eventloop()
+
+    -- Verify we have 3 windows (left, right, and quickfix)
+    eq(3, #fn.getwininfo())
+
+    -- Verify quickfix list has the expected entries
+    local qflist = fn.getqflist()
+    local entries = {}
+    for _, item in ipairs(qflist) do
+      table.insert(entries, { text = item.text, rel = item.user_data and item.user_data.rel })
+    end
+    eq({
+      { text = 'M', rel = 'file1.txt' },
+      { text = 'D', rel = 'file2.txt' },
+      { text = 'A', rel = 'file3.txt' },
+    }, entries)
+  end)
 end)