Add g? key help and describe every mapping

README.md

@@ -271,6 +271,12 @@ executable.
 
 ## Default Keys
 
+Press `g?` in any DiffBandit window to see its keys. The list comes from
+the window's live mappings, so it reflects your remaps, and it explains the
+compact diff header and the panel's staged symbols. Headers show a `g? help`
+hint; set `navigation.help_key = false` to turn both off. Every mapping also
+has a `DiffBandit: ...` description, so which-key and `:map` list them.
+
 Inside a diff view:
 
 | Key | Action |
@@ -289,6 +295,7 @@ Inside a diff view:
 | `<<` | Apply the right side to the left target |
 | `u` | Undo the last DiffBandit hunk action |
 | `q` | Close the diff session (`navigation.close_key`) |
+| `g?` | Show the keys of the current window (`navigation.help_key`) |
 
 At a file boundary, `]c` and `[c` first notify that the next press will move to
 the next or previous file. This keeps hunk navigation deliberate while still
@@ -451,6 +458,8 @@ require("diffbandit").setup({
       bottom = "]d",
     },
     snap_key = "]s",
+    close_key = "q",
+    help_key = "g?",
   },
   git = {
     default_mode = "all",

doc/diffbandit.txt

@@ -168,7 +168,19 @@ COMMANDS                                            *diffbandit-commands*
 ==============================================================================
 DEFAULT MAPPINGS                                  *diffbandit-mappings*
 
-Mappings are buffer-local inside DiffBandit buffers.
+Mappings are buffer-local inside DiffBandit buffers. Every DiffBandit view
+answers |diffbandit-g?| with the keys of the window you are in, and each
+mapping carries a "DiffBandit: ..." description, so `:map`, which-key, and
+keymap pickers explain them too.
+
+                                                       *diffbandit-g?*
+  g?            Show the keys of the current window in a floating window,
+                grouped by purpose, with a legend for the diff header and the
+                panel's staged symbols. The list is read from the live
+                mappings, so remapped and disabled keys are shown as they are.
+                q, <Esc>, or g? closes it. Headers show a "g? help" hint.
+                Set by `navigation.help_key`; false disables the key and the
+                hints.
 
 Diff view mappings:
 
@@ -209,10 +221,10 @@ Diff view mappings:
                                                         *diffbandit-u*
   u             Undo the last DiffBandit hunk action for the current file.
 
-                                                        *diffbandit-q*
                                                       *diffbandit-gzp*
   gzp           Show or hide the commit panel for a Git diff.
 
+                                                        *diffbandit-q*
   q             Close the diff session. Set by `navigation.close_key`;
                 false disables it.
 
@@ -432,6 +444,7 @@ Common configuration:
       },
       snap_key = "]s",
       close_key = "q",
