How do get a specific version of a particular file?

So given a particular tree-ish and a pathname, I'd like get the contents of that particular file as of a particular revision. i.e., the equivalent of:

	cvs -r v1.37 -p e2fsck/pass1.c
or
	bk cat -r 2345 e2fsck/pass1.c

The closest I've been able to come is to use

	git archive --format=zip v1.37 e2fsck/pass1.c | gunzip

But that seems kinda silly.  

git-checkout will only write the output to the working tree. git-cat-file and git-show only work on a object identifier (they are low-level plumbing commands).

So if it is a matter of we don't have an easy way to do this (as opposed to me being stupid or the git documentation just failing to mention it in the right places), what's the best way to add it?

One easy way would be to add --format=raw to git-archive, but that might seem counter-intuitive to an average git user; they just want to see the output of a file at a particular point in time, which doesn't have much to do with archiving.

Should we add a new command like "git-cat"? Should we add a -p option to the "git-checkout <treeish> <path>" form of git-checkout?

I'm currently leaning towards the last; it would be pretty simple to enhance git-checkout so that a -p option would run "git archive --format=zip ...", even though that would be a pretty nasty hack, and it wouldn't be much harder to add --format=raw support to git-archive, but I still think that's not a intuitive place to find that particular functionality.

						- Ted

quoting Linus:

Well, you can just add

       [alias]
               cat=-p cat-file -p

to your ~/.gitconfig file, and you're there.

[ For all the non-git people here: the first "-p" is shorthand for
 "--paginate", and means that git will automatically start a pager for
 the output. The second "-p" is shorthand for "pretty" (there's no
 long-format command line switch for it, though), and means that git
 cat-file will show the result in a human-readable way, regardless of
 whether it's just a text-file, or a git directory ]

So then you can do just

       git cat todo:TODO

and you're done.

[ So for the non-git people, what that will actually _do_ is to show the
 TODO file in the "todo" branch - regardless of whether it is checked out
 or not, and start a pager for you. ]

I actually do this sometimes, but I've never done it for branches (and I do it seldom enough that I haven't added the alias). I do it for things like

       git cat v2.6.16:Makefile

Theodore Ts'o <tytso@mit.edu> schrieb:

You you could do this with

	git show v1.5.0:Makefile

to show you the Makefile in revision v1.5.0.

-Peter

On 2/27/07, Theodore Ts'o <tytso@mit.edu> wrote:

git cat-file -p <objname>:file

I.e.: git cat-file v1.37:e2fsck/pass1.c

On 2/27/07, Alex Riesen <raa.lkml@gmail.com> wrote:

Err... With -p (for pretty).

  git cat-file -p v1.37:e2fsck/pass1.c

This outputs just the file, not prettifying, actually.

