Re: [PATCH v4 6/6] doc/git-commit: add documentation for fixup=[amend|reword] options

On Wed, Mar 10, 2021 at 2:45 PM Charvi Mendiratta [off-list ref] wrote:

s/it's/its/

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>`.

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`.

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.

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.

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`.