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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 25, 2021, 20:48 UTC
Message-ID: <xmqq4khzub4m.fsf@gitster.g>
In-Reply-To: <20210225100855.25530-7-charvi077@gmail.com>

Charvi Mendiratta <charvi077@gmail.com> writes:

> +--fixup=[(amend|reword):]<commit>::
> +	When used without options, lets's say `git commit --fixup=<commit>`,
> +	it creates a "fixup!" commit where the commit message will be

Be careful to use word 'option' that refers to something other than what a casual reader would think of an `--option` in the description of the `--fixup` option.

	Without `amend:` or `reword:`, create a `fixup!` commit where...

would be sufficient, no?

Show 7 quoted lines

> +	the subject line from the specified commit with a prefix of
> +	"fixup! ". The resulting "fixup!" commit is further used with
> +	`git rebase --autosquash` to fixup the content of the specified
> +	commit.
> ++
> +When used with option `amend`, let's say `git commit --fixup=amend:<commit>`,
> +it creates a "amend!" commit to fixup both the content and the commit log

	The `--fixup=amend:<commit>` form creates an "amend!" commit to...

> +message of the specified commit. The resulting "amend!" commit's 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

While that SP inside the double-quote may be technically more correct (and it was inherited from the original), I think with 'a prefix of "amend!"' is still understandable and a lot easier to read, especially because you'd mention "amend!" a few more times in the same paragraph below.

The same comment applies to "fixup! " above.

> +specified commit. It also invokes an editor seeded with the "amend!" commit
> +log message to allow to edit further. And it denies to create "amend!" commit

"amend!" commit log message -> log message of the "amend!" commit

denies -> refuses

> +if it's commit message body is empty unless used with `allow-empty-message`
> +option. "amend!" commit when rebased with `--autosquash` will fixup the

with the `--allow-empty-message` option.

Show 6 quoted lines

> +contents and replace the commit message of the specified commit with the
> +"amend!" commit's message body.
> ++
> +When used with alternative option `reword`, let's say
> +`git commit --fixup=reword:<commit>`, it works similar to `amend` option, but
> +here it creates an empty "amend!" commit, i.e it does not take any staged

	The `--fixup=reword:<commit>` form creates an `amend!`
	commit similar to `--fixup=amend:<commit>` creates, but it
	records the same tree as `HEAD`, i.e. it does not ...

Show 5 quoted lines

> +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`.
> ++
> +Unlike `--fixup` without options, `--fixup=[amend/reword]:` is incompatible with
> +`-m` commit message option.

	The `--fixup=amend:` and `--fixup=reword:` forms cannot be
	used with other options to add to the commit log message,
	e.g. `-m`.

Again, why is `-m` so special? Shouldn't -F/-c/-C also be incompatible?

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

Good.