Btw, for broken OS (and not to be named broken workarounds for the broken OS') we probably need "-o <output-file>". I forget what it was, but something used to mangle pipes on windows.

Hi,

On Tue, 27 Feb 2007, Theodore Ts'o wrote:

git-show, of all, is _not_ plumbing. It is one of the foremost porcelain programs core Git ships.

git show v.37:e2fsck/pass1.c

Is probably what you want.

Ciao, Dscho

On Tue, Feb 27, 2007 at 01:57:18PM +0100, Johannes Schindelin wrote:

Maybe, but its man page doesn't show it. The average end-user isn't going to be thinking about blobs, tree objects, and tag objects. Furthermore, the EXAMPLES section in the man page is misformatted due to some ASCII doc issues. I'll send a patch to correct the EXAMPLES section, but if git-show is a foremost porecelain program the DISCRIPTION section probably needs to be rewritten as well.

Thanks, I just didn't know about tree-ish:pathname syntax, and I've been playing with git for a while.

As a suggestion, maybe we should be moving (or at least copying) things like the <object> identifier syntax from the git-rev-parse manpage (which is plumbing, right?) to the top-level git manpage? I don't think it's a good idea to force users to read man pages for plumbing commands in order to learn key git command-line concepts.

						- Ted

Hi,

On Tue, 27 Feb 2007, Theodore Tso wrote:

Thank you for the patch.

Since you seem to be no old-timer who cannot remember how she learnt about certain Git concepts: What documentation did you read, an in which order? This might help us making the parts likely to be seen by new users better...

My vote is for moving, and referencing (kind of mv && ln -s).

But that means that you have to explain in a really concise way that Git repositories contain blob, tree, commit and tag objects. And what they are.

Ciao, Dscho

On Tue, Feb 27, 2007 at 08:55:41PM +0100, Johannes Schindelin wrote:

I started using Everyday git, and the git(7) man page, and the tutorials. I tried using some of the git manpages, but many of them were so inpenetrable that I would just skip over that bit and hope the rest of the man page would make sense or would just try searching somewhere for the information. To be honest, some of the best documentation was Linus's email messages on the git mailing list, especially the ones about git philosophy and examples about how to do things.

For example, the man page of git-rev-parse will give you a very dry description of ".." and "...", but absolutely no examples of when you would you might use one or the other. The only place where I learned about this was from some of Linus's e-mail messages, and even then I'm still a little shaky on when you might use '...'.

And I'm still not sure why

	git show v1.5.0..v1.5.0.1 

doesn't throw an error, and why it prints what it does...

Well, git(7) already has an extraordinary verbose description of glob, tree, commit, and tag options, so if we move the object id syntax to git(7) that wouldn't be a problem. :-)

						- Ted

Theodore> And I'm still not sure why

Theodore> 	git show v1.5.0..v1.5.0.1 

Theodore> doesn't throw an error, and why it prints what it does...

Wait, that doesn't throw an error?

(tries it)

OK, how is that different from git-diff ?

/me scratches head

merlyn@stonehenge.com (Randal L. Schwartz) writes:

I do not think there is any difference. "show" is about multiple points, not ranges. "diff" is about multiple (typically two) points, and not ranges.

On Tue, 27 Feb 2007, Junio C Hamano wrote:

Well, I do think Ted has a good point. Having negative refs makes no sense for the "no-walk" case (aka "git show").

So when we do

	git show v1.4.4..v1.5.0

that's an illogical thing to do, since "git show" is defined to be a non-revision-walking action, which means the range operator be pointless and wrong. The fact that we happily accept it (and then _only_ show v1.5.0, which is the positive end of the range) is quite arguably not very logical.

We should complain, and say that you can only do "no_walk" with positive refs. Negative object refs really don't make any sense unless you walk the obejct list (or you're "git diff" and know about ranges explicitly).

