Improve documentation about commit commands

2 files changed, 295 insertions, 75 deletions

diff --git a/docs/magit.org b/docs/magit.org
index acdfc66..4db6a11 100644
--- a/docs/magit.org
+++ b/docs/magit.org
@@ -4626,82 +4626,192 @@ Also see [[man:git-commit]]
 
 **** Editing the last commit
 
+These commands modify the last (a.k.a., "HEAD") commit.  The commit is
+modified (a.k.a., replaced) immediately.  Similar commands exist for
+modifying other (non-HEAD) commits.  Those commands are described in
+the following two sections.  For each command in this section, we
+mention the respective non-HEAD commands, to make the relation
+explicit.
+
+The command descriptions below mention the specific arguments they use
+when calling ~git commit~.  The arguments specified in the menu are
+appended to those arguments.
+
 - Key: c e (magit-commit-extend) ::
 
-  Amend the last commit, without editing the message.  With a prefix
-  argument keep the committer date, otherwise change it.  The option
-  ~magit-commit-extend-override-date~ can be used to inverse the meaning
-  of the prefix argument.
+  This command amends the staged changes to the last commit, without
+  editing its commit message.
+
+  This command calls ~git commit --amend --no-edit~.
 
-  Non-interactively respect the optional OVERRIDE-DATE argument and
-  ignore the option.
+  With a prefix argument the committer date is not updated; without an
+  argument it is updated.
+
+  The option ~magit-commit-extend-override-date~ can be used to inverse
+  the meaning of the prefix argument.  Non-interactively, the optional
+  OVERRIDE-DATE argument controls this behavior, and the option is of
+  no relevance.
 
 - Key: c a (magit-commit-amend) ::
 
-  Amend the last commit.
+  This command amends the staged changes to the last commit, and pops
+  up a buffer to let the user edit its commit message.
+
+  This command calls ~git commit --amend --edit~.
 
 - Key: c w (magit-commit-reword) ::
 
-  Reword the last commit, ignoring staged changes.  With a prefix
-  argument keep the committer date, otherwise change it.  The option
-  ~magit-commit-reword-override-date~ can be used to inverse the meaning
-  of the prefix argument.
+  This command pops up a buffer to let the user edit the message of
+  the latest commit.  The commit tree remains unchanged and staged
+  changes remain staged.
 
-  Non-interactively respect the optional OVERRIDE-DATE argument and
-  ignore the option.
+  This command calls ~git commit --amend --only --edit~.
+
+  With a prefix argument the committer date is not updated; without an
+  argument it is updated.
+
+  The option ~magit-commit-reword-override-date~ can be used to inverse
+  the meaning of the prefix argument.  Non-interactively, the optional
+  OVERRIDE-DATE argument controls this behavior, and the option is of
+  no relevance.
 
 **** Editing any reachable commit
 
+These commands create a new commit, which targets an existing commit,
+from the staged changes and/or using a new commit message.  Any commit
+that is reachable from HEAD, including HEAD itself, can be the target.
+
+The new commit is intended to be eventually squashed into the targeted
+commit, but this is *not* done immediately.  The squashing is done at a
+later time, when you explicitly call ~magit-rebase-autosquash~, or use
+~--autosquash~ with another rebase command.
+
+Some of these commands require that you immediately write a new commit
+message, or that you immediately edit an existing message.
+
+The new commits are called "squash" and "fixup" commits.  The
+difference is that when a "squash" commit is squashed into its
+targeted commit, the user gets a change to modify the message to be
+used for the final commit; while for "fixup" commits the existing
+message of the targeted commit is used as-is and the message of the
+"fixup" commit is discarded.
+
+If point is on a reachable commit, then all of these commands target
+that commit, without requiring confirmation.  If point is on some
+reachable commit, but you want to target another commit, use a prefix
+argument, to select a commit in a log buffer dedicated to that task.
+The meaning of the prefix argument can be inverted by customizing
+~magit-commit-squash-confirm~.
+
+The command descriptions below mention the specific arguments they use
+when calling ~git commit~.  The arguments specified in the menu are
+appended to those arguments.
+
+The next two commands also exist in "instant" variants, which are
+described in the next section.  Those variants behave the same as the
+variants described here, except that they immediately initiate an
+~--autosquash~ rebase.
+
 - Key: c f (magit-commit-fixup) ::
 
-  Create a fixup commit.
+  This command creates a new fixup commit from the staged changes,
+  targeting the reachable commit at point, if any.  Otherwise the
+  user is prompted for a commit.
 
-  With a prefix argument the target commit has to be confirmed.
-  Otherwise the commit at point may be used without confirmation
-  depending on the value of option ~magit-commit-squash-confirm~.
+  Use this variant if you want to correct some minor defect in the
+  targeted commit, which does not require changes to the existing
+  message of the targeted commit.
+
+  This command calls ~git commit --fixup=COMMIT --no-edit~.
 
 - Key: c s (magit-commit-squash) ::
 
