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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 3, 2013, 15:01 UTC
Message-ID: <7v4nfn7j5i.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1364994441-15961-1-git-send-email-cmn@elego.de>

Carlos Martín Nieto <cmn@elego.de> writes:

Show 6 quoted lines

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

Sign-off?

> The current text is from 2006, which I guess explains the wording.

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.

Thanks for looking into this.

Show 27 quoted lines

>  Documentation/git-commit.txt | 13 +++++--------
>  1 file changed, 5 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 42c22bb..48dac29 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -198,14 +198,11 @@ 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.
> +	Amend the tip of the current branch. The commit is prepared as
> +	usual (including -i/-o and explicit paths) and the editor
> +	starts off with the current tip's commit message. The new
> +	commit has the same parents and author as the current one and
> +	replaces it as the tip.
>  +
>  --
>  It is a rough equivalent for: