On Wed, Mar 10, 2021 at 2:45 PM Charvi Mendiratta <charvi077@xxxxxxxxx> wrote:
> ---
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> @@ -86,11 +86,40 @@ OPTIONS
> +--fixup=[(amend|reword):]<commit>::
> + Construct a new commit for use with `rebase --autosquash`,
> + which fixes the specified commit. The plain form
> + `--fixup=<commit>` creates a "fixup!" commit, that allows
> + to fixup only the content of the specified commit and leave
> + it's commit log message untouched. When used with `amend:`
s/it's/its/
> + or `reword:`, it creates "amend!" commit that is like "fixup!"
> + commit but it allows to fixup both the content and the commit
> + log message of the specified commit. The commit log message of
> + the specified commit is fixed implicitly by replacing it with
> + the "amend!" commit's message body upon `rebase --autosquash`.
The first half of this description is clear. The second half gets
bogged down and difficult to decipher. It also seems to claim that
"reword:" can change the content of <commit>, which isn't accurate at
the UI level (even if it happens to reflect the underlying
implementation). I might have written the above description like this:
Create a new commit which "fixes up" `<commit>` when applied with
`git rebase --autosquash`. Plain `--fixup=<commit>` creates a
"fixup!" commit which changes the content of `<commit>` but leaves
its log message untouched. `--fixup=amend:<commit>` is similar but
creates an "amend!" commit which also replaces the log message of
`<commit>` with the log message of the "amend!" commit.
`--fixup=reword:<commit>` creates an "amend!" commit which
replaces the log message of `<commit>` with its own log message
but makes no changes to the content of `<commit>`.
> +The resulting "fixup!" commit message will be the subject line
> +from the specified commit with a prefix of "fixup!". Can be used
> +with additional commit message option `-m`.
This gives details without providing meaning. If I didn't already know
how this all works, I think I'd probably be mystified about what it is
trying to say. Providing context by mentioning `git rebase
--autosquash` would help explain the significance of "fixup!".
Similarly, it's not clear on the surface why this mentions `-m` at
all. I might have written it like this:
The commit created by plain `--fixup=<commit>` has a subject
composed of "fixup!" followed by the subject line from <commit>,
and is recognized specially by `git rebase --autosquash`. The `-m`
option may be used to supplement the log message of the created
commit, but the additional commentary will be thrown away once the
"fixup!" commit is squashed into `<commit>` by `git rebase
--autosquash`.
> +The `--fixup=amend:<commit>` form creates an "amend!" commit where
> +its commit message subject will be the subject line from the
> +specified commit with a prefix of "amend!" and the message body
> +will be commit log message of the specified commit. It also invokes
> +an editor seeded with the log message of the "amend!" commit to
> +allow to edit further. It refuses to create "amend!" commit if it's
> +commit message body is empty unless used with the
> +`--allow-empty-message` option.
This is reasonable, but does get into the weeds somewhat and uses
potentially unusual terms such as "seeded". It can be tightened up a
bit by building upon what was explained earlier for plain
`--fixup=<commit>`. To really round it out and give proper context for
understanding the purpose, it would also be helpful to explain how an
"amend!" commit is handled by `git rebase --autosquash`. I might have
written it like this:
The commit created by `--fixup=amend:<commit>` is similar but its
subject is instead prefixed with "amend!". The log message of
<commit> is copied into the log message of the "amend!" commit and
opened in an editor so it can be refined. When `git rebase
--autosquash` squashes the "amend!" commit into `<commit>`, the
log message of `<commit>` is replaced by the refined log message
from the "amend!" commit. It is an error for the "amend!" commit's
log message to be empty unless `--allow-empty-message` is
specified.
> +The `--fixup=reword:<commit>` aliases `--fixup=amend:<commit> --only`
> +and it also creates an "amend!" commit, but here it records the same
> +tree as `HEAD`, i.e. it does not take any staged changes and only allows
> +to fixup the commit message of the specified commit. It will reword the
> +specified commit when it is rebased with `--autosquash`.
This gets too deep into the techno-speak by talking about "tree" and
`HEAD`. You can convey the same concept more simply by saying merely
that it creates an empty commit. I might have written it like this:
`--fixup=reword:<commit>` is shorthand for `--fixup=amend:<commit>
--only`. It creates an "amend!" commit with only a log message
(ignoring any changes staged in the index). When squashed by `git
rebase --autosquash`, it replaces the log message of `<commit>`
without making any other changes.
> +Also, after fixing the commit using `--fixup`, with or without option
> +and rebased with `--autosquash`, the authorship of the original commit
> +remains unchanged. See linkgit:git-rebase[1] for details.
It sounds odd to start this sentence with "also". Perhaps:
Neither "fixup!" nor "amend!" commits change authorship of
`<commit>` when applied by `git rebase --autosquash`.
