threads / patch / 33364

patchDocumentation/git-commit: reword the --amend explanation

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

## tl;dr

7 messages between Apr 3, 2013 and Apr 5, 2013. Diffs are folded; open one to read it.

replies: 6people: 3as markdown or json

Carlos Martín Nieto· Apr 3, 2013, 13:07 UTC · lore

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(-)
Show changes to Documentation/git-commit.txt +5 −8
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
Junio C Hamano· Apr 3, 2013, 15:01 UTC · re: Carlos Martín Nieto · lore

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

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:
Junio C Hamano· Apr 3, 2013, 20:04 UTC · re: Junio C Hamano · lore

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(-)
Show changes to Documentation/git-commit.txt +9 −8
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:
Philip Oakley· Apr 3, 2013, 22:25 UTC · re: Junio C Hamano · lore

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

Sent: Wednesday, April 03, 2013 9:04 PM
Show 60 quoted lines
> 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 ...]
Show 13 quoted lines
>                  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
Carlos Martín Nieto· Apr 4, 2013, 16:49 UTC · re: Philip Oakley · lore

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

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

Show 7 quoted lines
> > + 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
Junio C Hamano· Apr 4, 2013, 17:04 UTC · re: Carlos Martín Nieto · lore

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

Carlos Martín Nieto <cmn@elego.de> writes:
Show 10 quoted lines
> 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(-)
Show changes to Documentation/git-commit.txt +2 −2
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
Carlos Martín Nieto· Apr 5, 2013, 08:50 UTC · re: Junio C Hamano · lore

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

On Thu, 2013-04-04 at 10:04 -0700, Junio C Hamano wrote:
Show 39 quoted lines
> 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

← back to recent threads