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

[Michael J Gruber <git@drmicha.warpmail.net>]

Matthieu Moy venit, vidit, dixit 24.06.2010 13:53:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
>> ---
>> This formulation is based on my understanding that you can't cat-file
>>  --textconv something in the index or worktree.
> 
> Actually, you can't textconv from the worktree, but you can from the
> index, saying
> 
> git cat-file --textconv :path/to/file
> 
> (the :<path> syntax is not specific here, you can use it in other Git
> commands)
> 
>> +--textconv::
>> +	Show the content as transformed by a textconv filter. In this case,
>> +	<object> has be of the form <treeish:path>, with treeish defaulting to
>> +	HEAD.
> 
> So the "defaulting to HEAD" is incorrect. 

Oh no, this is bad! I'd say every git command defaults to HEAD when a
commitish/treeish is not specified!!

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.

> Also, I prefer
> <treeish>:<path> to <treeish:path>, to make it clear the : is actually
> a :.

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

Michael