magit.org: document refresh commands

2 files changed, 237 insertions, 83 deletions

diff --git a/Documentation/magit.org b/Documentation/magit.org
index 4c399e1..28c8d64 100644
--- a/Documentation/magit.org
+++ b/Documentation/magit.org
@@ -1353,7 +1353,21 @@ buffers.
 
 ** Logging
 
-Also see [[info:gitman#git-log]].
+The status buffer contains logs for the unpushed and unpulled commits,
+but that obviously isn't enough.  The prefix command ~magit-log-popup~,
+on ~l~, features several suffix commands, which show a specific log in a
+separate log buffer.
+
+Like other popups, the log popup also features several arguments that
+can be changed before invoking one of the suffix commands.  However in
+case of the log popup these arguments correspond to those currently in
+use in the current repository's log buffer.  When the log popup is
+invoked while no log buffer exists for the current repository yet,
+then the default value of ~magit-log-arguments~ is used instead.
+
+For information about the various arguments, see [[info:gitman#git-log]].
+
+The log popup also features several reflog commands.  See [[*Reflog]].
 
 - Key: l, magit-log-popup
 
@@ -1399,6 +1413,41 @@ The following related commands are not available from the popup.
 
   Show log for the file visited in the current buffer.
 
+*** Refreshing logs
+
+The prefix command ~magit-log-refresh-popup~, on ~L~, can be used to
+change the log arguments used in the current buffer, without changing
+which log is shown.  This works in dedicated log buffers, but also in
+the status buffer.
+
+- Key: L, magit-log-refresh-buffer
+
+  This prefix command shows the following suffix commands along with
+  the appropriate infix arguments in a popup buffer.
+
+- Key: L g, magit-log-refresh
+
+  This suffix command sets the local log arguments for the current
+  buffer.
+
+- Key: L s, magit-log-set-default-arguments
+
+  This suffix command sets the default log arguments for buffers of
+  the same type as that of the current buffer.  Other existing buffers
+  of the same type are not affected because their local values have
+  already been initialized.
+
+- Key: L w, magit-log-save-default-arguments
+
+  This suffix command sets the default log arguments for buffers of
+  the same type as that of the current buffer, and saves the value for
+  future sessions.  Other existing buffers of the same type are not
+  affected because their local values have already been initialized.
+
+- Key: L t, magit-toggle-margin
+
+  Show or hide the margin.
+
 *** Log Buffer
 
 - Key: C-c C-b, magit-go-backward
@@ -1468,9 +1517,11 @@ The following related commands are not available from the popup.
   displayed.  In status buffers this option is ignored, but it is
   possible to show the margin using the mentioned command.
 
-- Key: L, magit-toggle-margin
+- Key: L, magit-log-refresh-popup
 
-  Show or hide the Magit margin.
+  This prefix command shows the following suffix commands along with
+  the appropriate infix arguments in a popup buffer.  See [[*Refreshing
+  logs]].
 
 - User Option: magit-log-cutoff-length
 
@@ -1523,6 +1574,18 @@ These reflog commands are available from the log popup.  See [[*Logging]].
 
 ** Diffing
 
+The status buffer contains diffs for the staged and unstaged commits,
+but that obviously isn't enough.  The prefix command ~magit-diff-popup~,
+on ~d~, features several suffix commands, which show a specific diff in
+a separate diff buffer.
+
+Like other popups, the diff popup also features several arguments that
+can be changed before invoking one of the suffix commands.  However in
+case of the diff popup these arguments correspond to those currently
+in use in the current repository's diff buffer.  When the diff popup
+is invoked while no diff buffer exists for the current repository yet,
+then the default value of ~magit-diff-arguments~ is used instead.
+
 Also see [[info:gitman#git-diff]].
 
 - Key: d, magit-diff-popup
@@ -1568,6 +1631,18 @@ Also see [[info:gitman#git-diff]].
 
   Show changes between any two files on disk.
 
+- Key: M-x magit-diff-unpushed, magit-diff-unpushed
+
+  Show unpushed changes.
+
+- Key: M-x magit-diff-unpulled, magit-diff-unpulled
+
+  Show unpulled changes.
+
+All of the above suffix commands update the repository's diff buffer.
+The diff popup also features two commands which show differences in
+another buffer:
+
 - Key: d c, magit-show-commit
 
   Show the commit at point.  If there is no commit at point or with a
@@ -1577,25 +1652,12 @@ Also see [[info:gitman#git-diff]].
 
   Show all diffs of a stash in a buffer.
 
-- Key: M-x magit-diff-unpushed, magit-diff-unpushed
-
-  Show unpushed changes.
-
-- Key: M-x magit-diff-unpulled, magit-diff-unpulled
-
-  Show unpulled changes.
-
 *** Refreshing diffs
 
-The ~magit-diff-popup~ described in the previous section is used to
-display a log in the current repositories diff buffer.  The following
-popup is used to change the arguments used to generate the diff or
-diffs in the current buffer, the status buffer or the diff buffer.
-
-In the diff buffer you can of course just use ~magit-diff-popup~, but
-~magit-diff-refresh-popup~ is more convenient because you don't have to
-again specify which differences to show.  In the status buffer this
-popup is the only way to change certain arguments.
+The prefix command ~magit-diff-refresh-popup~, on ~D~, can be used to
+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.
 
 - Key: D, magit-diff-refresh-popup
 
@@ -1604,28 +1666,36 @@ popup is the only way to change certain arguments.
 
 - Key: D g, magit-diff-refresh
 
-  Set the local diff arguments for the current buffer.
+  This suffix command sets the local diff arguments for the current
+  buffer.
 
 - Key: D s, magit-diff-set-default-arguments
 
-  Set the global diff arguments for the current buffer.
+  This suffix command sets the default diff arguments for buffers of
+  the same type as that of the current buffer.  Other existing buffers
+  of the same type are not affected because their local values have
+  already been initialized.
 
 - Key: D w, magit-diff-save-default-arguments
 
-  Set and save the global diff arguments for the current buffer.
+  This suffix command sets the default diff arguments for buffers of
+  the same type as that of the current buffer, and saves the value for
+  future sessions.  Other existing buffers of the same type are not
+  affected because their local values have already been initialized.
 
 - Key: D t, magit-diff-toggle-refine-hunk
 
-  Toggle hunk refinement on or off.
+  This command toggles hunk refinement on or off.
 
 - Key: D r, magit-diff-switch-range-type
 
-  Convert diff range type from "revA..revB" to "revB...revA", or vice
-  versa.
+  This command converts the diff range type from "revA..revB" to
+  "revB...revA", or vice versa.
 
 - Key: D f, magit-diff-flip-revs
 
-  Swap revisions in diff range from "revA..revB" to "revB..revA".
+  This command swaps revisions in the diff range from "revA..revB"
+  to "revB..revA", or vice versa.
 
 In addition to the above popup, which allows changing any of the
 supported arguments, there also exist some commands which change a
@@ -1633,37 +1703,36 @@ particular argument.
 
 - Key: -, magit-diff-less-context
 
-  Decrease the context for diff hunks by COUNT lines.
+  This command decreases the context for diff hunks by COUNT lines.
 
 - Key: +, magit-diff-more-context
 
-  Increase the context for diff hunks by COUNT lines.
+  This command increase the context for diff hunks by COUNT lines.
 
 - Key: 0, magit-diff-default-context
 
-  Reset context for diff hunks to the default height.
+  This command reset context for diff hunks to the default height.
 
-While all of the above commands change *how* some change is being
-displayed without changing *what* change is being displayed, the
-following commands do the opposite: they change what is being
-displayed but not how.
+The following commands quicky change what diff is being displayed
+without having to using one of the diff popups.
 
 - Key: C-c C-d, magit-diff-while-committing
 
-  While committing, show the changes that are about to be committed.
-  While amending, invoking the command again toggles between showing
-  just the new changes or all the changes that will be committed.
+  While committing, this command shows the changes that are about to
+  be committed.  While amending, invoking the command again toggles
+  between showing just the new changes or all the changes that will be
+  committed.
 
   This binding is available in the diff buffer as well as the commit
   message buffer.
 
 - Key: C-c C-b, magit-go-backward
 
-  Move backward in current buffer's history.
+  This command moves backward in current buffer's history.
 
 - Key: C-c C-f, magit-go-forward
 
-  Move forward in current buffer's history.
+  This command Moves forward in current buffer's history.
 
 *** Diff buffer
 
diff --git a/Documentation/magit.texi b/Documentation/magit.texi
index a814c85..1de249e 100644
--- a/Documentation/magit.texi
+++ b/Documentation/magit.texi
@@ -127,6 +127,7 @@ Status buffer
 
 Logging
 
+* Refreshing logs::
 * Log Buffer::
 * Select from log::
 * Reflog::
@@ -1837,7 +1838,19 @@ buffers.
 @node Logging
 @section Logging
 
-Also see 
+The status buffer contains logs for the unpushed and unpulled commits,
+but that obviously isn't enough.  The prefix command @code{magit-log-popup},
+on @code{l}, features several suffix commands, which show a specific log in a
+separate log buffer.
+
+Like other popups, the log popup also features several arguments that
+can be changed before invoking one of the suffix commands.  However in
+case of the log popup these arguments correspond to those currently in
+use in the current repository's log buffer.  When the log popup is
+invoked while no log buffer exists for the current repository yet,
+then the default value of @code{magit-log-arguments} is used instead.
+
+For information about the various arguments, see 
 @ifinfo
 @ref{git-log,,,gitman,}
 @end ifinfo
@@ -1851,6 +1864,8 @@ the git-log(1) manpage
 @end iftex
 .
 
+The log popup also features several reflog commands.  See @ref{Reflog,Reflog}.
+
 @table @asis
 @kindex l
 @cindex magit-log-popup
@@ -1918,11 +1933,60 @@ Show log for the file visited in the current buffer.
 @end table
 
 @menu
+* Refreshing logs::
 * Log Buffer::
 * Select from log::
 * Reflog::
 @end menu
 
+@node Refreshing logs
+@subsection Refreshing logs
+
+The prefix command @code{magit-log-refresh-popup}, on @code{L}, can be used to
+change the log arguments used in the current buffer, without changing
+which log is shown.  This works in dedicated log buffers, but also in
+the status buffer.
+
+@table @asis
+@kindex L
+@cindex magit-log-refresh-buffer
+@item @kbd{L} @tie{}@tie{}@tie{}@tie{}(@code{magit-log-refresh-buffer})
+
+This prefix command shows the following suffix commands along with
+the appropriate infix arguments in a popup buffer.
+
+@kindex L g
+@cindex magit-log-refresh
+@item @kbd{L g} @tie{}@tie{}@tie{}@tie{}(@code{magit-log-refresh})
+
+This suffix command sets the local log arguments for the current
+buffer.
+
+@kindex L s
+@cindex magit-log-set-default-arguments
+@item @kbd{L s} @tie{}@tie{}@tie{}@tie{}(@code{magit-log-set-default-arguments})
+
+This suffix command sets the default log arguments for buffers of
+the same type as that of the current buffer.  Other existing buffers
+of the same type are not affected because their local values have
+already been initialized.
+
+@kindex L w
+@cindex magit-log-save-default-arguments
+@item @kbd{L w} @tie{}@tie{}@tie{}@tie{}(@code{magit-log-save-default-arguments})
+
+This suffix command sets the default log arguments for buffers of
+the same type as that of the current buffer, and saves the value for
+future sessions.  Other existing buffers of the same type are not
+affected because their local values have already been initialized.
+
+@kindex L t
+@cindex magit-toggle-margin
+@item @kbd{L t} @tie{}@tie{}@tie{}@tie{}(@code{magit-toggle-margin})
+
+Show or hide the margin.
+@end table
+
 @node Log Buffer
 @subsection Log Buffer
 
@@ -2015,10 +2079,11 @@ possible to show the margin using the mentioned command.
 
 @table @asis
 @kindex L
-@cindex magit-toggle-margin
-@item @kbd{L} @tie{}@tie{}@tie{}@tie{}(@code{magit-toggle-margin})
+@cindex magit-log-refresh-popup
+@item @kbd{L} @tie{}@tie{}@tie{}@tie{}(@code{magit-log-refresh-popup})
 
-Show or hide the Magit margin.
+This prefix command shows the following suffix commands along with
+the appropriate infix arguments in a popup buffer.  See @ref{Refreshing logs,Refreshing logs}.
 
 @end table
 
@@ -2104,6 +2169,18 @@ Display the @code{HEAD} reflog.
 @node Diffing
 @section Diffing
 
+The status buffer contains diffs for the staged and unstaged commits,
+but that obviously isn't enough.  The prefix command @code{magit-diff-popup},
+on @code{d}, features several suffix commands, which show a specific diff in
+a separate diff buffer.
+
+Like other popups, the diff popup also features several arguments that
+can be changed before invoking one of the suffix commands.  However in
+case of the diff popup these arguments correspond to those currently
+in use in the current repository's diff buffer.  When the diff popup
+is invoked while no diff buffer exists for the current repository yet,
+then the default value of @code{magit-diff-arguments} is used instead.
+
 Also see 
 @ifinfo
 @ref{git-diff,,,gitman,}
@@ -2176,6 +2253,24 @@ Show changes between the working tree and the index.
 
 Show changes between any two files on disk.
 
+@kindex M-x magit-diff-unpushed
+@cindex magit-diff-unpushed
+@item @kbd{M-x magit-diff-unpushed} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-unpushed})
+
+Show unpushed changes.
+
+@kindex M-x magit-diff-unpulled
+@cindex magit-diff-unpulled
+@item @kbd{M-x magit-diff-unpulled} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-unpulled})
+
+Show unpulled changes.
+@end table
+
+All of the above suffix commands update the repository's diff buffer.
+The diff popup also features two commands which show differences in
+another buffer:
+
+@table @asis
 @kindex d c
 @cindex magit-show-commit
 @item @kbd{d c} @tie{}@tie{}@tie{}@tie{}(@code{magit-show-commit})
@@ -2188,18 +2283,6 @@ prefix argument, prompt for a commit.
 @item @kbd{d t} @tie{}@tie{}@tie{}@tie{}(@code{magit-stash-show})
 
 Show all diffs of a stash in a buffer.
-
-@kindex M-x magit-diff-unpushed
-@cindex magit-diff-unpushed
-@item @kbd{M-x magit-diff-unpushed} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-unpushed})
-
-Show unpushed changes.
-
-@kindex M-x magit-diff-unpulled
-@cindex magit-diff-unpulled
-@item @kbd{M-x magit-diff-unpulled} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-unpulled})
-
-Show unpulled changes.
 @end table
 
 @menu
@@ -2212,15 +2295,10 @@ Show unpulled changes.
 @node Refreshing diffs
 @subsection Refreshing diffs
 
-The @code{magit-diff-popup} described in the previous section is used to
-display a log in the current repositories diff buffer.  The following
-popup is used to change the arguments used to generate the diff or
-diffs in the current buffer, the status buffer or the diff buffer.
-
-In the diff buffer you can of course just use @code{magit-diff-popup}, but
-@code{magit-diff-refresh-popup} is more convenient because you don't have to
-again specify which differences to show.  In the status buffer this
-popup is the only way to change certain arguments.
+The prefix command @code{magit-diff-refresh-popup}, on @code{D}, can be used to
+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.
 
 @table @asis
 @kindex D
@@ -2234,38 +2312,46 @@ the appropriate infix arguments in a popup buffer.
 @cindex magit-diff-refresh
 @item @kbd{D g} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-refresh})
 
