From: Philip Oakley Date: Sun, 14 Aug 2016 22:45:37 GMT Subject: Re: [PATCH v1 1/3] doc: commit: --fixup/--squash can take a commit revision Message-ID: <6ACCC850AC434350B15AADC19F02760B@PhilipOakley> In-Reply-To: From: "Junio C Hamano" > Philip Oakley writes: >> Be clearer that the --fixup/--squash options can take any of the >> gitrevisions methods of specifying a commit, not just a 'hash'. >> >> Signed-off-by: Philip Oakley >> --- >> ... >> @@ -81,15 +81,15 @@ OPTIONS >> --fixup=:: >> Construct a commit message for use with `rebase --autosquash`. >> The commit message will be the subject line from the specified >> - commit with a prefix of "fixup! ". See linkgit:git-rebase[1] >> - for details. >> + commit revision with a prefix of "fixup! ". See linkgit:git-rebase[1] >> + and linkgit:gitrevisions[7] for details. > > The same comment applies to the other hunk, but rephrasing "commit" > with "commit revision" (the latter is not even in the glossary) does > not make it clearer at all. Especially when discussing rebases and > anything that rewrites commits, it can easily be mistaken as if you > are talking about v2 of the commit by fixing up the original, but > that is not the impression you want to give. Hmm, had to read that a few times before I saw what you meant regarding 'v2' as the revised commit. > > "The specified commit" is clear enough. It may be debatable if we > want to talk about "how" to specify the commit, though. Exactly. The latter. > I think the > use of "commit" in an angle-bracket-pair in the label for the > section, i.e. "--fixup=", has been considered to be clear > enough to tell that you can use usual extended SHA-1 syntax to > specify the commit you want to talk about, I certainly hadn't picked up on that ability to use the extended sha1 syntax (specifying revisions...) here. Part of the issue is that the whole fixup/squash capability is buried within just two documents as asides [1], and in the place it's spelt out (in rebase) it talks about the commit message being used, which is just part of the confusion. > but if so, that is not > limited to this entry, and I do not think this description or the > other one for the "--squash" option are particularly worse than > those for the "-c" and "-C" options. The description for "-c" does > say "Take an existing commit object", but that's like "the specified > commit" used here. > OK -- Philip [1] just looked at the new Progit version and fixup/squash is not even mentioned.