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

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

[Carlos Martín Nieto]

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

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

 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:
-- 
1.8.2.524.g8f8def7

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

[Junio C Hamano]

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

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

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

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

[Junio C Hamano]

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:

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

[Philip Oakley]

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

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

>                  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:
>
> --
Philip 

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

[Carlos Martín Nieto]

On Wed, 2013-04-03 at 23:25 +0100, Philip Oakley wrote:
> 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:


Sorry I keep forgetting lately, it seems I've been away from core git
too long.

Signed-off-by: Carlos Martín Nieto <cmn@elego.de>

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

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

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

[Junio C Hamano]

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

> On Wed, 2013-04-03 at 23:25 +0100, Philip Oakley wrote:
>
>>  + 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.

We would want to be careful to make sure that the reader understands
that the "new commit" is created by running this command (i.e. it is
not like "git branch -f $current_branch $new_commit"), but other
than that, sounds sensible.

Perhaps like this?

 Documentation/git-commit.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index bc919ac..61266d8 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -190,8 +190,8 @@ OPTIONS
 	without changing its commit message.
 
 --amend::
-	Create a new commit and replace the tip of the current
-	branch. The recorded tree is prepared as usual (including
+	Replace the tip of the current branch by creating a new
+	commit. 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

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

[Carlos Martín Nieto]

On Thu, 2013-04-04 at 10:04 -0700, Junio C Hamano wrote:
> Carlos Martín Nieto <cmn@elego.de> writes:
> 
> > On Wed, 2013-04-03 at 23:25 +0100, Philip Oakley wrote:
> >
> >>  + 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.
> 
> We would want to be careful to make sure that the reader understands
> that the "new commit" is created by running this command (i.e. it is
> not like "git branch -f $current_branch $new_commit"), but other
> than that, sounds sensible.
> 
> Perhaps like this?
> 
>  Documentation/git-commit.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index bc919ac..61266d8 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -190,8 +190,8 @@ OPTIONS
>  	without changing its commit message.
>  
>  --amend::
> -	Create a new commit and replace the tip of the current
> -	branch. The recorded tree is prepared as usual (including
> +	Replace the tip of the current branch by creating a new
> +	commit. 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
> 

Looks good, yeah. This should stop anybody thinking that they can
replace the tip with an arbitrary commit.

   cmn