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

Junio C Hamano venit, vidit, dixit 24.06.2010 22:09:

Michael J Gruber [off-list ref] writes:

quoted

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.

I'll object to the "unless"...

The comparision target of "git diff" defaults to the index, not HEAD, if
you want other precedents.

...but agree here. Do we have a logic/principle which determines whether
"empty ref" means HEAD or INDEX (which doesn't exist, of course)?

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

I'll promise to be more careful ;-)

But I still think the situation is unfortunate:

rm -Rf tt && mkdir tt && cd tt && git init
echo a >f && git add f && git commit -m a
echo b >f && git add f && git commit -m b
echo c >f && git add f && echo d >f
for c in "show --oneline f" "show --oneline :f" "diff f"; do
  echo "#git $c"
  git $c
done

produces

#git show --oneline f
3b977dc b

diff --git a/f b/f
index 7898192..6178079 100644
--- a/f
+++ b/f

@@ -1 +1 @@
-a
+b

#git show --oneline :f
c
#git diff f

diff --git i/f w/f
index f2ad6c7..4bcfe98 100644
--- i/f
+++ w/f

@@ -1 +1 @@
-c
+d

[I don't need "f" with "show" or "diff" nor "--oneline" with ":f", of
course.]

I know why it does that, but I think it's confusing that "show :f" does
not show the version of f which is the endpoint of the comparison for
the diff shown by "git show", which is the only parameter to show.

diff is different in that it really has two parameters for the two
points of comparison (which default to INDEX and WORKTREE), and by
giving one you specify the startpoint.

quoted

I was going with the usage line, but you are right: <a>:<b> makes more
sense semantically and is clearer.

quoted

What about this:

--textconv:: 
	Show the content as transformed by a textco+nv 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.

Yes. Maybe my remark was ambiguous, but from my v2 you can see what I
meant: not "on the file <path> stored in the index", but "content
recorded in the index at <path>".

Michael