From 97a6fb2bd7637b8fca0707539fd449a1046d9565 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Sat, 7 Feb 2026 14:12:49 -0500
Subject: [PATCH] feat: add <Plug> mappings

Problem: users who want keybindings must wrap commands in closures.
There is no stable public API for key binding.

Solution: define <Plug> mappings in the plugin file and document them
in a new MAPPINGS section in the vimdoc.
---
 doc/diffs.nvim.txt | 16 ++++++++++++++++
 plugin/diffs.lua   |  8 ++++++++
 2 files changed, 24 insertions(+)

diff --git a/doc/diffs.nvim.txt b/doc/diffs.nvim.txt
index e4e750b..aa51301 100644
--- a/doc/diffs.nvim.txt
+++ b/doc/diffs.nvim.txt
@@ -227,6 +227,22 @@ COMMANDS                                                      *diffs-commands*
 :Ghdiff [revision]                                                  *:Ghdiff*
     Like |:Gdiff| but explicitly opens in a horizontal split.
 
+==============================================================================
+MAPPINGS                                                     *diffs-mappings*
+
+                                                        *<Plug>(diffs-gdiff)*
+<Plug>(diffs-gdiff)     Show unified diff against HEAD in a horizontal
+                        split. Equivalent to |:Gdiff| with no arguments.
+
+                                                       *<Plug>(diffs-gvdiff)*
+<Plug>(diffs-gvdiff)    Show unified diff against HEAD in a vertical
+                        split. Equivalent to |:Gvdiff| with no arguments.
+
+Example configuration: >lua
+    vim.keymap.set('n', '<leader>gd', '<Plug>(diffs-gdiff)')
+    vim.keymap.set('n', '<leader>gD', '<Plug>(diffs-gvdiff)')
+<
+
 ==============================================================================
 FUGITIVE STATUS KEYMAPS                                   *diffs-fugitive*
 
diff --git a/plugin/diffs.lua b/plugin/diffs.lua
index c51d417..031ed60 100644
--- a/plugin/diffs.lua
+++ b/plugin/diffs.lua
@@ -40,3 +40,11 @@ vim.api.nvim_create_autocmd('OptionSet', {
     end
   end,
 })
+
+local cmds = require('diffs.commands')
+vim.keymap.set('n', '<Plug>(diffs-gdiff)', function()
+  cmds.gdiff(nil, false)
+end, { desc = 'Unified diff (horizontal)' })
+vim.keymap.set('n', '<Plug>(diffs-gvdiff)', function()
+  cmds.gdiff(nil, true)
+end, { desc = 'Unified diff (vertical)' })