Something like this (although I don't know if my message is necessarily the best possible one).

		Linus

---

Linus Torvalds <torvalds@linux-foundation.org> writes:

If you did not say "(or you're..." part, then I would agree to this 100%.

On the other hand, as you earlier said:

    On Fri, 22 Dec 2006,...
    > 
    > I can understand the advantage of a shortcut like "git diff ..next",
    > ...

    I can't understand why people complain about this.

    YOU DON'T HAVE TO USE IT. 
    ...
    > But, really, I still don't understand exactly _what_ "diff a..b" even
    > means. Can you explain it to me?

    It means exactly the same as "diff a b".

    It's that simple.

which made me lol, I am very tempted to say:

	It means exactly the same as "show a b".

        It's that simple.

Back to serious my self, I am wondering if this is a sensible thing to ask:

	$ git show master...maint

which your patch now forbids.

Hi,

On Tue, 27 Feb 2007, Junio C Hamano wrote:

git diff does not set revs->no_walk, so the patch would not trigger for git-diff.

Ciao, Dscho

On Tue, 27 Feb 2007, Junio C Hamano wrote:

Well, I personally see (and think) of ".." as a "difference operator".

It very much is that, both for "git diff" and for "git log".

It's just that the "differences" are different.

In "git diff", the difference is obviously the code difference. When you say "git diff a..b" to "show the difference between a and b", you mean "show the patch". When you say "git log a..b", it's *still* a "difference", but now it's the *set* difference of the commits.

But "a..b" makes sense to me in both cases, exactly because to me, "a..b" _literally_ means "b - a" or "the difference between a and b".

Maybe I'm odd, or maybe it's because I have a fairly strong math background, but I have no trouble at all with a "difference operator" that does different things.

In real algebra (what in the US is apparently called "abstract algebra", and not to be confused with just "arithmetic with unknowns"), you do generalized arithmetic operations, and using "+" and "-" and "*" to mean arbitrary things that depend on the stuff you operate on, and doing different things depending on whether you talk about a "set of commits" (log) or talking about a "set of source code" (diff), makes total sense mathematically.

No, it really makes no sense at all if you see "a..b" as being a "difference operator".

What is the difference between two commits? It's either the difference in code (diff) _or_ it's the difference in sets of commits (log), and either is logical, but which one should "git show" actually show?

In NO CASE is it logical to say that "git show a..b" makes the "difference" be the "union" of two commits. That's just confusing and odd.

Again, what would that *mean*?

The "..." operator is the "symmetric difference". It has meaning both for code and for commit sets, but which one is "show"?

		Linus

On Tue, 27 Feb 2007, Linus Torvalds wrote:

/me wonders why Linux wasn't written in C++ with overloaded operators...

Nicolas

On Tue, 27 Feb 2007, Nicolas Pitre wrote:

Actually, there was a short while that we tried it.

In the end, we ended up using the C pre-processor (and some gcc hackery) instead, since it's just superior to the mess that is C++.

See "<asm/uaccess.h>" and various other header files, and realize that we have overloaded operations for things like "get_user()" and "xchg()" and friends.

Overloading of operators wouldn't be very useful, though: it really only pays in either real math (where having "+" etc do the right thing for complex numbers/vectors/matrices/whatever is totally unambiguous and just makes code a lot more readable) or with really trivial stuff (ie "+" for string concatenation).

Outside of math and really trivial stuff, it's just a horribly bad idea, because it just makes for subtle and hard to understand code.

Same largely goes for overloading of functions too, for that matter, except for the cases where you really can pretty much do it by argument size (and then the C preprocessor and few gcc extensions actually generate better and more readable code than C++ ever did - which is admittedly not saying a whole lot).

		Linus

On Tue, 27 Feb 2007, Linus Torvalds wrote:

I know.  Amusing piece of history.

Well... We could have >> and << to replace memcpy(), copy_to_user(), copy_from_user(), and select the appropriate method depending on whether one is a user space pointer.

Or spin_lock++ and spin_lock--.

Or written_data >> file >> filesystem, replacing all fops methods with operators as well.

;-)

Indeed. Well it can make the intent of the code clearer but certainly not its implementation.

Nicolas

On Tue, Feb 27, 2007 at 04:31:47PM -0800, Junio C Hamano wrote:

Well, the other design alternative is to make git-show take a list of objects, so that

	git show v1.5.0..v1.5.0.1

ends up displaying the same thing as

	git show `git-rev-list v1.5.0..v1.5.0.1`

... but I'm not really convinced that's really all that useful.  

Also, at the moment the git-show man page states the following:

       <object>
              The name of the object to show. For a more complete list of ways
              to spell object names, see  "SPECIFYING  REVISIONS"  section  in
              git-rev-parse(1).

Note the use of singular. That would imply that it takes a single object, and not a range of objects. Of course, if the above behavior were actually shown to be useful, man pages can always be easily changed. :-)

						- Ted

Theodore Tso <tytso@mit.edu> writes:

I think we are better off doing "git show v1.5.0..v1.5.0.1" for that, but we do take multiple objects.

I find myself running "git show --stat v1.X.Y v1.X.Y+1" every time I tag a new release Y+2 to find out things like:

	* Should I say "Git v1.5.1" or "GIT 1.5.1"?
	* Ah, I have to update GIT-VERSION-GEN, which I did, good.

On Tue, Feb 27, 2007 at 06:45:41PM -0800, Junio C Hamano wrote:

Not sure I understand what you mean?  That:

	git show v1.5.0..v1.5.0.1

should should show all the commits between v1.5.0 and v1.5.0.1, or just print the commit corresponding to v1.5.0.1 (and the v1.5.0 is completely meaningless?)

But why not just type:

	git show --stat v1.X.Y+1

instead?  Or if you don't want the tag information, you could type:

	git show --stat v1.X.Y+1^{commit}

since 

	git show --stat v1.5.0..v1.5.0.1
and
	git show --stat v1.4.4.0..v1.5.0.1
and
	git show --stat v1.0.0..v1.5.0.1

all print exactly the same thing!  

Hence Linus's and my argument that as currently implemented the ".." operator to git doesn't make a lot of sense....

						- Ted