+      help_key = "g?",
     },
     git = {
       default_mode = "all",

doc/tags

@@ -35,6 +35,7 @@ diffbandit-commands	diffbandit.txt	/*diffbandit-commands*
 diffbandit-commit-panel	diffbandit.txt	/*diffbandit-commit-panel*
 diffbandit-configuration	diffbandit.txt	/*diffbandit-configuration*
 diffbandit-folder-diff	diffbandit.txt	/*diffbandit-folder-diff*
+diffbandit-g?	diffbandit.txt	/*diffbandit-g?*
 diffbandit-git	diffbandit.txt	/*diffbandit-git*
 diffbandit-gzp	diffbandit.txt	/*diffbandit-gzp*
 diffbandit-hunk-actions	diffbandit.txt	/*diffbandit-hunk-actions*

lua/diffbandit/config.lua

@@ -121,6 +121,7 @@ local defaults = {
     },
     snap_key = "]s",
     close_key = "q",
+    help_key = "g?",
     prompt_message = "Reached final change in this diff. Open next file with changes?",
     on_request_next_file = nil,
   },

lua/diffbandit/folder/init.lua

@@ -6,6 +6,7 @@ local ui = require("diffbandit.util.ui")
 local layout = require("diffbandit.util.layout")
 local winbar = require("diffbandit.util.winbar")
 local config_mod = require("diffbandit.config")
+local keyhelp = require("diffbandit.util.keyhelp")
 
 local Folder = {}
 Folder.__index = Folder
@@ -540,7 +541,9 @@ function Folder:render()
   local columns = folder_config(self).columns or {}
   local left_lines = { header_text("left", self.left_root, self.left_entries, left_width) }
   local gutter_lines = { center_text(compact_filter_label(self.filter), self.gutter_width) }
-  local right_lines = { header_text("right", self.right_root, self.right_entries, right_width) }
+  local help_hint = keyhelp.hint(config_mod.section(self.config, "navigation").help_key)
+  local hint_width = help_hint and (vim.fn.strdisplaywidth(help_hint) + 2) or 0
+  local right_lines = { header_text("right", self.right_root, self.right_entries, math.max(10, right_width - hint_width)) }
   local left_meta = {}
   local right_meta = {}
 
@@ -581,6 +584,7 @@ function Folder:render()
     vim.api.nvim_buf_clear_namespace(buf, self.ns, 0, -1)
     vim.api.nvim_buf_add_highlight(buf, self.ns, "DiffBanditStatus", 0, 0, -1)
   end
+  keyhelp.place_hint(self.right_buf, self.ns, 0, help_hint, "DiffBanditStatusMuted")
 
   for index, row in ipairs(self.visible_rows or {}) do
     local line = index
@@ -1035,55 +1039,60 @@ end
 function Folder:setup_keymaps()
   local opts = { nowait = true, noremap = true, silent = true }
   local keys = folder_config(self).keys or {}
-  local function map(buf, lhs, rhs)
+  local help_key = config_mod.section(self.config, "navigation").help_key
+  -- section/desc label the mapping for the help window (util/keyhelp).
+  local function map(buf, lhs, rhs, section, desc)
     if lhs and lhs ~= "" then
-      vim.keymap.set("n", lhs, rhs, vim.tbl_extend("force", opts, { buffer = buf }))
+      vim.keymap.set("n", lhs, rhs, keyhelp.opts(buf, section, desc, vim.tbl_extend("force", opts, { buffer = buf })))
     end
   end
   local function maps(buf)
+    map(buf, help_key, function()
+      keyhelp.open(buf, { title = "Folder diff", order = { "General", "Folder" }, help_key = help_key })
+    end, "General", "Show this key help")
+    map(buf, keys.close or "q", function()
+      self:close()
+    end, "General", "Close this view")
     map(buf, keys.open or "<CR>", function()
       self:open_selected()
-    end)
+    end, "Folder", "Open the file pair, or expand the directory")
     map(buf, keys.alternate_open or "o", function()
       self:open_selected()
-    end)
+    end, "Folder", "Open the file pair, or expand the directory")
     map(buf, keys.toggle_expand or "<Space>", function()
       self:toggle_expand()
-    end)
+    end, "Folder", "Expand or collapse the directory")
     map(buf, keys.alternate_toggle_expand or "za", function()
       self:toggle_expand()
-    end)
+    end, "Folder", "Expand or collapse the directory")
     map(buf, keys.expand_all or "zR", function()
       self:expand_all()
-    end)
+    end, "Folder", "Expand all directories")
     map(buf, keys.collapse_all or "zM", function()
       self:collapse_all()
-    end)
+    end, "Folder", "Collapse all directories")
     map(buf, keys.next_diff or "]c", function()
       self:goto_diff(1)
-    end)
+    end, "Navigation", "Next difference")
     map(buf, keys.prev_diff or "[c", function()
       self:goto_diff(-1)
-    end)
-    map(buf, keys.refresh or "R", function()
-      self:refresh()
-    end)
+    end, "Navigation", "Previous difference")
     map(buf, keys.filter or "s", function()
       self:select_filter()
-    end)
-    map(buf, keys.close or "q", function()
-      self:close()
-    end)
+    end, "Folder", "Choose which entries to show")
+    map(buf, keys.refresh or "R", function()
+      self:refresh()
+    end, "Folder", "Compare again")
     map(buf, "<C-w>l", function()
       if self.right_win and vim.api.nvim_win_is_valid(self.right_win) then
         vim.api.nvim_set_current_win(self.right_win)
       end
-    end)
+    end, "Navigation", "Go to the right side")
     map(buf, "<C-w>h", function()
       if self.left_win and vim.api.nvim_win_is_valid(self.left_win) then
         vim.api.nvim_set_current_win(self.left_win)
       end
-    end)
+    end, "Navigation", "Go to the left side")
   end
   maps(self.left_buf)
   maps(self.right_buf)

lua/diffbandit/init.lua

@@ -268,20 +268,17 @@ local function review_panel_details(queue)
       target = review.target,
       author = commit.author,
       date = commit.date,
-      help = "<CR> focus diff  ]f/[f files  ]c/[c hunks  q close",
     }
   elseif review.kind == "compare" then
     return {
       title = "Compare " .. tostring(review.requested_base or review.base) .. " with " .. tostring(review.target),
       subtitle = review.direct and "Direct branch comparison" or "Merge-base branch comparison",
       base = review.base,
       target = review.target,
-      help = "<CR> focus diff  ]f/[f files  ]c/[c hunks  q close",
     }
   end
   return {
     title = "Git review",
-    help = "<CR> focus diff  ]f/[f files  ]c/[c hunks  q close",
   }
 end
 

lua/diffbandit/merge/init.lua

@@ -3,6 +3,7 @@ local git = require("diffbandit.git")
 local merge_model = require("diffbandit.merge.model")
 local nvim = require("diffbandit.util.nvim")
 local keymaps = require("diffbandit.util.keymaps")
+local keyhelp = require("diffbandit.util.keyhelp")
 local layout = require("diffbandit.util.layout")
 local winbar = require("diffbandit.util.winbar")
 local document = require("diffbandit.util.document")
@@ -844,21 +845,30 @@ end
 function Merge:setup_keymaps()
   local keys = config_mod.section(self.config, "merge", "keys")
   local document_keys = config_mod.section(self.config, "navigation", "document_keys")
-  local function map(buf, lhs, rhs)
-    self:set_buffer_keymap("n", buf, lhs, rhs, { nowait = true, noremap = true, silent = true })
+  local help_key = config_mod.section(self.config, "navigation").help_key
+  -- section/desc label the mapping for the help window (util/keyhelp).
+  local function map(buf, lhs, rhs, section, desc)
+    self:set_buffer_keymap("n", buf, lhs, rhs,
+      keyhelp.opts(buf, section, desc, { nowait = true, noremap = true, silent = true }))
   end
   for _, buf in ipairs({ self.local_buf, self.result_buf, self.remote_buf }) do
-    map(buf, keys.next_conflict, function() self:goto_next_hunk() end)
-    map(buf, keys.prev_conflict, function() self:goto_prev_hunk() end)
-    map(buf, keys.accept_local, function() self:accept("local") end)
-    map(buf, keys.accept_remote, function() self:accept("remote") end)
-    map(buf, keys.accept_both, function() self:accept("both") end)
-    map(buf, keys.apply_non_conflicting, function() self:apply_non_conflicting() end)
-    map(buf, keys.focus_panel, function() self:focus_commit_panel_for_current_file() end)
-    map(buf, document_keys.top, function() self:goto_document_edge("top") end)
-    map(buf, document_keys.bottom, function() self:goto_document_edge("bottom") end)
-    map(buf, keys.snap, function() self:snap_to_cursor() end)
-    map(buf, keys.close, function() self:close() end)
+    map(buf, help_key, function() self:show_key_help() end, "General", "Show this key help")
+    map(buf, keys.close, function() self:close() end, "General", "Close this view")
+    map(buf, keys.next_conflict, function() self:goto_next_hunk() end, "Merge", "Next conflict")
+    map(buf, keys.prev_conflict, function() self:goto_prev_hunk() end, "Merge", "Previous conflict")
+    map(buf, keys.accept_local, function() self:accept("local") end, "Merge", "Accept local (ours) into the result")
+    map(buf, keys.accept_remote, function() self:accept("remote") end, "Merge", "Accept remote (theirs) into the result")
+    map(buf, keys.accept_both, function() self:accept("both") end, "Merge", "Accept both, local then remote")
+    map(buf, keys.apply_non_conflicting, function() self:apply_non_conflicting() end,
+      "Merge", "Apply every non-conflicting change")
+    map(buf, keys.focus_panel, function() self:focus_commit_panel_for_current_file() end,
+      "Panel", "Open or focus the commit panel")
+    map(buf, document_keys.top, function() self:goto_document_edge("top") end,
+      "Navigation", "Align the panes to the top")
+    map(buf, document_keys.bottom, function() self:goto_document_edge("bottom") end,
+      "Navigation", "Align the panes to the bottom")
+    map(buf, keys.snap, function() self:snap_to_cursor() end,
+      "Navigation", "Line up the other panes with the cursor line")
   end
   -- Visibility toggles also work from the panel buffers, so the panel can be
   -- hidden while focused in it and panes re-shown from anywhere.
@@ -869,15 +879,34 @@ function Merge:setup_keymaps()
   end
   for _, buf in ipairs(toggle_bufs) do
     if buf and vim.api.nvim_buf_is_valid(buf) then
-      map(buf, keys.toggle_panel, function() self:toggle_panel_visibility() end)
-      map(buf, keys.toggle_local, function() self:toggle_pane("local") end)
-      map(buf, keys.toggle_remote, function() self:toggle_pane("remote") end)
-      map(buf, keys.show_all, function() self:show_all() end)
+      map(buf, keys.toggle_panel, function() self:toggle_panel_visibility() end,
+        "Layout", "Show or hide the commit panel")
+      map(buf, keys.toggle_local, function() self:toggle_pane("local") end,
+        "Layout", "Show or hide the local (left) pane")
+      map(buf, keys.toggle_remote, function() self:toggle_pane("remote") end,
+        "Layout", "Show or hide the remote (right) pane")
+      map(buf, keys.show_all, function() self:show_all() end,
+        "Layout", "Show every hidden pane and the panel")
     end
   end
   keymaps.reassert_later(self, { self.local_buf, self.result_buf, self.remote_buf })
 end
 
+function Merge:show_key_help()
+  keyhelp.open(vim.api.nvim_get_current_buf(), {
+    title = "Merge",
+    notes = {
+      {
+        title = "Result",
+        rows = {
+          { keys = ":w", desc = "Write the result and mark the file resolved" },
+        },
+      },
+    },
+    help_key = config_mod.section(self.config, "navigation").help_key,
+  })
+end
+
 function Merge:status_text()
   local conflict_text
   if #self.conflicts == 0 then
@@ -952,7 +981,13 @@ function Merge:render_headers()
     )
   end
   if remote_width then
-    ui.set_header_line(self.remote_header_buf, self.header_ns, lines.remote, remote_width)
+    ui.set_header_line_with_right(
+      self.remote_header_buf,
+      self.header_ns,
+      lines.remote,
+      keyhelp.hint(config_mod.section(self.config, "navigation").help_key),
+      remote_width
+    )
   end
 end