Junio C Hamano wrote: > 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. I'll take a stab at this ... -apw - 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