Theodore Tso <tytso@mit.edu> writes:

I don't either.

I thought I was writing "git log v1.5.0..v1.5.0.1".

Sorry for the confusion.

On Tue, 27 Feb 2007, Linus Torvalds wrote:

It could be improved a little.

What about "a single object specification only must be provided" instead?

Nicolas

Hi,

On Tue, 27 Feb 2007, Randal L. Schwartz wrote:

	$ git diff v1.5.0..v1.5.0.1

shows the differences between those two versions;

	$ git show v1.5.0..v1.5.0.1

is _identical_ to

	$ git show v1.5.0 v1.5.0.1

and shows the same as

	$ git show v1.5.0; git show v1.5.0.1

i.e. the commit diffs of both commits.

Ciao, Dscho

On Wed, 28 Feb 2007, Johannes Schindelin wrote:

No, it's not.

Try it.

For one thing, the ".." format makes no sense with something that doesn't actually walk the range (it _does_ make sense for "diff", because while it doesn't "walk the range", it does show the _result_ of walking that the range - "diff" really is special, since by definition it's about end-poits).

For another, "git show" actually uses "cmd_log_walk()" for showing commits, which in turn uses get_revision(), which in turn will _ignore_ any commit that you've marked uninteresting.

So it will *not* show the commit that is v1.5.0.

So I agree with Ted: "git show" as it is now is not logical with commit ranges. I sent out a patch that I think at least makes it sensible, although I'm not claiming that it's necessarily the only way to handle it.

		Linus

Linus Torvalds <torvalds@linux-foundation.org> writes:

Ah, sorry, I missed that part.

Hi,

On Tue, 27 Feb 2007, Linus Torvalds wrote:

My fault. Crossed eyes...

Ciao, Dscho

Fix asciidoc markup so that the man page is properly formatted in the EXAMPLES section.

Signed-off-by: "Theodore Ts'o" <tytso@mit.edu>
---
 Documentation/git-show.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

On Tue, 27 Feb 2007, Theodore Ts'o wrote:

Everybody has already pointed out how easy this actually is, but your fundamental mistake was thinking that "only work on a object identifier" is a bad thing.

Repeat after me: in git, *everything* is a SHA1 object!

So the problem you had was that "only". Remove the "only", and realize that object identifiers will cover _all_ you ever need, and be happy.

That's why

	git show <tree>:<path>

works. All the files are *also* just SHA1 objects, and as a result all the normal SHA1 naming rules apply.

This is also why you can literally do

	git diff v1.4.4:Makefile HEAD~5:Makefile

and it will just magically work and do exactly what the command line would make you think it does - even if you didn't know anything at all about git.

Because "git diff" knows about blob objects too, and "v1.3:Makefile" is the object name for the blob that was the Makefile object at version 1.4.4, and HEAD~5:Makefile is the Makefile in the fifth parent of your current HEAD.

Tell me any other SCM that makes things quite _that_ easy?

So in Unix, we have "everything is a file" (and then we have processes). In git, we have "everything is a SHA1-named object" (and then we have revision walking). There's a really simple underlying logic to it all, and the great thing is how _powerful_ it is.

THIS is what good design is all about. Forget nipples. You just need to internalize the fact that "everything is a SHA1".

So not only do we have it, it's probably not mentioned in the docs because it is *so* fundamental that nobody even thought to mention any of this except in the "how does SHA1 lookup work" sections.

			Linus

On Tuesday, February 27, 2007 at 08:38:59 (-0800) Linus Torvalds writes:

Nipples?  Is this a Windows construct?

Bill

On Tue, Feb 27, 2007 at 08:38:59AM -0800, Linus Torvalds wrote:

Yeah, the problem was that in the git man pages I had read, and the git tutorials that I had read, I had never learned about the <tree>:<path> syntax of object identifiers. So this was more of a documentation problem than anything else --- I did look and trawlled through the documentation for quite a while before posting because I didn't want to look stupid, and I still didn't find it.

						- Ted

On Tue, 27 Feb 2007, Theodore Tso wrote:

It's there in git-rev-parse.txt (which explains all the SHA1 object "math"), but yeah, it's not exactly obvious, and all the examples tend to use just the "commit relationship" math, not the commit->tree->path rules.

		Linus