Re: [PATCH 3/5] git-log.txt: fix description of <since>..<until>

Jonathan Nieder wrote:

What's so confusing about it?

commit:: As a noun: A single point in the Git history; the entire history of a project is represented as a set of interrelated commits. The word "commit" is often used by Git in the same places other revision control systems use the words "revision" or "version". Also used as a short hand for commit object.

revision:: A particular state of files and directories which was stored in the object database. It is referenced by a commit object.

-- 8< --

There a reference to "revision" in the "commit" description which might be misleading.

Otherwise, these are quite accurate. master~3:README is a valid revision, but not a commit, for instance. Another problem with the word commit is that it doesn't encapsulate ranges like 'master~3..HEAD'. It would probably help to add the terms "commitish" and "treeish" to the glossary to refer to "rev specs" (those in revisions.txt) that resolve to commits or trees. I'll give you two simple examples:

1. In 'git show master:README', master is a treeish and master:README
is a blob.  If we were to say 'git blame master: -- README', it would
error out because master: is not a commitish, but a treeish.

2. In 'git log master~3.. -- README', master~3.. is a commitish.  In
general, log can take only rev specs that resolve to a commits.
Although 'git log master:' doesn't error out, it doesn't make any
sense either.  Perhaps we should tighten it?