-  Create a squash commit, without editing the squash message.
+  This command creates a new squash commit from the staged changes,
+  targeting the reachable commit at point, if any.  Otherwise the
+  user is prompted for a commit.
+
+  Use this variant if you want a chance to make changes to the final
+  commit message, but not until the two commits are being squashed
+  into the final combined commit.
 
-  With a prefix argument the target commit has to be confirmed.
-  Otherwise the commit at point may be used without confirmation
-  depending on the value of option ~magit-commit-squash-confirm~.
+  This command calls ~git commit --squash=COMMIT --no-edit~.
 
 - Key: c A (magit-commit-alter) ::
 
-  Create a squash commit, finalizing the message up front.
+  This command creates a new fixup commit from the staged changes,
+  targeting the reachable commit at point, if any.  Otherwise the
+  user is prompted for a commit.
 
-  With a prefix argument the target COMMIT has to be confirmed.
-  Otherwise the commit at point may be used without confirmation
-  depending on the value of option ~magit-commit-squash-confirm~.
+  Use this variant if you want to write the final commit message now,
+  but (as for all variants in this section) do not want to immediately
+  squash the fixup and targeted commits into a final combined commit.
+
+  This command calls ~git commit --fixup=amend:COMMIT --edit~.
 
 - Key: c n (magit-commit-augment) ::
 
-  Create a squash commit, editing the squash message.
+  This command creates a new squash commit from the staged changes,
+  targeting the reachable commit at point, if any.  Otherwise the
+  user is prompted for a commit.
+
+  Use this variant if you want to describe the new changes now, but
+  want to delay writing the final message, which describes the changes
+  in the combined commit, until you actually combine the squash and
+  target commits into the final commit.  You can think of the new
+  message, which you write here, as a "note", to be integrated once
+  once you write the final commit message.
 
-  With a prefix argument the target commit has to be confirmed.
-  Otherwise the commit at point may be used without confirmation
-  depending on the value of option ~magit-commit-squash-confirm~.
+  This command calls ~git commit --squash=COMMIT --edit~.
 
 - Key: c A (magit-commit-revise) ::
 
-  Reword the message of commit other than the last, without editing
-  its tree.
+  This command pops up a buffer containing the commit message of the
+  reachable commit at point, if any.  Otherwise the user is prompted
+  for a commit to target.
+
+  Use this variant if you want to correct the message of the targeted
+  commit, but want to delay performing the ~--autosquash~ rebase, which
+  actually changes that commit.
+
+  This command calls ~git commit --fixup=reword:COMMIT --edit~.
+
+**** Editing any reachable commit and rebasing immediately
 
-  With a prefix argument the target commit has to be confirmed.
-  Otherwise the commit at point may be used without confirmation
-  depending on the value of option ~magit-commit-squash-confirm~.
+These commands create a new commit, which targets an existing commit,
+from the staged changes.  Any commit that is reachable from HEAD,
+including HEAD itself, can be the target.
 
-**** Editing any reachable commit and rebase immediately
+The new commit is immediately squashed into its target commit, using
+an ~--autosquash~ rebase.
+
+The command descriptions below mention the specific arguments they use
+when calling ~git commit~.  The arguments specified in the menu are
+appended to those arguments when calling ~git commit~.
 
 - Key: c F (magit-commit-instant-fixup) ::
 
-  Create a fixup commit and instantly rebase.
+  This command creates a fixup commit, targeting the reachable commit
+  at point, if any.  Otherwise the user is prompted for a commit. Then
+  it instantly performs a rebase, to squash the new commit into the
+  targeted commit.
+
+  The original commit message of the targeted commit is left untouched.
+
+  This command calls ~git commit --fixup=COMMIT --no-edit~
+  and then ~git rebase --autosquash MERGE-BASE~.
 
 - Key: c S (magit-commit-instant-squash) ::
 
-  Create a squash commit and instantly rebase.
+  This command creates a squash commit, targeting the reachable commit
+  at point, if any.  Otherwise the user is prompted for a commit. Then
+  it instantly performs a rebase, to squash the new commit into the
+  targeted commit.
+
+  During the rebase phase the user is asked to author the final commit
+  message, based on the original message of the targeted commit.
+
+  This command calls ~git commit --squash=COMMIT --no-edit~
+  and then ~git rebase --autosquash MERGE-BASE~.
 
 **** Options for commit commands
 
diff --git a/docs/magit.texi b/docs/magit.texi
index 21930b6..3c7bdbe 100644
--- a/docs/magit.texi
+++ b/docs/magit.texi
@@ -5505,99 +5505,209 @@ Create a new commit.
 @anchor{Editing the last commit}
 @subsubheading Editing the last commit
 