-Set the local diff arguments for the current buffer.
+This suffix command sets the local diff arguments for the current
+buffer.
 
 @kindex D s
 @cindex magit-diff-set-default-arguments
 @item @kbd{D s} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-set-default-arguments})
 
-Set the global diff arguments for the current buffer.
+This suffix command sets the default diff arguments for buffers of
+the same type as that of the current buffer.  Other existing buffers
+of the same type are not affected because their local values have
+already been initialized.
 
 @kindex D w
 @cindex magit-diff-save-default-arguments
 @item @kbd{D w} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-save-default-arguments})
 
-Set and save the global diff arguments for the current buffer.
+This suffix command sets the default diff arguments for buffers of
+the same type as that of the current buffer, and saves the value for
+future sessions.  Other existing buffers of the same type are not
+affected because their local values have already been initialized.
 
 @kindex D t
 @cindex magit-diff-toggle-refine-hunk
 @item @kbd{D t} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-toggle-refine-hunk})
 
-Toggle hunk refinement on or off.
+This command toggles hunk refinement on or off.
 
 @kindex D r
 @cindex magit-diff-switch-range-type
 @item @kbd{D r} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-switch-range-type})
 
-Convert diff range type from "revA..revB" to "revB@dots{}revA", or vice
-versa.
+This command converts the diff range type from "revA..revB" to
+"revB@dots{}revA", or vice versa.
 
 @kindex D f
 @cindex magit-diff-flip-revs
 @item @kbd{D f} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-flip-revs})
 
