Re: [PATCH] Documentation/git-commit: reword the --amend explanation
On Thu, 2013-04-04 at 10:04 -0700, Junio C Hamano wrote: > Carlos Martín Nieto 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 -- 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
Re: [PATCH] Documentation/git-commit: reword the --amend explanation
Carlos Martín Nieto 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 -- 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
Re: [PATCH] Documentation/git-commit: reword the --amend explanation
On Wed, 2013-04-03 at 23:25 +0100, Philip Oakley wrote: > Sent: Wednesday, April 03, 2013 9:04 PM > > Junio C Hamano 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 > > -- >8 -- > > From: 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. > > > > --- > > 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
Re: [PATCH] Documentation/git-commit: reword the --amend explanation
Sent: Wednesday, April 03, 2013 9:04 PM Junio C Hamano 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 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 -- 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
Re: [PATCH] Documentation/git-commit: reword the --amend explanation
Junio C Hamano 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 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: -- 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
Re: [PATCH] Documentation/git-commit: reword the --amend explanation
Carlos Martín Nieto 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: -- 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
[PATCH] Documentation/git-commit: reword the --amend explanation
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 -- 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
