How to view an old revision?

How to view an old revision?

[Matt McCutchen]

Dear git people,

How do I view an old revision of a file without actually checking it
out?  This would be analogous to "cvs checkout -r <old> -p".  I've
RTMed and STWed and can't seem to find a way.

Re: How to view an old revision?

[Andy Whitcroft]

Matt McCutchen wrote:
> Dear git people,
> 
> How do I view an old revision of a file without actually checking it
> out?  This would be analogous to "cvs checkout -r <old> -p".  I've
> RTMed and STWed and can't seem to find a way.
> 

Something like the following:

	git cat-file -p <commit-ish>:<file>

For example:
	git cat-file -p tags/v1.4.3:git.c
	git cat-file -p f5f75c652b9c2347522159a87297820103e593e4:git.c

Re: How to view an old revision?

[Matt McCutchen]

On 11/1/06, Andy Whitcroft <apw@shadowen.org> wrote:
>         git cat-file -p <commit-ish>:<file>

Nice!  Thanks!  I had guessed "git cat-file -p <commit-ish>/<file>"
but didn't try a colon as the separator.  The colon syntax ought to be
mentioned in the git-cat-file man page.

Re: How to view an old revision?

[Andy Whitcroft]

Matt McCutchen wrote:
> On 11/1/06, Andy Whitcroft <apw@shadowen.org> wrote:
>>         git cat-file -p <commit-ish>:<file>
> 
> Nice!  Thanks!  I had guessed "git cat-file -p <commit-ish>/<file>"
> but didn't try a colon as the separator.  The colon syntax ought to be
> mentioned in the git-cat-file man page.

There are some improvements in the documentation in 'next' but nothing
which would make this easier for you to find.

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.

Re: How to view an old revision?

[Junio C Hamano]

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.

Re: How to view an old revision?

[Matt McCutchen]

On 11/1/06, Junio C Hamano <junkio@cox.net> wrote:
> 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.

There's no way I would have known to look in git-rev-parse.  My
git-rev-parse man page doesn't mention the colon syntax, but now I see
that part in git's gitweb; my man page must be too old.  Either (1) or
(2) would have been enough for me to figure out that the colon syntax
would do what I wanted, but to grab the attention of the less
persistent user, it would be good to mention the particular case of
"git-cat-file <commit-ish>:<file>" in the git-cat-file man page.

Re: How to view an old revision?

[Andy Whitcroft]

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 ...