From: Junio C Hamano <gitster@pobox.com>
Date: Sun, 14 Aug 2016 22:55:33 GMT
Subject: Re: [PATCH v1 1/3] doc: commit: --fixup/--squash can take a commit revision
Message-ID: <xmqqbn0vj6ze.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <6ACCC850AC434350B15AADC19F02760B@PhilipOakley>

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

>> 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.