branch: elpa/magit
commit bee964c56a83fd58add073c34343c6c2307df06f
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
magit-diff-dwim: Improve documentation
I wrote this a while ago in response to a user complaining that this
command never does what they mean (dwtm), and have finally decided to
install it after all, because, despite the slight saltiness towards
the end, this actually is useful information.
---
docs/magit.org | 18 ++++++++++++++++++
docs/magit.texi | 18 ++++++++++++++++++
lisp/magit-diff.el | 20 +++++++++++++++++++-
3 files changed, 55 insertions(+), 1 deletion(-)
diff --git a/docs/magit.org b/docs/magit.org
index 4d32dd7c61c..d5c327ab440 100644
--- a/docs/magit.org
+++ b/docs/magit.org
@@ -3105,6 +3105,24 @@ Also see [[man:git-diff]]
Show changes for the thing at point.
+ For example, if point is on a commit, show the changes introduced by
+ that commit. Likewise if point is on the section titled "Unstaged
+ changes", then show those changes in a separate buffer. Generally
+ speaking, compare the thing at point with the most logical, trivial
+ and (in *any* situation) at least potentially useful other thing it
+ could be compared to.
+
+ When the region selects commits, then compare the two commits at
+ either end. There are different ways two commits can be compared.
+ In the buffer showing the diff, you can control how the comparison,
+ is done, using "D r" and "D f".
+
+ This function does not always show the changes that you might want
+ to view in any given situation. You can think of the changes being
+ shown as the smallest common denominator. There is no AI involved.
+ If this command never does what you want, then ignore it, and instead
+ use the commands that allow you to explicitly specify what you need.
+
- Key: d r (magit-diff-range) ::
Show differences between two commits.
diff --git a/docs/magit.texi b/docs/magit.texi
index 240e26218bd..d5b9e14614e 100644
--- a/docs/magit.texi
+++ b/docs/magit.texi
@@ -3871,6 +3871,24 @@ temporary buffer until a suffix is invoked.
@findex magit-diff-dwim
Show changes for the thing at point.
+For example, if point is on a commit, show the changes introduced by
+that commit. Likewise if point is on the section titled "Unstaged
+changes", then show those changes in a separate buffer. Generally
+speaking, compare the thing at point with the most logical, trivial
+and (in @strong{any} situation) at least potentially useful other thing it
+could be compared to.
+
+When the region selects commits, then compare the two commits at
+either end. There are different ways two commits can be compared.
+In the buffer showing the diff, you can control how the comparison,
+is done, using "D r" and "D f".
+
+This function does not always show the changes that you might want
+to view in any given situation. You can think of the changes being
+shown as the smallest common denominator. There is no AI involved.
+If this command never does what you want, then ignore it, and instead
+use the commands that allow you to explicitly specify what you need.
+
@item @kbd{d r} (@code{magit-diff-range})
@kindex d r
@findex magit-diff-range
diff --git a/lisp/magit-diff.el b/lisp/magit-diff.el
index a5903254e74..598b6171292 100644
--- a/lisp/magit-diff.el
+++ b/lisp/magit-diff.el
@@ -1078,7 +1078,25 @@ and `:slant'."
;;;###autoload
(defun magit-diff-dwim (&optional args files)
- "Show changes for the thing at point."
+ "Show changes for the thing at point.
+
+For example, if point is on a commit, show the changes introduced by
+that commit. Likewise if point is on the section titled \"Unstaged
+changes\", then show those changes in a separate buffer. Generally
+speaking, compare the thing at point with the most logical, trivial
+and (in *any* situation) at least potentially useful other thing it
+could be compared to.
+
+When the region selects commits, then compare the two commits at
+either end. There are different ways two commits can be compared.
+In the buffer showing the diff, you can control how the comparison,
+is done, using \"D r\" and \"D f\".
+
+This function does not always show the changes that you might want
+to view in any given situation. You can think of the changes being
+shown as the smallest common denominator. There is no AI involved.
+If this command never does what you want, then ignore it, and instead
+use the commands that allow you to explicitly specify what you need."
(interactive (magit-diff-arguments))
(let ((default-directory default-directory)
(section (magit-current-section)))
