Re: [PATCH] git-cat-file.txt: Document --textconv

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 24, 2010, 20:09 UTC
Message-ID: <7vocf0chwa.fsf@alter.siamese.dyndns.org>
In-Reply-To: <4C2355EF.7030604@drmicha.warpmail.net>

Michael J Gruber <git@drmicha.warpmail.net> writes:

Show 8 quoted lines

> Wait a minute:
>
> git show HEAD:path >a
> git show :path >b
> diff a b
>
> Oh no! We've been having this all along. This is bad but probably
> unchangeable.

There is nothing "bad" about this, unless you forgot about the index. The comparision target of "git diff" defaults to the index, not HEAD, if you want other precedents.

If you kept telling others that "everything defaults to HEAD", it is indeed bad, but that can be fixed ;-).

Show 11 quoted lines

> I was going with the usage line, but you are right: <a>:<b> makes more
> sense semantically and is clearer.
>> 
>> What about this:
>> 
>> --textconv:: 
>> 	Show the content as transformed by a textconv filter. In this
>> 	case, <object> has be of the form <treeish>:<path>, or :<path>
>> 	to run the filter on the file <path> stored in the index.
>
> I'll be more mathematically stubborn about "file", see v2;)

If you want to be mathematically stubborn, then I think you should prefer <path> in a context like this, since <treeish>:<path> is the notation to reach to a <blob> inside the treeish. <file> is merely one of the two possible manifestations of <blob> when it is accessed through the tree that immediately contains it (other being <symlink>).

Most importantly, "cat-file blob <blob>" codepath has nothing to do with that "should this <blob> materialize as a <file> or a <symlink>?" logic, so saying <file> is doubly wrong in this context.