Re: [PATCH v1 1/3] doc: commit: --fixup/--squash can take a commit revision

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 14, 2016, 22:55 UTC
Message-ID: <xmqqbn0vj6ze.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <6ACCC850AC434350B15AADC19F02760B@PhilipOakley>

"Philip Oakley" <philipoakley@iee.org> writes:

Show 8 quoted lines

>> I think the
>> use of "commit" in an angle-bracket-pair in the label for the
>> section, i.e. "--fixup=<commit>", 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.

By "has been considered", I meant that the documentation text is still open for improvement. I just didn't find rewording "commit" with "commit revision" is that improvement we need there.

Perhaps we need to have somewhere central a section that explains various notations used in the documentation set. I think it is safe to say something like "unless otherwise qualified, <commit> (or any object type in an angle-bracket-pair) is used as a placeholder to take any acceptable way to spell object names (cf. gitrevisions for details)" these days [*1*].

[Footnote]

*1* In ancient days I think some plumbing commands only took 40-hex object names, but as far as I know they've all been updated.