{"thread":{"id":"33364","subject":"[PATCH] Documentation/git-commit: reword the --amend explanation","startedAt":"2013-04-03T13:07:21Z","lastAt":"2013-04-05T08:50:05Z","messageCount":7,"participants":["Carlos Martín Nieto","Junio C Hamano","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"213032","messageId":"1364994441-15961-1-git-send-email-cmn@elego.de","threadId":"33364","inReplyTo":null,"subject":"[PATCH] Documentation/git-commit: reword the --amend explanation","fromName":"Carlos Martín Nieto","fromEmail":"cmn@elego.de","sentAt":"2013-04-03T13:07:21Z","receivedAt":"2013-04-03T13:07:21Z","isPatch":true,"sender":{"key":"cmn@elego.de","avatar":"https://avatars.githubusercontent.com/u/335443?v=4"},"body":"The explanation for 'git commit --amend' talks about preparing a tree\nobject, which shouldn't be how user-facing documentation talks about\ncommit.\n\nReword it to say it works as usual, but replaces the current commit.\n---\n\nThe current text is from 2006, which I guess explains the wording.\n\n Documentation/git-commit.txt | 13 +++++--------\n 1 file changed, 5 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 42c22bb..48dac29 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -198,14 +198,11 @@ OPTIONS\n \twithout changing its commit message.\n \n --amend::\n-\tUsed to amend the tip of the current branch. Prepare the tree\n-\tobject you would want to replace the latest commit as usual\n-\t(this includes the usual -i/-o and explicit paths), and the\n-\tcommit log editor is seeded with the commit message from the\n-\ttip of the current branch. The commit you create replaces the\n-\tcurrent tip -- if it was a merge, it will have the parents of\n-\tthe current tip as parents -- so the current top commit is\n-\tdiscarded.\n+\tAmend the tip of the current branch. The commit is prepared as\n+\tusual (including -i/-o and explicit paths) and the editor\n+\tstarts off with the current tip's commit message. The new\n+\tcommit has the same parents and author as the current one and\n+\treplaces it as the tip.\n +\n --\n It is a rough equivalent for:\n-- \n1.8.2.524.g8f8def7\n"},{"id":"213040","messageId":"7v4nfn7j5i.fsf@alter.siamese.dyndns.org","threadId":"33364","inReplyTo":"1364994441-15961-1-git-send-email-cmn@elego.de","subject":"Re: [PATCH] Documentation/git-commit: reword the --amend explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-03T15:01:29Z","receivedAt":"2013-04-03T15:01:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Carlos Martín Nieto writes:\n\n> The explanation for 'git commit --amend' talks about preparing a tree\n> object, which shouldn't be how user-facing documentation talks about\n> commit.\n>\n> Reword it to say it works as usual, but replaces the current commit.\n> ---\n\nSign-off?\n\n> The current text is from 2006, which I guess explains the wording.\n\nYes, and since then we gained --no-edit option and such, so \"editor\nstarts off\" also needs to be rethought, no? The original wording\nwith \"seeded\" may have a better chance of survival, I suspect, but\nstill needs some adjustment.\n\nThanks for looking into this.\n\n> Documentation/git-commit.txt | 13 +++++--------\n> 1 file changed, 5 insertions(+), 8 deletions(-)\n>\n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index 42c22bb..48dac29 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -198,14 +198,11 @@ OPTIONS\n> \twithout changing its commit message.\n> \n> --amend::\n> -\tUsed to amend the tip of the current branch. Prepare the tree\n> -\tobject you would want to replace the latest commit as usual\n> -\t(this includes the usual -i/-o and explicit paths), and the\n> -\tcommit log editor is seeded with the commit message from the\n> -\ttip of the current branch. The commit you create replaces the\n> -\tcurrent tip -- if it was a merge, it will have the parents of\n> -\tthe current tip as parents -- so the current top commit is\n> -\tdiscarded.\n> +\tAmend the tip of the current branch. The commit is prepared as\n> +\tusual (including -i/-o and explicit paths) and the editor\n> +\tstarts off with the current tip's commit message. The new\n> +\tcommit has the same parents and author as the current one and\n> +\treplaces it as the tip.\n> +\n> --\n> It is a rough equivalent for:\n"},{"id":"213065","messageId":"7vtxnn4c02.fsf@alter.siamese.dyndns.org","threadId":"33364","inReplyTo":"7v4nfn7j5i.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-commit: reword the --amend explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-03T20:04:13Z","receivedAt":"2013-04-03T20:04:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Yes, and since then we gained --no-edit option and such, so \"editor\n> starts off\" also needs to be rethought, no? The original wording\n> with \"seeded\" may have a better chance of survival, I suspect, but\n> still needs some adjustment.\n\nSo here is my attempt. We still need a sign-off from you even if we\ndecide to use this version. Relative to your original patch:\n\n * Using \"amend\" to explain what \"--amend\" does felt a bit\n tautological; I moved the \"replaces it\" to the opening.\n\n * We do not necessarily launch the editor, and if you give the\n message in some other way we do not even reuse the original log\n message.\n\n * Mention --reset-author at the same time mentioning that by\n default the authorship is carried forward.\n\n * \"The commit is prepared as usual\" was meant to describe how the\n content to be recorded (i.e. the tree object contained in the\n resulting commit) is shaped, but I felt it a bit too unclear\n without saying either content or tree (it could be some other\n aspects of the commit like the log message and authorship, etc.)\n I tentatively replaced it with \"The recorded tree is prepared\",\n but there may be a better phrasing.\n\n-- >8 --\nFrom: Carlos Martín Nieto \n\nThe explanation for 'git commit --amend' talks about preparing a tree\nobject, which shouldn't be how user-facing documentation talks about\ncommit.\n\nReword it to say it works as usual, but replaces the current commit.\n\n---\n Documentation/git-commit.txt | 17 +++++++++--------\n 1 file changed, 9 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 19cbb90..bc919ac 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -190,14 +190,15 @@ OPTIONS\n \twithout changing its commit message.\n \n --amend::\n-\tUsed to amend the tip of the current branch. Prepare the tree\n-\tobject you would want to replace the latest commit as usual\n-\t(this includes the usual -i/-o and explicit paths), and the\n-\tcommit log editor is seeded with the commit message from the\n-\ttip of the current branch. The commit you create replaces the\n-\tcurrent tip -- if it was a merge, it will have the parents of\n-\tthe current tip as parents -- so the current top commit is\n-\tdiscarded.\n+\tCreate a new commit and replace the tip of the current\n+\tbranch. The recorded tree is prepared as usual (including\n+\tthe effect of the `-i` and `-o` options and explicit\n+\tpathspec), and the message from the original commit is used\n+\tas the starting point, instead of an empty message, when no\n+\tother message is specified from the command line via options\n+\tsuch as `-m`, `-F`, `-c`, etc. The new commit has the same\n+\tparents and author as the current one (the `--reset-author`\n+\toption can countermand this).\n +\n --\n It is a rough equivalent for:\n"},{"id":"213073","messageId":"50CA4F4141DD484D97CA8BA571529F65@PhilipOakley","threadId":"33364","inReplyTo":"7vtxnn4c02.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-commit: reword the --amend explanation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-04-03T22:25:36Z","receivedAt":"2013-04-03T22:25:36Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Sent: Wednesday, April 03, 2013 9:04 PM\n> Junio C Hamano writes:\n>\n>> Yes, and since then we gained --no-edit option and such, so \"editor\n>> starts off\" also needs to be rethought, no? The original wording\n>> with \"seeded\" may have a better chance of survival, I suspect, but\n>> still needs some adjustment.\n>\n> So here is my attempt. We still need a sign-off from you even if we\n> decide to use this version. Relative to your original patch:\n>\n> * Using \"amend\" to explain what \"--amend\" does felt a bit\n> tautological; I moved the \"replaces it\" to the opening.\n>\n> * We do not necessarily launch the editor, and if you give the\n> message in some other way we do not even reuse the original log\n> message.\n>\n> * Mention --reset-author at the same time mentioning that by\n> default the authorship is carried forward.\n>\n> * \"The commit is prepared as usual\" was meant to describe how the\n> content to be recorded (i.e. the tree object contained in the\n> resulting commit) is shaped, but I felt it a bit too unclear\n> without saying either content or tree (it could be some other\n> aspects of the commit like the log message and authorship, etc.)\n> I tentatively replaced it with \"The recorded tree is prepared\",\n> but there may be a better phrasing.\n>\n> -- >8 --\n> From: Carlos Martín Nieto \n>\n> The explanation for 'git commit --amend' talks about preparing a tree\n> object, which shouldn't be how user-facing documentation talks about\n> commit.\n>\n> Reword it to say it works as usual, but replaces the current commit.\n>\n> ---\n> Documentation/git-commit.txt | 17 +++++++++--------\n> 1 file changed, 9 insertions(+), 8 deletions(-)\n>\n> diff --git a/Documentation/git-commit.txt \n> b/Documentation/git-commit.txt\n> index 19cbb90..bc919ac 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -190,14 +190,15 @@ OPTIONS\n> without changing its commit message.\n>\n> --amend::\n> - Used to amend the tip of the current branch. Prepare the tree\n> - object you would want to replace the latest commit as usual\n> - (this includes the usual -i/-o and explicit paths), and the\n> - commit log editor is seeded with the commit message from the\n> - tip of the current branch. The commit you create replaces the\n> - current tip -- if it was a merge, it will have the parents of\n> - the current tip as parents -- so the current top commit is\n> - discarded.\n> + Create a new commit and replace the tip of the current\n> + branch.\n\nI don't think we should say \"Create New\" at the start of the sentence,\nwhich may confuse some, rather we should start with the key\n'Replace' verb, essentially swapping the parts to say:\n\n + Replace the tip of the current branch with a fresh commit.\n[or updated commit, or new commit, or ...]\n\n> The recorded tree is prepared as usual (including\n> + the effect of the `-i` and `-o` options and explicit\n> + pathspec), and the message from the original commit is used\n> + as the starting point, instead of an empty message, when no\n> + other message is specified from the command line via options\n> + such as `-m`, `-F`, `-c`, etc. The new commit has the same\n> + parents and author as the current one (the `--reset-author`\n> + option can countermand this).\n> +\n> --\n> It is a rough equivalent for:\n>\n> --\nPhilip \n"},{"id":"213130","messageId":"1365094159.30466.60.camel@centaur.cmartin.tk","threadId":"33364","inReplyTo":"50CA4F4141DD484D97CA8BA571529F65@PhilipOakley","subject":"Re: [PATCH] Documentation/git-commit: reword the --amend explanation","fromName":"Carlos Martín Nieto","fromEmail":"cmn@elego.de","sentAt":"2013-04-04T16:49:19Z","receivedAt":"2013-04-04T16:49:19Z","isPatch":true,"sender":{"key":"cmn@elego.de","avatar":"https://avatars.githubusercontent.com/u/335443?v=4"},"body":"On Wed, 2013-04-03 at 23:25 +0100, Philip Oakley wrote:\n> Sent: Wednesday, April 03, 2013 9:04 PM\n> > Junio C Hamano writes:\n> >\n> >> Yes, and since then we gained --no-edit option and such, so \"editor\n> >> starts off\" also needs to be rethought, no? The original wording\n> >> with \"seeded\" may have a better chance of survival, I suspect, but\n> >> still needs some adjustment.\n> >\n> > So here is my attempt. We still need a sign-off from you even if we\n> > decide to use this version. Relative to your original patch:\n\n\nSorry I keep forgetting lately, it seems I've been away from core git\ntoo long.\n\nSigned-off-by: Carlos Martín Nieto \n\n> > -- >8 --\n> > From: Carlos Martín Nieto \n> >\n> > The explanation for 'git commit --amend' talks about preparing a tree\n> > object, which shouldn't be how user-facing documentation talks about\n> > commit.\n> >\n> > Reword it to say it works as usual, but replaces the current commit.\n> >\n> > ---\n> > Documentation/git-commit.txt | 17 +++++++++--------\n> > 1 file changed, 9 insertions(+), 8 deletions(-)\n> >\n> > diff --git a/Documentation/git-commit.txt \n> > b/Documentation/git-commit.txt\n> > index 19cbb90..bc919ac 100644\n> > --- a/Documentation/git-commit.txt\n> > +++ b/Documentation/git-commit.txt\n> > @@ -190,14 +190,15 @@ OPTIONS\n> > without changing its commit message.\n> >\n> > --amend::\n> > - Used to amend the tip of the current branch. Prepare the tree\n> > - object you would want to replace the latest commit as usual\n> > - (this includes the usual -i/-o and explicit paths), and the\n> > - commit log editor is seeded with the commit message from the\n> > - tip of the current branch. The commit you create replaces the\n> > - current tip -- if it was a merge, it will have the parents of\n> > - the current tip as parents -- so the current top commit is\n> > - discarded.\n> > + Create a new commit and replace the tip of the current\n> > + branch.\n> \n> I don't think we should say \"Create New\" at the start of the sentence,\n> which may confuse some, rather we should start with the key\n> 'Replace' verb, essentially swapping the parts to say:\n> \n> + Replace the tip of the current branch with a fresh commit.\n> [or updated commit, or new commit, or ...]\n\nAck, we should lead with the goal, I'd go for the\n\n \"Replace the tip of the current branch with a new commit\"\n\nwording.\n\n\n> \n> > The recorded tree is prepared as usual (including\n> > + the effect of the `-i` and `-o` options and explicit\n\nIs \"recorded tree\" what we want to say at porcelain level? I'd go for\n\"The commit\" as in my version, but maybe it's just the way I think about\nit. I don't feel too strongly about changing it, though.\n\n> > + pathspec), and the message from the original commit is used\n> > + as the starting point, instead of an empty message, when no\n> > + other message is specified from the command line via options\n> > + such as `-m`, `-F`, `-c`, etc. The new commit has the same\n> > + parents and author as the current one (the `--reset-author`\n> > + option can countermand this).\n> > +\n\nThe rest looks great.\n\n cmn\n"},{"id":"213133","messageId":"7va9pejkgt.fsf@alter.siamese.dyndns.org","threadId":"33364","inReplyTo":"1365094159.30466.60.camel@centaur.cmartin.tk","subject":"Re: [PATCH] Documentation/git-commit: reword the --amend explanation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-04T17:04:34Z","receivedAt":"2013-04-04T17:04:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Carlos Martín Nieto writes:\n\n> On Wed, 2013-04-03 at 23:25 +0100, Philip Oakley wrote:\n>\n>> + Replace the tip of the current branch with a fresh commit.\n>> [or updated commit, or new commit, or ...]\n>\n> Ack, we should lead with the goal, I'd go for the\n>\n> \"Replace the tip of the current branch with a new commit\"\n>\n> wording.\n\nWe would want to be careful to make sure that the reader understands\nthat the \"new commit\" is created by running this command (i.e. it is\nnot like \"git branch -f $current_branch $new_commit\"), but other\nthan that, sounds sensible.\n\nPerhaps like this?\n\n Documentation/git-commit.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex bc919ac..61266d8 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -190,8 +190,8 @@ OPTIONS\n \twithout changing its commit message.\n \n --amend::\n-\tCreate a new commit and replace the tip of the current\n-\tbranch. The recorded tree is prepared as usual (including\n+\tReplace the tip of the current branch by creating a new\n+\tcommit. The recorded tree is prepared as usual (including\n \tthe effect of the `-i` and `-o` options and explicit\n \tpathspec), and the message from the original commit is used\n \tas the starting point, instead of an empty message, when no\n"},{"id":"213255","messageId":"1365151805.2478.25.camel@flaca.cmartin.tk","threadId":"33364","inReplyTo":"7va9pejkgt.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-commit: reword the --amend explanation","fromName":"Carlos Martín Nieto","fromEmail":"cmn@elego.de","sentAt":"2013-04-05T08:50:05Z","receivedAt":"2013-04-05T08:50:05Z","isPatch":true,"sender":{"key":"cmn@elego.de","avatar":"https://avatars.githubusercontent.com/u/335443?v=4"},"body":"On Thu, 2013-04-04 at 10:04 -0700, Junio C Hamano wrote:\n> Carlos Martín Nieto writes:\n> \n> > On Wed, 2013-04-03 at 23:25 +0100, Philip Oakley wrote:\n> >\n> >> + Replace the tip of the current branch with a fresh commit.\n> >> [or updated commit, or new commit, or ...]\n> >\n> > Ack, we should lead with the goal, I'd go for the\n> >\n> > \"Replace the tip of the current branch with a new commit\"\n> >\n> > wording.\n> \n> We would want to be careful to make sure that the reader understands\n> that the \"new commit\" is created by running this command (i.e. it is\n> not like \"git branch -f $current_branch $new_commit\"), but other\n> than that, sounds sensible.\n> \n> Perhaps like this?\n> \n> Documentation/git-commit.txt | 4 ++--\n> 1 file changed, 2 insertions(+), 2 deletions(-)\n> \n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index bc919ac..61266d8 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -190,8 +190,8 @@ OPTIONS\n> \twithout changing its commit message.\n> \n> --amend::\n> -\tCreate a new commit and replace the tip of the current\n> -\tbranch. The recorded tree is prepared as usual (including\n> +\tReplace the tip of the current branch by creating a new\n> +\tcommit. The recorded tree is prepared as usual (including\n> \tthe effect of the `-i` and `-o` options and explicit\n> \tpathspec), and the message from the original commit is used\n> \tas the starting point, instead of an empty message, when no\n> \n\nLooks good, yeah. This should stop anybody thinking that they can\nreplace the tip with an arbitrary commit.\n\n cmn\n"}]}