branch: elpa/magit
commit 0daafe08149b406ca0bf200a1ed0a8e4b1c1054a
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
Clarify that commands run magit-section-movement-hook explicitly
Closes #5394.
---
docs/magit.org | 20 +++++++++++++++-----
docs/magit.texi | 20 +++++++++++++++-----
lisp/magit-log.el | 6 ++++--
lisp/magit-section.el | 5 ++++-
lisp/magit-stash.el | 3 ++-
lisp/magit-status.el | 9 ++++++---
6 files changed, 46 insertions(+), 17 deletions(-)
diff --git a/docs/magit.org b/docs/magit.org
index bcf81777db..f5fe1756f1 100644
--- a/docs/magit.org
+++ b/docs/magit.org
@@ -891,6 +891,12 @@ To move within a section use the usual keys (~C-p~, ~C-n~,
~C-b~, ~C-f~ etc),
whose global bindings are not shadowed. To move to another section use
the following commands.
+The section movement commands described here run the hook
+~magit-section-movement-hook~. Note that they explicitly run that hook
+and that aribrary other movement, defined in Emacs and other packages,
+do not run that hook. That hook, and hook functions that can be added
+to it, or are part of its default value, are described below.
+
- Key: p (magit-section-backward) ::
When not at the beginning of a section, then move to the beginning
@@ -931,8 +937,10 @@ remove function that haven't even been added yet, for
example:
- Variable: magit-section-movement-hook ::
- This hook is run by all of the above movement commands, after
- arriving at the destination.
+ This hook is run by all of the above section movement commands,
+ after arriving at the destination. It is *not* run by arbitrary other
+ movement commands (such as ~next-line~), which are provided by Emacs
+ or third-party packages.
- Function: magit-hunk-set-window-start ::
@@ -999,9 +1007,11 @@ remove function that haven't even been added yet, for
example:
Delay before automatically updating the other window.
- When moving around in certain buffers, then certain other buffers,
- which are being displayed in another window, may optionally be
- updated to display information about the section at point.
+ When moving around in certain buffers using Magit's own section
+ movement commands (but not other movement commands), then certain
+ other buffers, which are being displayed in another window, may
+ optionally be updated to display information about the section at
+ point.
When holding down a key to move by more than just one section, then
that would update that buffer for each section on the way. To
diff --git a/docs/magit.texi b/docs/magit.texi
index 112bb136be..22ee57f5e5 100644
--- a/docs/magit.texi
+++ b/docs/magit.texi
@@ -1080,6 +1080,12 @@ To move within a section use the usual keys (@code{C-p},
@code{C-n}, @code{C-b},
whose global bindings are not shadowed. To move to another section use
the following commands.
+The section movement commands described here run the hook
+@code{magit-section-movement-hook}. Note that they explicitly run that hook
+and that aribrary other movement, defined in Emacs and other packages,
+do not run that hook. That hook, and hook functions that can be added
+to it, or are part of its default value, are described below.
+
@table @asis
@item @kbd{p} (@code{magit-section-backward})
@kindex p
@@ -1126,8 +1132,10 @@ remove function that haven't even been added yet, for
example:
@end lisp
@defvar magit-section-movement-hook
-This hook is run by all of the above movement commands, after
-arriving at the destination.
+This hook is run by all of the above section movement commands,
+after arriving at the destination. It is @strong{not} run by arbitrary other
+movement commands (such as @code{next-line}), which are provided by Emacs
+or third-party packages.
@end defvar
@defun magit-hunk-set-window-start
@@ -1194,9 +1202,11 @@ in another window of the same frame.
@defopt magit-update-other-window-delay
Delay before automatically updating the other window.
-When moving around in certain buffers, then certain other buffers,
-which are being displayed in another window, may optionally be
-updated to display information about the section at point.
+When moving around in certain buffers using Magit's own section
+movement commands (but not other movement commands), then certain
+other buffers, which are being displayed in another window, may
+optionally be updated to display information about the section at
+point.
When holding down a key to move by more than just one section, then
that would update that buffer for each section on the way. To
diff --git a/lisp/magit-log.el b/lisp/magit-log.el
index 3c4ac21d9a..28266d6254 100644
--- a/lisp/magit-log.el
+++ b/lisp/magit-log.el
@@ -1530,7 +1530,8 @@ exists mostly for backward compatibility reasons."
(defun magit-log-maybe-update-revision-buffer (&optional _)
"When moving in a log or cherry buffer, update the revision buffer.
-If there is no revision buffer in the same frame, then do nothing."
+If there is no revision buffer in the same frame, then do nothing.
+See also info node `(magit)Section Movement'."
(when (derived-mode-p 'magit-log-mode 'magit-cherry-mode 'magit-reflog-mode)
(magit--maybe-update-revision-buffer)))
@@ -1558,7 +1559,8 @@ If there is no revision buffer in the same frame, then do
nothing."
(defun magit-log-maybe-update-blob-buffer (&optional _)
"When moving in a log or cherry buffer, update the blob buffer.
-If there is no blob buffer in the same frame, then do nothing."
+If there is no blob buffer in the same frame, then do nothing.
+See also info node `(magit)Section Movement'."
(when (derived-mode-p 'magit-log-mode 'magit-cherry-mode 'magit-reflog-mode)
(magit--maybe-update-blob-buffer)))
diff --git a/lisp/magit-section.el b/lisp/magit-section.el
index 5eac6753a9..e162982a13 100644
--- a/lisp/magit-section.el
+++ b/lisp/magit-section.el
@@ -106,7 +106,8 @@ similar defect.")
(defvar magit-section-movement-hook nil
"Hook run by `magit-section-goto'.
-That function in turn is used by all section movement commands.")
+That function in turn is used by all section movement commands.
+See also info node `(magit)Section Movement'.")
(defvar magit-section-set-visibility-hook
(list #'magit-section-cached-visibility)
@@ -874,6 +875,8 @@ If there is no previous sibling section, then move to the
parent."
(run-hook-with-args 'magit-section-movement-hook (magit-current-section)))
(defun magit-section-goto (arg)
+ "Run `magit-section-movement-hook'.
+See info node `(magit)Section Movement'."
(if (integerp arg)
(progn (forward-line arg)
(setq arg (magit-current-section)))
diff --git a/lisp/magit-stash.el b/lisp/magit-stash.el
index 4ceea526c3..1ca279db7a 100644
--- a/lisp/magit-stash.el
+++ b/lisp/magit-stash.el
@@ -569,7 +569,8 @@ instead of \"Stashes:\"."
(defun magit-stashes-maybe-update-stash-buffer (&optional _)
"When moving in the stashes buffer, update the stash buffer.
-If there is no stash buffer in the same frame, then do nothing."
+If there is no stash buffer in the same frame, then do nothing.
+See also info node `(magit)Section Movement'."
(when (derived-mode-p 'magit-stashes-mode)
(magit--maybe-update-stash-buffer)))
diff --git a/lisp/magit-status.el b/lisp/magit-status.el
index 970d727416..68c7ce050a 100644
--- a/lisp/magit-status.el
+++ b/lisp/magit-status.el
@@ -500,19 +500,22 @@ Type \\[magit-commit] to create a commit.
(defun magit-status-maybe-update-revision-buffer (&optional _)
"When moving in the status buffer, update the revision buffer.
-If there is no revision buffer in the same frame, then do nothing."
+If there is no revision buffer in the same frame, then do nothing.
+See also info node `(magit)Section Movement'."
(when (derived-mode-p 'magit-status-mode)
(magit--maybe-update-revision-buffer)))
(defun magit-status-maybe-update-stash-buffer (&optional _)
"When moving in the status buffer, update the stash buffer.
-If there is no stash buffer in the same frame, then do nothing."
+If there is no stash buffer in the same frame, then do nothing.
+See also info node `(magit)Section Movement'."
(when (derived-mode-p 'magit-status-mode)
(magit--maybe-update-stash-buffer)))
(defun magit-status-maybe-update-blob-buffer (&optional _)
"When moving in the status buffer, update the blob buffer.
-If there is no blob buffer in the same frame, then do nothing."
+If there is no blob buffer in the same frame, then do nothing.
+See also info node `(magit)Section Movement'."
(when (derived-mode-p 'magit-status-mode)
(magit--maybe-update-blob-buffer)))
