On Wed, 2013-04-03 at 23:25 +0100, Philip Oakley wrote:
> Sent: Wednesday, April 03, 2013 9:04 PM
> > Junio C Hamano <gits...@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:
Sorry I keep forgetting lately, it seems I've been away from core git
too long.
Signed-off-by: Carlos Martín Nieto <c...@elego.de>
> > -- >8 --
> > From: Carlos Martín Nieto <c...@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 ...]
Ack, we should lead with the goal, I'd go for the
"Replace the tip of the current branch with a new commit"
wording.
>
> > The recorded tree is prepared as usual (including
> > + the effect of the `-i` and `-o` options and explicit
Is "recorded tree" what we want to say at porcelain level? I'd go for
"The commit" as in my version, but maybe it's just the way I think about
it. I don't feel too strongly about changing it, though.
> > + 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).
> > +
The rest looks great.
cmn
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