+These commands modify the last (a.k.a., "HEAD") commit.  The commit is
+modified (a.k.a., replaced) immediately.  Similar commands exist for
+modifying other (non-HEAD) commits.  Those commands are described in
+the following two sections.  For each command in this section, we
+mention the respective non-HEAD commands, to make the relation
+explicit.
+
+The command descriptions below mention the specific arguments they use
+when calling @code{git commit}.  The arguments specified in the menu are
+appended to those arguments.
+
 @table @asis
 @item @kbd{c e} (@code{magit-commit-extend})
 @kindex c e
 @findex magit-commit-extend
-Amend the last commit, without editing the message.  With a prefix
-argument keep the committer date, otherwise change it.  The option
-@code{magit-commit-extend-override-date} can be used to inverse the meaning
-of the prefix argument.
+This command amends the staged changes to the last commit, without
+editing its commit message.
+
+This command calls @code{git commit --amend --no-edit}.
 
-Non-interactively respect the optional OVERRIDE-DATE argument and
-ignore the option.
+With a prefix argument the committer date is not updated; without an
+argument it is updated.
+
+The option @code{magit-commit-extend-override-date} can be used to inverse
+the meaning of the prefix argument.  Non-interactively, the optional
+OVERRIDE-DATE argument controls this behavior, and the option is of
+no relevance.
 
 @item @kbd{c a} (@code{magit-commit-amend})
 @kindex c a
 @findex magit-commit-amend
-Amend the last commit.
+This command amends the staged changes to the last commit, and pops
+up a buffer to let the user edit its commit message.
+
+This command calls @code{git commit --amend --edit}.
 
 @item @kbd{c w} (@code{magit-commit-reword})
 @kindex c w
 @findex magit-commit-reword
-Reword the last commit, ignoring staged changes.  With a prefix
-argument keep the committer date, otherwise change it.  The option
-@code{magit-commit-reword-override-date} can be used to inverse the meaning
-of the prefix argument.
+This command pops up a buffer to let the user edit the message of
+the latest commit.  The commit tree remains unchanged and staged
+changes remain staged.
 
-Non-interactively respect the optional OVERRIDE-DATE argument and
-ignore the option.
+This command calls @code{git commit --amend --only --edit}.
+
+With a prefix argument the committer date is not updated; without an
+argument it is updated.
+
+The option @code{magit-commit-reword-override-date} can be used to inverse
+the meaning of the prefix argument.  Non-interactively, the optional
+OVERRIDE-DATE argument controls this behavior, and the option is of
+no relevance.
 @end table
 
 @anchor{Editing any reachable commit}
 @subsubheading Editing any reachable commit
 
+These commands create a new commit, which targets an existing commit,
+from the staged changes and/or using a new commit message.  Any commit
+that is reachable from HEAD, including HEAD itself, can be the target.
+
+The new commit is intended to be eventually squashed into the targeted
+commit, but this is @strong{not} done immediately.  The squashing is done at a
+later time, when you explicitly call @code{magit-rebase-autosquash}, or use
+@code{--autosquash} with another rebase command.
+
+Some of these commands require that you immediately write a new commit
+message, or that you immediately edit an existing message.
+
+The new commits are called "squash" and "fixup" commits.  The
+difference is that when a "squash" commit is squashed into its
+targeted commit, the user gets a change to modify the message to be
+used for the final commit; while for "fixup" commits the existing
+message of the targeted commit is used as-is and the message of the
+"fixup" commit is discarded.
+
+If point is on a reachable commit, then all of these commands target
+that commit, without requiring confirmation.  If point is on some
+reachable commit, but you want to target another commit, use a prefix
+argument, to select a commit in a log buffer dedicated to that task.
+The meaning of the prefix argument can be inverted by customizing
+@code{magit-commit-squash-confirm}.
+
+The command descriptions below mention the specific arguments they use
+when calling @code{git commit}.  The arguments specified in the menu are
+appended to those arguments.
+
+The next two commands also exist in "instant" variants, which are
+described in the next section.  Those variants behave the same as the
+variants described here, except that they immediately initiate an
+@code{--autosquash} rebase.
+
 @table @asis
 @item @kbd{c f} (@code{magit-commit-fixup})
 @kindex c f
 @findex magit-commit-fixup
-Create a fixup commit.
+This command creates a new fixup commit from the staged changes,
+targeting the reachable commit at point, if any.  Otherwise the
+user is prompted for a commit.
 
-With a prefix argument the target commit has to be confirmed.
-Otherwise the commit at point may be used without confirmation
-depending on the value of option @code{magit-commit-squash-confirm}.
+Use this variant if you want to correct some minor defect in the
+targeted commit, which does not require changes to the existing
+message of the targeted commit.
+
+This command calls @code{git commit --fixup=COMMIT --no-edit}.
 
 @item @kbd{c s} (@code{magit-commit-squash})
 @kindex c s
 @findex magit-commit-squash