-Swap revisions in diff range from "revA..revB" to "revB..revA".
+This command swaps revisions in the diff range from "revA..revB"
+to "revB..revA", or vice versa.
 @end table
 
 In addition to the above popup, which allows changing any of the
@@ -2277,34 +2363,33 @@ particular argument.
 @cindex magit-diff-less-context
 @item @kbd{-} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-less-context})
 
-Decrease the context for diff hunks by COUNT lines.
+This command decreases the context for diff hunks by COUNT lines.
 
 @kindex +
 @cindex magit-diff-more-context
 @item @kbd{+} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-more-context})
 
-Increase the context for diff hunks by COUNT lines.
+This command increase the context for diff hunks by COUNT lines.
 
 @kindex 0
 @cindex magit-diff-default-context
 @item @kbd{0} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-default-context})
 
-Reset context for diff hunks to the default height.
+This command reset context for diff hunks to the default height.
 @end table
 
-While all of the above commands change @strong{how} some change is being
-displayed without changing @strong{what} change is being displayed, the
-following commands do the opposite: they change what is being
-displayed but not how.
+The following commands quicky change what diff is being displayed
+without having to using one of the diff popups.
 
 @table @asis
 @kindex C-c C-d
 @cindex magit-diff-while-committing
 @item @kbd{C-c C-d} @tie{}@tie{}@tie{}@tie{}(@code{magit-diff-while-committing})
 
-While committing, show the changes that are about to be committed.
-While amending, invoking the command again toggles between showing
-just the new changes or all the changes that will be committed.
+While committing, this command shows the changes that are about to
+be committed.  While amending, invoking the command again toggles
+between showing just the new changes or all the changes that will be
+committed.
 
 This binding is available in the diff buffer as well as the commit
 message buffer.
@@ -2313,13 +2398,13 @@ message buffer.
 @cindex magit-go-backward
 @item @kbd{C-c C-b} @tie{}@tie{}@tie{}@tie{}(@code{magit-go-backward})
 
-Move backward in current buffer's history.
+This command moves backward in current buffer's history.
 
 @kindex C-c C-f
 @cindex magit-go-forward
 @item @kbd{C-c C-f} @tie{}@tie{}@tie{}@tie{}(@code{magit-go-forward})
 
-Move forward in current buffer's history.
+This command Moves forward in current buffer's history.
 @end table
 
 @node Diff buffer