From 45b4bbac281b518e86906f39f1b4119ae0905012 Mon Sep 17 00:00:00 2001
From: Tomas Slusny <slusnucky@gmail.com>
Date: Sat, 28 Feb 2026 17:03:44 +0100
Subject: [PATCH] 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                       |  6 ++--
 .../dist/opt/nvim.difftool/lua/difftool.lua   |  6 ++--
 .../opt/nvim.difftool/plugin/difftool.lua     | 20 ++++++++++++
 test/functional/plugin/difftool_spec.lua      | 31 +++++++++++++++++++
 4 files changed, 57 insertions(+), 6 deletions(-)

diff --git a/runtime/doc/plugins.txt b/runtime/doc/plugins.txt
index 3b34a7ec16..e6c34984b6 100644
--- a/runtime/doc/plugins.txt
+++ b/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
 <
diff --git a/runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua b/runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua
index 2e4562a6c5..539b7ee750 100644
--- a/runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua
+++ b/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
 --- ```
diff --git a/runtime/pack/dist/opt/nvim.difftool/plugin/difftool.lua b/runtime/pack/dist/opt/nvim.difftool/plugin/difftool.lua
index cae828995a..3d4c29d009 100644
--- a/runtime/pack/dist/opt/nvim.difftool/plugin/difftool.lua
+++ b/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,
+})
diff --git a/test/functional/plugin/difftool_spec.lua b/test/functional/plugin/difftool_spec.lua
index 060a0414f2..567376bda3 100644
--- a/test/functional/plugin/difftool_spec.lua
+++ b/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)