-Create a squash commit, without editing the squash message.
+This command creates a new squash commit from the staged changes,
+targeting the reachable commit at point, if any.  Otherwise the
+user is prompted for a commit.
+
+Use this variant if you want a chance to make changes to the final
+commit message, but not until the two commits are being squashed
+into the final combined commit.
 
-With a prefix argument the target commit has to be confirmed.
-Otherwise the commit at point may be used without confirmation
-depending on the value of option @code{magit-commit-squash-confirm}.
+This command calls @code{git commit --squash=COMMIT --no-edit}.
 
 @item @kbd{c A} (@code{magit-commit-alter})
 @kindex c A
 @findex magit-commit-alter
-Create a squash commit, finalizing the message up front.
+This command creates a new fixup commit from the staged changes,
+targeting the reachable commit at point, if any.  Otherwise the
+user is prompted for a commit.
 
-With a prefix argument the target COMMIT has to be confirmed.
-Otherwise the commit at point may be used without confirmation
-depending on the value of option @code{magit-commit-squash-confirm}.
+Use this variant if you want to write the final commit message now,
+but (as for all variants in this section) do not want to immediately
+squash the fixup and targeted commits into a final combined commit.
+
+This command calls @code{git commit --fixup=amend:COMMIT --edit}.
 
 @item @kbd{c n} (@code{magit-commit-augment})
 @kindex c n
 @findex magit-commit-augment
-Create a squash commit, editing the squash message.
+This command creates a new squash commit from the staged changes,
+targeting the reachable commit at point, if any.  Otherwise the
+user is prompted for a commit.
+
+Use this variant if you want to describe the new changes now, but
+want to delay writing the final message, which describes the changes
+in the combined commit, until you actually combine the squash and
+target commits into the final commit.  You can think of the new
+message, which you write here, as a "note", to be integrated once
+once you write the final commit message.
 
-With a prefix argument the target commit has to be confirmed.
-Otherwise the commit at point may be used without confirmation
-depending on the value of option @code{magit-commit-squash-confirm}.
+This command calls @code{git commit --squash=COMMIT --edit}.
 
 @item @kbd{c A} (@code{magit-commit-revise})
 @kindex c A
 @findex magit-commit-revise
-Reword the message of commit other than the last, without editing
-its tree.
+This command pops up a buffer containing the commit message of the
+reachable commit at point, if any.  Otherwise the user is prompted
+for a commit to target.
+
+Use this variant if you want to correct the message of the targeted
+commit, but want to delay performing the @code{--autosquash} rebase, which
+actually changes that commit.
 
-With a prefix argument the target commit has to be confirmed.
-Otherwise the commit at point may be used without confirmation
-depending on the value of option @code{magit-commit-squash-confirm}.
+This command calls @code{git commit --fixup=reword:COMMIT --edit}.
 @end table
 
-@anchor{Editing any reachable commit and rebase immediately}
-@subsubheading Editing any reachable commit and rebase immediately
+@anchor{Editing any reachable commit and rebasing immediately}
+@subsubheading Editing any reachable commit and rebasing immediately
+
+These commands create a new commit, which targets an existing commit,
+from the staged changes.  Any commit that is reachable from HEAD,
+including HEAD itself, can be the target.
+
+The new commit is immediately squashed into its target commit, using
+an @code{--autosquash} rebase.
+
+The command descriptions below mention the specific arguments they use
+when calling @code{git commit}.  The arguments specified in the menu are
+appended to those arguments when calling @code{git commit}.
 
 @table @asis
 @item @kbd{c F} (@code{magit-commit-instant-fixup})
 @kindex c F
 @findex magit-commit-instant-fixup
-Create a fixup commit and instantly rebase.
+This command creates a fixup commit, targeting the reachable commit
+at point, if any.  Otherwise the user is prompted for a commit. Then
+it instantly performs a rebase, to squash the new commit into the
+targeted commit.
+
+The original commit message of the targeted commit is left untouched.
+
+This command calls @code{git commit --fixup=COMMIT --no-edit}
+and then @code{git rebase --autosquash MERGE-BASE}.
 
 @item @kbd{c S} (@code{magit-commit-instant-squash})
 @kindex c S
 @findex magit-commit-instant-squash
-Create a squash commit and instantly rebase.
+This command creates a squash commit, targeting the reachable commit
+at point, if any.  Otherwise the user is prompted for a commit. Then
+it instantly performs a rebase, to squash the new commit into the
+targeted commit.
+
+During the rebase phase the user is asked to author the final commit
+message, based on the original message of the targeted commit.
+
+This command calls @code{git commit --squash=COMMIT --no-edit}
+and then @code{git rebase --autosquash MERGE-BASE}.
 @end table
 
 @anchor{Options for commit commands}