Sent: Wednesday, April 03, 2013 9:04 PM
Junio C Hamano <gitster@xxxxxxxxx> 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@xxxxxxxx>
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 majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html