Re: [PATCH 4/5] git-log.txt: rewrite note on why "--" may be required

[Junio C Hamano <gitster@pobox.com>]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Ramkumar Ramachandra wrote:
>
>>                       I would say the most technically accurate
>> description of what 'git log' takes is a "committish range" (basically
>> a "revision range" that resolves to commits).
>
> What is a revision range that doesn't resolve to commits?  Am I wrong
> in thinking revision is nothing more than a synonym for commit?
>
> When gitrevisions(7) says "A revision parameter <rev> typically, but
> not necessarily, names a commit object", I suspect it is residue from
> 3a45f625 trying to apologize for the extended SHA1 syntax parser being
> called "git rev-parse" instead of "git object-name-parse".

 - A revision range is a slice of history.  There is no need for
   "committish revision range" as there is no other kinds of ranges.

 - A revision should be a synonym to a committish, as glossary
   defines.  We historically used "revision" more or less
   interchangeably with "object name", especially "an extended SHA-1
   expression that is used as an object name", to mean whatever
   get_sha1() can grok down to a single object name.  This must be
   rectified to avoid causing confusion to new readers of our
   documentation.

 - Documentation/revisions.txt needs to be cleaned up.  It lists
   "specifying revisions" and "specifying ranges", which is a good
   start primarily because some notations used in ranges are not
   revisions (e.g. "^C"), but it should have three (not two) sections.

   They are: "specifying revisions", "specifying object names", and
   "specifying ranges".  Move non committish specification such as
   <revision>:<path> from the current "specifying revisions" section
   and make the new "object names" section.  The "ranges" section is
   already written in terms of revisions, and does not need any
   update, once we clarify the definition of a "revision" as
   "committish".