[nongnu] elpa/git-commit 46a4ac10ff: manual: Mention limitation of merge preview diff

[ELPA Syncer]

branch: elpa/git-commit
commit 46a4ac10ffc99b1242bd063506092ab0f8a7c107
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>

    manual: Mention limitation of merge preview diff
    
    Closes #4887.
---
 docs/magit.org     | 8 ++++++++
 docs/magit.texi    | 8 ++++++++
 lisp/magit-diff.el | 4 ++++
 3 files changed, 20 insertions(+)

diff --git a/docs/magit.org b/docs/magit.org
index caa3df5c93..98f8ae141f 100644
--- a/docs/magit.org
+++ b/docs/magit.org
@@ -3108,6 +3108,10 @@ change the diff arguments used in the current buffer, 
without changing
 which diff is shown.  This works in dedicated diff buffers, but also
 in the status buffer.
 
+(There is one exception; diff arguments cannot be changed in buffers
+created by ~magit-merge-preview~ because the underlying Git command does
+not support these arguments.)
+
 - Key: D (magit-diff-refresh) ::
 
   This transient prefix command binds the following suffix commands
@@ -5521,6 +5525,10 @@ following suffix commands.
   This command shows a preview of merging another branch or an
   arbitrary revision into the current branch.
 
+  Note that commands, that normally change how a diff is displayed, do
+  not work in buffers created by this command, because the underlying
+  Git command does not support diff arguments.
+
 When a merge is in progress, then the transient instead features the
 following suffix commands.
 
diff --git a/docs/magit.texi b/docs/magit.texi
index 9054a5adf3..5b52b531ae 100644
--- a/docs/magit.texi
+++ b/docs/magit.texi
@@ -3893,6 +3893,10 @@ change the diff arguments used in the current buffer, 
without changing
 which diff is shown.  This works in dedicated diff buffers, but also
 in the status buffer.
 
+(There is one exception; diff arguments cannot be changed in buffers
+created by @code{magit-merge-preview} because the underlying Git command does
+not support these arguments.)
+
 @table @asis
 @item @kbd{D} (@code{magit-diff-refresh})
 @kindex D
@@ -6796,6 +6800,10 @@ command you should probably use a command from the apply 
transient.
 @findex magit-merge-preview
 This command shows a preview of merging another branch or an
 arbitrary revision into the current branch.
+
+Note that commands, that normally change how a diff is displayed, do
+not work in buffers created by this command, because the underlying
+Git command does not support diff arguments.
 @end table
 
 When a merge is in progress, then the transient instead features the
diff --git a/lisp/magit-diff.el b/lisp/magit-diff.el
index 278c4d3e33..a2f2e6affe 100644
--- a/lisp/magit-diff.el
+++ b/lisp/magit-diff.el
@@ -961,6 +961,8 @@ and `:slant'."
     ("r" "switch range type"        magit-diff-switch-range-type)
     ("f" "flip revisions"           magit-diff-flip-revs)]]
   (interactive)
+  (when (derived-mode-p 'magit-merge-preview-mode)
+    (user-error "Cannot use %s in %s" this-command major-mode))
   (if (not (eq transient-current-command 'magit-diff-refresh))
       (transient-setup 'magit-diff-refresh)
     (pcase-let ((`(,args ,files) (magit-diff-arguments)))
@@ -1470,6 +1472,8 @@ instead."
   (magit-diff-set-context #'ignore))
 
 (defun magit-diff-set-context (fn)
+  (when (derived-mode-p 'magit-merge-preview-mode)
+    (user-error "Cannot use %s in %s" this-command major-mode))
   (let* ((def (--if-let (magit-get "diff.context") (string-to-number it) 3))
          (val magit-buffer-diff-args)
          (arg (--first (string-match "^-U\\([0-9]+\\)?$" it) val))