Re: [PATCH] Documentation/git-commit: reword the --amend explanation

> Junio C Hamano <gitster@pobox.com> writes:
>
>> Yes, and since then we gained --no-edit option and such, so "editor
>> starts off" also needs to be rethought, no?  The original wording
>> with "seeded" may have a better chance of survival, I suspect, but
>> still needs some adjustment.
>
> So here is my attempt.  We still need a sign-off from you even if we
> decide to use this version.  Relative to your original patch:
>
> * Using "amend" to explain what "--amend" does felt a bit
>   tautological; I moved the "replaces it" to the opening.
>
> * We do not necessarily launch the editor, and if you give the
>   message in some other way we do not even reuse the original log
>   message.
>
> * Mention --reset-author at the same time mentioning that by
>   default the authorship is carried forward.
>
> * "The commit is prepared as usual" was meant to describe how the
>   content to be recorded (i.e. the tree object contained in the
>   resulting commit) is shaped, but I felt it a bit too unclear
>   without saying either content or tree (it could be some other
>   aspects of the commit like the log message and authorship, etc.)
>   I tentatively replaced it with "The recorded tree is prepared",
>   but there may be a better phrasing.
>
> -- >8 --
> From: Carlos Martín Nieto <cmn@elego.de>
>
> The explanation for 'git commit --amend' talks about preparing a tree
> object, which shouldn't be how user-facing documentation talks about
> commit.
>
> Reword it to say it works as usual, but replaces the current commit.
>
> ---
> Documentation/git-commit.txt | 17 +++++++++--------
> 1 file changed, 9 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/git-commit.txt 
> b/Documentation/git-commit.txt
> index 19cbb90..bc919ac 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -190,14 +190,15 @@ OPTIONS
>  without changing its commit message.
>
> --amend::
> - Used to amend the tip of the current branch. Prepare the tree
> - object you would want to replace the latest commit as usual
> - (this includes the usual -i/-o and explicit paths), and the
> - commit log editor is seeded with the commit message from the
> - tip of the current branch. The commit you create replaces the
> - current tip -- if it was a merge, it will have the parents of
> - the current tip as parents -- so the current top commit is
> - discarded.
> + Create a new commit and replace the tip of the current
> + branch.

>                  The recorded tree is prepared as usual (including
> + the effect of the `-i` and `-o` options and explicit
> + pathspec), and the message from the original commit is used
> + as the starting point, instead of an empty message, when no
> + other message is specified from the command line via options
> + such as `-m`, `-F`, `-c`, etc.  The new commit has the same
> + parents and author as the current one (the `--reset-author`
> + option can countermand this).
> +
> --
> It is a rough equivalent for:
>
> --