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

[Junio C Hamano <gitster@pobox.com>]

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

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

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