From 69ca0147d8197a104de1216408cc850c15ece96e Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Sun, 8 Mar 2026 19:03:39 -0400
Subject: [PATCH] docs: update default keymaps to `g`-prefixed keys (#101)

Problem: Default buffer-local keys `!`, `D`, `F`, `U` shadow common Vim
builtins (`!` filter, `D` delete-to-eol, `F` reverse-find, `U` line-undo).

Solution: Document new defaults `g!`, `gd`, `gf`, `gz` in the mappings
table, config example, and command references. Add a deprecated-keys
section listing the old-to-new mapping with removal timeline.
---
 doc/pending.txt | 35 ++++++++++++++++++++++++++---------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/doc/pending.txt b/doc/pending.txt
index 11c3973..380a9e9 100644
--- a/doc/pending.txt
+++ b/doc/pending.txt
@@ -238,7 +238,7 @@ COMMANDS                                                    *pending-commands*
                                                                *:Pending-undo*
 :Pending undo
     Undo the last `:w` save, restoring the task store to its previous state.
-    Equivalent to the `U` buffer-local key (see |pending-mappings|). Up to 20
+    Equivalent to the `gz` buffer-local key (see |pending-mappings|). Up to 20
     levels of undo are persisted across sessions.
 
                                                               *:Pending-init*
@@ -267,11 +267,11 @@ Default buffer-local keys: ~
     -------     ------------------------------------------------
     `q`           Close the task buffer (`close`)
     `<CR>`        Toggle complete / uncomplete (`toggle`)
-    `!`           Toggle the priority flag (`priority`)
-    `D`           Prompt for a due date (`date`)
-    `F`           Prompt for filter predicates (`filter`)
+    `g!`          Toggle the priority flag (`priority`)
+    `gd`          Prompt for a due date (`date`)
+    `gf`          Prompt for filter predicates (`filter`)
     `<Tab>`       Switch between category / queue view (`view`)
-    `U`           Undo the last `:w` save (`undo`)
+    `gz`          Undo the last `:w` save (`undo`)
     `o`           Insert a new task line below (`open_line`)
     `O`           Insert a new task line above (`open_line_above`)
     `zc`          Fold the current category section (requires `folding`)
@@ -307,6 +307,23 @@ All motions support count: `3]]` jumps three headers forward. `]]` and
 
 `dd`, `p`, `P`, and `:w` work as standard Vim operations.
 
+Deprecated keys: ~                                  *pending-deprecated-keys*
+The following keys were renamed to avoid shadowing Vim builtins. The old
+keys still work but emit a deprecation warning and will be removed in a
+future release:
+
+    Old         New         Action ~
+    -------     -------     ------------------------------------------------
+    `!`           `g!`        Toggle the priority flag
+    `D`           `gd`        Prompt for a due date
+    `F`           `gf`        Prompt for filter predicates
+    `U`           `gz`        Undo the last `:w` save
+
+To silence warnings, set the new keys explicitly in your config or set the
+old keys to `false`: >lua
+    vim.g.pending = { keymaps = { priority = 'g!' } }
+<
+
                                                         *<Plug>(pending-open)*
 <Plug>(pending-open)
     Open the task buffer. Maps to |:Pending| with no arguments.
@@ -601,10 +618,10 @@ loads: >lua
         close = 'q',
         toggle = '<CR>',
         view = '<Tab>',
-        priority = '!',
-        date = 'D',
-        undo = 'U',
-        filter = 'F',
+        priority = 'g!',
+        date = 'gd',
+        undo = 'gz',
+        filter = 'gf',
         open_line = 'o',
         open_line_above = 'O',
         a_task = 'at',