Re: [PATCH] Documentation/git-commit: reword the --amend explanation
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Apr 3, 2013, 20:04 UTC
- Message-ID
- <7vtxnn4c02.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <7v4nfn7j5i.fsf@alter.siamese.dyndns.org>
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: