Andy Whitcroft <apw@xxxxxxxxxxxx> writes:
> Junio, I wonder if we should be changing the usage for this command
> slightly. Currently, it mearly says <object> as the identifier for the
> blob. Really this is <object-ish> as it supports symbolic naming in
> addition to raw sha1's. I also feel it would be very helpful if
> <commit-ish> and family were documented as a glossary section in main
> git manpage.
>
> Something like this:
>
> <commit-ish>:: is an sha1 for a commit, or any symbolic name for a
> commit (see SPECIFYING REVISIONS in git-rev-parse)
>
> What do people think. I can do the munging about if its seems like a
> sane plan.
When we really want an object of type <x>, we accept an object
that is not of type <x> if there is a natural and unique
dereferencing of that object to the type <x>. We use word
<x-ish> to describe such an object that dereferences to <x>.
For example, ls-tree is about listing tree contents (so we want
a tree), but we accept a commit because the natural and unique
dereferencing of a commit to a tree is to take its (toplevel)
tree. We also accept a tag pointing at a commit because we can
dereference it to the commit and then to its tree. Hence a tag
that points at either commit or a tree, and a commit are
tree-ish.
<object> is an object which can be <commit>, <tree>, <tag> or
<blob>. There is nothing -ish about it.
I was actually reviewing the documentation of git-rev-parse and
noticed that it talks about naming objects in the section called
"SPECIFYING REVISIONS". The title implies that it is about
committish (because we think of "revisions" as something that is
used in walking commit ancestry chains), but it actually talks
about naming objects of any type.
It is a good and comprehensive list when viewed as "list of ways
you can name an object", but both the title and the page the
list appears in put unfair emphasis of commits for that purpose,
and it is hard to realize that what you learned there applies to
naming any type of objects. It is even harder to guess the list
appears on that page, unless you are the one who is actively involved
in the git list, when you want to know which manual page to look
at in order to find out how you name an arbitrary object.
We could either
(1) retitle the list and move it to git.txt (Symbolic
Identifiers), and refer to it from pages that describe
commands that take object names;
(2) retitle the list and make it an includable snippet, similar
to the way Documentation/diff-format.txt is used from pages
that describe diff commands, and include it everywhere.
I am slightly in favor of the latter. Although it has a bloat
factor in the generated documentation, docs are not novels and
not meant to be read from cover to cover, and duplicating
relevant information on each page is more useful than refering
the reader to jump around in the documentation set.
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html