Improve documentation about commit commands

1 files changed, 84 insertions, 40 deletions

diff --git a/lisp/magit-commit.el b/lisp/magit-commit.el
index 14efb14..f9cc7c9 100644
--- a/lisp/magit-commit.el
+++ b/lisp/magit-commit.el
@@ -201,12 +201,13 @@ Also see https://github.com/magit/magit/issues/4132."
 
 ;;;###autoload
 (defun magit-commit-extend (&optional args override-date)
-  "Amend the last commit, without editing the message.
+  "Amend staged changes to the last commit, without editing its 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.
-\n(git commit --amend --no-edit)"
+With a prefix argument do not update the committer date; without an
+argument update it. The option `magit-commit-extend-override-date'
+can be used to inverse the meaning of the prefix argument.  Called
+non-interactively, the optional OVERRIDE-DATE argument controls this
+behavior, and the option is of no relevance."
   (interactive (list (magit-commit-arguments)
                      (if current-prefix-arg
                          (not magit-commit-extend-override-date)
@@ -221,23 +222,20 @@ to inverse the meaning of the prefix argument.
 
 ;;;###autoload
 (defun magit-commit-amend (&optional args)
-  "Amend the last commit.
-\n(git commit --amend ARGS)"
+  "Amend staged changes (if any) to the last commit, and edit its message."
   (interactive (list (magit-commit-arguments)))
   (magit-commit-amend-assert)
   (magit-run-git-with-editor "commit" "--amend" args))
 
 ;;;###autoload
 (defun magit-commit-reword (&optional args override-date)
-  "Reword the last commit, ignoring staged changes.
+  "Reword the message of the last commit, without amending its tree.
 
-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.
-
-Non-interactively respect the optional OVERRIDE-DATE argument
-and ignore the option.
-\n(git commit --amend --only)"
+With a prefix argument do not update the committer date; without an
+argument update it. The option `magit-commit-reword-override-date'
+can be used to inverse the meaning of the prefix argument.  Called
+non-interactively, the optional OVERRIDE-DATE argument controls this
+behavior, and the option is of no relevance."
   (interactive (list (magit-commit-arguments)
                      (if current-prefix-arg
                          (not magit-commit-reword-override-date)
@@ -254,58 +252,86 @@ and ignore the option.
 
 ;;;###autoload
 (defun magit-commit-fixup (&optional commit args)
-  "Create a fixup commit.
+  "Create a fixup commit, leaving the original commit message untouched.
+
+If there is a reachable commit at point, target that.  Otherwise prompt
+for a commit.  If `magit-commit-squash-confirm' is non-nil, always make
+the user explicitly select a commit, in a buffer dedicated to that task.
 
-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'."
+During a later rebase, when this commit gets squashed into its targeted
+commit, the original message of the targeted commit is used as-is.
+
+In other words, call \"git commit --fixup=COMMIT --no-edit\"."
   (interactive (list (magit-commit-at-point)
                      (magit-commit-arguments)))
   (magit-commit-squash-internal "--fixup=" commit args))
 
 ;;;###autoload
 (defun magit-commit-squash (&optional commit args)
-  "Create a squash commit, without editing the squash message.
+  "Create a squash commit, without the user authoring a commit message.
+
+If there is a reachable commit at point, target that.  Otherwise prompt
+for a commit.  If `magit-commit-squash-confirm' is non-nil, always make
+the user explicitly select a commit, in a buffer dedicated to that task.
 
-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'.
+During a later rebase, when this commit gets squashed into its targeted
+commit, the user is given a chance to edit the original message to take
+the changes from the squash commit into account.
 
-If you want to immediately add a message to the squash commit,
-then use `magit-commit-augment' instead of this command."
+In other words, call \"git commit --squash=COMMIT --no-edit\"."
   (interactive (list (magit-commit-at-point)
                      (magit-commit-arguments)))
   (magit-commit-squash-internal "--squash=" commit args))
 
 ;;;###autoload
 (defun magit-commit-alter (&optional commit args)
-  "Create a squash commit, finalizing the message up front.
+  "Create a squash commit, authoring the final commit message now.
 
-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'."
+If there is a reachable commit at point, target that.  Otherwise prompt
+for a commit.  If `magit-commit-squash-confirm' is non-nil, always make
+the user explicitly select a commit, in a buffer dedicated to that task.
+
+During a later rebase, when this commit gets squashed into its targeted
+commit, the original message of the targeted commit is replaced with the
+message of this commit, without the user automatically being given a
+chance to edit again.
+
+In other words, call \"git commit --fixup=amend:COMMIT --edit\"."
   (interactive (list (magit-commit-at-point)
                      (magit-commit-arguments)))
   (magit-commit-squash-internal "--fixup=amend:" commit args nil 'edit))
 
 ;;;###autoload
 (defun magit-commit-augment (&optional commit args)
-  "Create a squash commit, editing the squash message.
+  "Create a squash commit, authoring a new temporary commit message.
+
+If there is a reachable commit at point, target that.  Otherwise prompt
+for a commit.  If `magit-commit-squash-confirm' is non-nil, always make
+the user explicitly select a commit, in a buffer dedicated to that task.
+
+During a later rebase, when this commit gets squashed into its targeted
+commit, the user is asked to write a final commit message, in a buffer
+that starts out containing both the original commit message, as well as
+the temporary commit message of the squash 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'."
+In other words, call \"git commit --squash=COMMIT --edit\"."
   (interactive (list (magit-commit-at-point)
                      (magit-commit-arguments)))
   (magit-commit-squash-internal "--squash=" commit args nil 'edit))
 
 ;;;###autoload
 (defun magit-commit-revise (&optional commit args)
-  "Reword the message of commit other than the last, without editing its tree.
+  "Reword the message of an existing commit, without editing its tree.
 
-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'."
+If there is a reachable commit at point, target that.  Otherwise prompt
+for a commit.  If `magit-commit-squash-confirm' is non-nil, always make
+the user explicitly select a commit, in a buffer dedicated to that task.
+
+During a later rebase, when this commit gets squashed into its targeted
+commit, a combined commit is created which uses the message of the fixup
+commit and the tree of the targeted commit.
+
+In other words, call \"git commit --fixup=reword:COMMIT --edit\"."
   (interactive (list (magit-commit-at-point)
                      (magit-commit-arguments)))
   (magit-commit-squash-internal "--fixup=reword:" commit args 'nopatch 'edit))
@@ -314,14 +340,32 @@ depending on the value of option `magit-commit-squash-confirm'."
 
 ;;;###autoload
 (defun magit-commit-instant-fixup (&optional commit args)
-  "Create a fixup commit targeting COMMIT and instantly rebase."
+  "Create a fixup commit, and immediately combine it with its target.
+
+If there is a reachable commit at point, target that.  Otherwise prompt
+for a commit.  If `magit-commit-squash-confirm' is non-nil, always make
+the user explicitly select a commit, in a buffer dedicated to that task.
+
+Leave the original commit message of the targeted commit untouched.
+
+Like `magit-commit-fixup' but also run a `--autofixup' rebase."
   (interactive (list (magit-commit-at-point)
                      (magit-commit-arguments)))
   (magit-commit-squash-internal "--fixup=" commit args nil nil 'rebase))
 
 ;;;###autoload
 (defun magit-commit-instant-squash (&optional commit args)
-  "Create a squash commit targeting COMMIT and instantly rebase."
+  "Create a squash commit, and immediately combine it with its target.
+
+If there is a reachable commit at point, target that.  Otherwise prompt
+for a commit.  If `magit-commit-squash-confirm' is non-nil, always make
+the user explicitly select a commit, in a buffer dedicated to that task.
+
+Turing the rebase phase, when the two commits are being squashed, ask
+the user to author the final commit message, based on the original
+message of the targeted commit.
+
+Like `magit-commit-squash' but also run a `--autofixup' rebase."
   (interactive (list (magit-commit-at-point)
                      (magit-commit-arguments)))
   (magit-commit-squash-internal "--squash=" commit args nil nil 'rebase))
@@ -436,7 +480,7 @@ depending on the value of option `magit-commit-squash-confirm'."
 
 ;;;###autoload
 (defun magit-commit-reshelve (date update-author &optional args)
-  "Change the committer date and possibly the author date of `HEAD'.
+  "Change committer (and possibly author) date of the last commit.
 
 The current time is used as the initial minibuffer input and the
 original author or committer date is available as the previous