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

> Sent: Wednesday, April 03, 2013 9:04 PM
> > 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:

> > -- >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.
> 
> I don't think we should say "Create New" at the start of the sentence,
> which may confuse some, rather we should start with the key
> 'Replace' verb, essentially swapping the parts to say:
> 
>  + Replace the tip of the current branch with a fresh commit.
> [or updated commit, or new commit, or ...]

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