branch: elpa/magit
commit 778ad46f01ecbc0a71cf3dd85c33c72afa55a3a5
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
Improve documentation about commit commands
---
CHANGELOG | 2 +
docs/magit.org | 184 ++++++++++++++++++++++++++++++++++++++++----------
docs/magit.texi | 186 ++++++++++++++++++++++++++++++++++++++++-----------
lisp/magit-commit.el | 124 +++++++++++++++++++++++-----------
4 files changed, 381 insertions(+), 115 deletions(-)
diff --git a/CHANGELOG b/CHANGELOG
index 1ab667411dd..979de2742db 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -21,6 +21,8 @@
- Added new commands ~magit-commit-alter~ and ~magit-commit-revise~. #5261
+- Improved commit menu, documentation and implementation details. #5261
+
Bug fixes:
- When applying a stash, it was not always discovered when the trivial
diff --git a/docs/magit.org b/docs/magit.org
index acdfc666a43..4db6a11c522 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 21930b688fd..3c7bdbe4405 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}
diff --git a/lisp/magit-commit.el b/lisp/magit-commit.el
index 14efb147db7..f9cc7c9936e 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
