Re: How to view an old revision?

[Andy Whitcroft <apw@shadowen.org>]

Junio C Hamano wrote:
> Andy Whitcroft <apw@shadowen.org> 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 ...