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

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

[Michael J Gruber]

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.

 Documentation/git-cat-file.txt |   10 ++++++++--
 1 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index 58c8d65..da932ab 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -9,14 +9,15 @@ git-cat-file - Provide content or type and size information for repository objec
 SYNOPSIS
 --------
 [verse]
-'git cat-file' (-t | -s | -e | -p | <type>) <object>
+'git cat-file' (-t | -s | -e | -p | <type> | --textconv ) <object>
 'git cat-file' (--batch | --batch-check) < <list-of-objects>
 
 DESCRIPTION
 -----------
 In its first form, the command provides the content or the type of an object in
 the repository. The type is required unless '-t' or '-p' is used to find the
-object type, or '-s' is used to find the object size.
+object type, or '-s' is used to find the object size, or '--textconv' is used
+(which implies type "blob").
 
 In the second form, a list of objects (separated by linefeeds) is provided on
 stdin, and the SHA1, type, and size of each object is printed on stdout.
@@ -51,6 +52,11 @@ OPTIONS
 	or to ask for a "blob" with <object> being a tag object that
 	points at it.
 
+--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.
+
 --batch::
 	Print the SHA1, type, size, and contents of each object provided on
 	stdin. May not be combined with any other options or arguments.
-- 
1.7.1.621.g01d76

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

[Matthieu Moy]

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. Also, I prefer
<treeish>:<path> to <treeish:path>, to make it clear the : is actually
a :.

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.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

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

[Michael J Gruber]

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

[PATCHv2] git-cat-file.txt: Document --textconv

[Michael J Gruber]

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
v2 based on clarification by Matthieu Moy.

 Documentation/git-cat-file.txt |   10 ++++++++--
 1 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index 58c8d65..9ebbe94 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -9,14 +9,15 @@ git-cat-file - Provide content or type and size information for repository objec
 SYNOPSIS
 --------
 [verse]
-'git cat-file' (-t | -s | -e | -p | <type>) <object>
+'git cat-file' (-t | -s | -e | -p | <type> | --textconv ) <object>
 'git cat-file' (--batch | --batch-check) < <list-of-objects>
 
 DESCRIPTION
 -----------
 In its first form, the command provides the content or the type of an object in
 the repository. The type is required unless '-t' or '-p' is used to find the
-object type, or '-s' is used to find the object size.
+object type, or '-s' is used to find the object size, or '--textconv' is used
+(which implies type "blob").
 
 In the second form, a list of objects (separated by linefeeds) is provided on
 stdin, and the SHA1, type, and size of each object is printed on stdout.
@@ -51,6 +52,11 @@ OPTIONS
 	or to ask for a "blob" with <object> being a tag object that
 	points at it.
 
+--textconv::
+	Show the content as transformed by a textconv filter. In this case,
+	<object> has be of the form <treeish>:<path>, or :<path> in order
+	to apply the filter to the content recorded in the index at <path>.
+
 --batch::
 	Print the SHA1, type, size, and contents of each object provided on
 	stdin. May not be combined with any other options or arguments.
-- 
1.7.1.621.g01d76

[PATCH] git-rev-parse.txt: Document ":path" specifier

[Michael J Gruber]

The empty treeish in ":path" means "index", not "HEAD" like in probably
every other place.

Don't even try to change this, but at least document it.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 Documentation/git-rev-parse.txt |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 8db600f..f964de4 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -290,8 +290,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
   followed by something else than '!' is reserved for now.
 
 * A suffix ':' followed by a path; this names the blob or tree
-  at the given path in the tree-ish object named by the part
-  before the colon.
+  at the given path in the tree-ish object named by the ref
+  before the colon. An empty ref before ':' denotes the content
+  recorded in the index at the given path.
 
 * A colon, optionally followed by a stage number (0 to 3) and a
   colon, followed by a path; this names a blob object in the
-- 
1.7.1.621.g01d76

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

[Matthieu Moy]

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

> +--textconv::
> +	Show the content as transformed by a textconv filter. In this case,
> +	<object> has be of the form <treeish>:<path>, or :<path> in order
> +	to apply the filter to the content recorded in the index at <path>.

Good, I was not totally happy with my wording, yours is definitely
better.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

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

[Junio C Hamano]

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.

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

[Junio C Hamano]

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

> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
> v2 based on clarification by Matthieu Moy.

Looks good; thanks.

Re: [PATCH] git-rev-parse.txt: Document ":path" specifier

[Junio C Hamano]

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

> The empty treeish in ":path" means "index", not "HEAD" like in probably
> every other place.

I would suggest dropping the ', not "HEAD"... place.' part from the above.
It is more confusing than useful to the readers.  

E.g. "git diff <treeish>" compares with the named tree-ish, but "git diff"
compares with the index, even though the latter obviously lacks <treeish>
and does not default to HEAD.

The rule is more like "the index is used by default for missing value, but
with an operation that does not make sense with the index, it defaults to
the HEAD", I think.

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

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 24.06.2010 22:09:
> 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.

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.

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

[PATCHv2] git-rev-parse.txt: Document ":path" specifier

[Michael J Gruber]

The empty treeish in ":path" means "index". Document this.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 Documentation/git-rev-parse.txt |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 8db600f..f964de4 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -290,8 +290,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
   followed by something else than '!' is reserved for now.
 
 * A suffix ':' followed by a path; this names the blob or tree
-  at the given path in the tree-ish object named by the part
-  before the colon.
+  at the given path in the tree-ish object named by the ref
+  before the colon. An empty ref before ':' denotes the content
+  recorded in the index at the given path.
 
 * A colon, optionally followed by a stage number (0 to 3) and a
   colon, followed by a path; this names a blob object in the
-- 
1.7.1.621.g01d76

Re: [PATCHv2] git-rev-parse.txt: Document ":path" specifier

[Matthieu Moy]

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

> The empty treeish in ":path" means "index". Document this.
>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
>  Documentation/git-rev-parse.txt |    5 +++--
>  1 files changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
> index 8db600f..f964de4 100644
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -290,8 +290,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
>    followed by something else than '!' is reserved for now.
>  
>  * A suffix ':' followed by a path; this names the blob or tree
> -  at the given path in the tree-ish object named by the part
> -  before the colon.
> +  at the given path in the tree-ish object named by the ref
> +  before the colon. An empty ref before ':' denotes the content
> +  recorded in the index at the given path.

Actually, what you're adding is precisely what was already documented
right below:

>  * A colon, optionally followed by a stage number (0 to 3) and a
>    colon, followed by a path; this names a blob object in the
     index at the given path.  Missing stage number (and the colon
     that follows it) names a stage 0 entry. During a merge, stage
     1 is the common ancestor, stage 2 is the target branch's version
     (typically the current branch), and stage 3 is the version from
     the branch being merged.

Probably it's not obvious enough and your patch is worth it, but then
it would be less confusing if you added "(see next item)." at the end
of your sentence.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCHv2] git-rev-parse.txt: Document ":path" specifier

[Junio C Hamano]

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

> The empty treeish in ":path" means "index". Document this.
>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
>  Documentation/git-rev-parse.txt |    5 +++--
>  1 files changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
> index 8db600f..f964de4 100644
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -290,8 +290,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
>    followed by something else than '!' is reserved for now.
>  
>  * A suffix ':' followed by a path; this names the blob or tree
> -  at the given path in the tree-ish object named by the part
> -  before the colon.
> +  at the given path in the tree-ish object named by the ref
> +  before the colon. An empty ref before ':' denotes the content
> +  recorded in the index at the given path.

I am wondering if it is less confusing to present these two cases as two
independent entries...

    A colon ':' followed by a path names the blob at the given path in the
    index.

    A tree-ish, followed by a colon ':', followed by a path names the blob
    or tree at the given path  in the tree-ish.

It is not like we treat the index as a pseudo tree, but your wording
implies we do in this syntax.  We of course cannot treat the index as a
pseudo tree in all operations, and people can get confused and ask "When
can I say empty to mean index?"...

Thoughts?

Re: [PATCHv2] git-rev-parse.txt: Document ":path" specifier

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> Actually, what you're adding is precisely what was already documented
> right below:
>
>>  * A colon, optionally followed by a stage number (0 to 3) and a
>>    colon, followed by a path; this names a blob object in the
>      index at the given path.  Missing stage number (and the colon
>      that follows it) names a stage 0 entry. During a merge, stage
>      1 is the common ancestor, stage 2 is the target branch's version
>      (typically the current branch), and stage 3 is the version from
>      the branch being merged.
>
> Probably it's not obvious enough and your patch is worth it, but then
> it would be less confusing if you added "(see next item)." at the end
> of your sentence.

Another possibility is to swap the order of presentation.  It might reduce
the confusion of ':path' form appearing to be a variant of 'tree:path',
and that is what invited the "what happens when tree is an empty string"
question, I think.

[PATCHv3] git-rev-parse.txt: Document ":path" specifier

[Michael J Gruber]

The empty treeish in ":path" means "index". This is actually a special
case of the ":stage:path" syntax where it is documented, but mentioning
it also together with "treeish:path" is helpful, so do it.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
How about this? Short description at "rev:path" but still pointing
to ":stage:path".

 Documentation/git-rev-parse.txt |    4 +++-
 1 files changed, 3 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 8db600f..d525e57 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -291,7 +291,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
 
 * A suffix ':' followed by a path; this names the blob or tree
   at the given path in the tree-ish object named by the part
-  before the colon.
+  before the colon. ":path" (with an empty part before the colon)
+  is a special case of the syntax described next: content
+  recorded in the index at the given path.
 
 * A colon, optionally followed by a stage number (0 to 3) and a
   colon, followed by a path; this names a blob object in the
-- 
1.7.1.621.g01d76

Re: [PATCHv3] git-rev-parse.txt: Document ":path" specifier

[Junio C Hamano]

Thanks, will replace v2 with this versoin, but I suspect that swapping the
two bullets in the existing documentation without anything else may be a
simpler and easier-to-read alternative.

Orthogonal to this, it would probably make sense to give a simplest
example in-line in the text, i.e.

 Documentation/git-rev-parse.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 8db600f..c03f31d 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -291,12 +291,12 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
 
 * A suffix ':' followed by a path; this names the blob or tree
   at the given path in the tree-ish object named by the part
-  before the colon.
+  before the colon (e.g. "HEAD:README").
 
 * A colon, optionally followed by a stage number (0 to 3) and a
   colon, followed by a path; this names a blob object in the
-  index at the given path.  Missing stage number (and the colon
-  that follows it) names a stage 0 entry. During a merge, stage
+  index at the given path (e.g. ":0:README").  Missing stage number (and the colon
+  that follows it) names a stage 0 entry (e.g. ":README"). During a merge, stage
   1 is the common ancestor, stage 2 is the target branch's version
   (typically the current branch), and stage 3 is the version from
   the branch being merged.

Re: [PATCHv3] git-rev-parse.txt: Document ":path" specifier

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 27.06.2010 21:29:
> Thanks, will replace v2 with this versoin, but I suspect that swapping the
> two bullets in the existing documentation without anything else may be a
> simpler and easier-to-read alternative.
> 
> Orthogonal to this, it would probably make sense to give a simplest
> example in-line in the text, i.e.
> 
>  Documentation/git-rev-parse.txt |    6 +++---
>  1 files changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
> index 8db600f..c03f31d 100644
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -291,12 +291,12 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
>  
>  * A suffix ':' followed by a path; this names the blob or tree
>    at the given path in the tree-ish object named by the part
> -  before the colon.
> +  before the colon (e.g. "HEAD:README").

Yep, I think the whole discussion there is quite theoretical, often
describing symbols like slash and colon by words rather then writing
them out. That could be the topic for a more extensive rewrite. But I'm
often wondering whether git-rev-parse(1) really is the place for that,
or whether the whole revision syntax should into, say, gitrevision, to
go with gitglossary etc.

Michael

Re: [PATCHv3] git-rev-parse.txt: Document ":path" specifier

[Matthieu Moy]

Junio C Hamano <gitster@pobox.com> writes:

> Orthogonal to this, it would probably make sense to give a simplest
> example in-line in the text, i.e.

Definitely, yes.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

[PATCH] git-rev-parse.txt: Add more examples for caret and colon

[Michael J Gruber]

Several items in the caret, colon and friends section contain examples
already. Make sure they all come with examples, and that examples come
early so that they serve as a visual guide, as well.

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
This is on top of the ":path" patch to git-rev-parse.txt.

I chose not to rewrap the paragraphs so that the diff is clearer,
especially with --color-words.
I don't know what the best patch workflow guideline is here. Maybe
rewrapping a v2?

 Documentation/git-rev-parse.txt |   15 ++++++++-------
 1 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index d525e57..da5cdf4 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -256,7 +256,7 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
   the branch the ref is set to build on top of.  Missing ref defaults
   to the current branch.
 
-* A suffix '{caret}' to a revision parameter means the first parent of
+* A suffix '{caret}' to a revision parameter (e.g. "HEAD^") means the first parent of
   that commit object.  '{caret}<n>' means the <n>th parent (i.e.
   'rev{caret}'
   is equivalent to 'rev{caret}1').  As a special rule,
@@ -282,23 +282,24 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
   and dereference the tag recursively until a non-tag object is
   found.
 
-* A colon, followed by a slash, followed by a text: this names
+* A colon, followed by a slash, followed by a text (e.g. ":/fix nasty bug"): this names
   a commit whose commit message starts with the specified text.
   This name returns the youngest matching commit which is
   reachable from any ref.  If the commit message starts with a
   '!', you have to repeat that;  the special sequence ':/!',
   followed by something else than '!' is reserved for now.
 
-* A suffix ':' followed by a path; this names the blob or tree
+* A suffix ':' followed by a path (e.g. "HEAD:README"); this names the blob or tree
   at the given path in the tree-ish object named by the part
-  before the colon. ":path" (with an empty part before the colon)
+  before the colon.
+  ":path" (with an empty part before the colon, e.g. ":README")
   is a special case of the syntax described next: content
   recorded in the index at the given path.
 
 * A colon, optionally followed by a stage number (0 to 3) and a
-  colon, followed by a path; this names a blob object in the
-  index at the given path.  Missing stage number (and the colon
-  that follows it) names a stage 0 entry. During a merge, stage
+  colon, followed by a path (e.g. ":0:README"); this names a blob object in the
+  index at the given path. Missing stage number (and the colon
+  that follows it, e.g. ":README") names a stage 0 entry. During a merge, stage
   1 is the common ancestor, stage 2 is the target branch's version
   (typically the current branch), and stage 3 is the version from
   the branch being merged.
-- 
1.7.1.621.g01d76

RE: [PATCH] git-rev-parse.txt: Add more examples for caret and colon

[Peter Kjellerstedt]

> -----Original Message-----
> From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On
> Behalf Of Michael J Gruber
> Sent: den 28 juni 2010 10:18
> To: git@vger.kernel.org
> Cc: Junio C Hamano; Matthieu Moy
> Subject: [PATCH] git-rev-parse.txt: Add more examples for caret and
> colon
> 
> Several items in the caret, colon and friends section contain examples
> already. Make sure they all come with examples, and that examples come
> early so that they serve as a visual guide, as well.
> 
> Suggested-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
> This is on top of the ":path" patch to git-rev-parse.txt.
> 
> I chose not to rewrap the paragraphs so that the diff is clearer,
> especially with --color-words.
> I don't know what the best patch workflow guideline is here. Maybe
> rewrapping a v2?
> 
>  Documentation/git-rev-parse.txt |   15 ++++++++-------
>  1 files changed, 8 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-
> parse.txt
> index d525e57..da5cdf4 100644
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -256,7 +256,7 @@ the `$GIT_DIR/refs` directory or from the
> `$GIT_DIR/packed-refs` file.
>    the branch the ref is set to build on top of.  Missing ref defaults
>    to the current branch.
> 
> -* A suffix '{caret}' to a revision parameter means the first parent of
> +* A suffix '{caret}' to a revision parameter (e.g. "HEAD^") means the first parent of

Shouldn't that be

* A suffix '{caret}' to a revision parameter (e.g. `HEAD{caret}`) means the first parent of

for consistency?

>    that commit object.  '{caret}<n>' means the <n>th parent (i.e.
>    'rev{caret}'
>    is equivalent to 'rev{caret}1').  As a special rule,
> @@ -282,23 +282,24 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
>    and dereference the tag recursively until a non-tag object is
>    found.
> 
> -* A colon, followed by a slash, followed by a text: this names
> +* A colon, followed by a slash, followed by a text (e.g. ":/fix nasty bug"): this names

Most examples in this file seem to use `` rather than "".

>    a commit whose commit message starts with the specified text.
>    This name returns the youngest matching commit which is
>    reachable from any ref.  If the commit message starts with a
>    '!', you have to repeat that;  the special sequence ':/!',
>    followed by something else than '!' is reserved for now.
> 
> -* A suffix ':' followed by a path; this names the blob or tree
> +* A suffix ':' followed by a path (e.g. "HEAD:README"); this names the blob or tree
>    at the given path in the tree-ish object named by the part
> -  before the colon. ":path" (with an empty part before the colon)
> +  before the colon.
> +  ":path" (with an empty part before the colon, e.g. ":README")
>    is a special case of the syntax described next: content
>    recorded in the index at the given path.
> 
>  * A colon, optionally followed by a stage number (0 to 3) and a
> -  colon, followed by a path; this names a blob object in the
> -  index at the given path.  Missing stage number (and the colon
> -  that follows it) names a stage 0 entry. During a merge, stage
> +  colon, followed by a path (e.g. ":0:README"); this names a blob object in the
> +  index at the given path. Missing stage number (and the colon
> +  that follows it, e.g. ":README") names a stage 0 entry. During a merge, stage
>    1 is the common ancestor, stage 2 is the target branch's version
>    (typically the current branch), and stage 3 is the version from
>    the branch being merged.
> --
> 1.7.1.621.g01d76

I tried to find a document describing documentation standards for 
git (i.e., something similar to Documentation/CodingGuidelines),
but could not find any such document. Did I just miss it, or does
it not exist?

//Peter

Re: [PATCH] git-rev-parse.txt: Add more examples for caret and colon

[Michael J Gruber]

Peter Kjellerstedt venit, vidit, dixit 28.06.2010 12:03:
>> -----Original Message-----
>> From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On
>> Behalf Of Michael J Gruber
>> Sent: den 28 juni 2010 10:18
>> To: git@vger.kernel.org
>> Cc: Junio C Hamano; Matthieu Moy
>> Subject: [PATCH] git-rev-parse.txt: Add more examples for caret and
>> colon
>>
>> Several items in the caret, colon and friends section contain examples
>> already. Make sure they all come with examples, and that examples come
>> early so that they serve as a visual guide, as well.
>>
>> Suggested-by: Junio C Hamano <gitster@pobox.com>
>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
>> ---
>> This is on top of the ":path" patch to git-rev-parse.txt.
>>
>> I chose not to rewrap the paragraphs so that the diff is clearer,
>> especially with --color-words.
>> I don't know what the best patch workflow guideline is here. Maybe
>> rewrapping a v2?
>>
>>  Documentation/git-rev-parse.txt |   15 ++++++++-------
>>  1 files changed, 8 insertions(+), 7 deletions(-)
>>
>> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-
>> parse.txt
>> index d525e57..da5cdf4 100644
>> --- a/Documentation/git-rev-parse.txt
>> +++ b/Documentation/git-rev-parse.txt
>> @@ -256,7 +256,7 @@ the `$GIT_DIR/refs` directory or from the
>> `$GIT_DIR/packed-refs` file.
>>    the branch the ref is set to build on top of.  Missing ref defaults
>>    to the current branch.
>>
>> -* A suffix '{caret}' to a revision parameter means the first parent of
>> +* A suffix '{caret}' to a revision parameter (e.g. "HEAD^") means the first parent of
> 
> Shouldn't that be
> 
> * A suffix '{caret}' to a revision parameter (e.g. `HEAD{caret}`) means the first parent of
> 
> for consistency?

Both of them render the same with my asciidoc. I don't mind making it
consistent.

~ and ^ are dangerous with asciidoc 8, but we compile with
asciidoc7compatible, so this is a non-issue.

> 
>>    that commit object.  '{caret}<n>' means the <n>th parent (i.e.
>>    'rev{caret}'
>>    is equivalent to 'rev{caret}1').  As a special rule,
>> @@ -282,23 +282,24 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
>>    and dereference the tag recursively until a non-tag object is
>>    found.
>>
>> -* A colon, followed by a slash, followed by a text: this names
>> +* A colon, followed by a slash, followed by a text (e.g. ":/fix nasty bug"): this names
> 
> Most examples in this file seem to use `` rather than "".

I did not do the statistics, many use `, many use ', and many use ".
The first two often render in the same way.

> 
>>    a commit whose commit message starts with the specified text.
>>    This name returns the youngest matching commit which is
>>    reachable from any ref.  If the commit message starts with a
>>    '!', you have to repeat that;  the special sequence ':/!',
>>    followed by something else than '!' is reserved for now.
>>
>> -* A suffix ':' followed by a path; this names the blob or tree
>> +* A suffix ':' followed by a path (e.g. "HEAD:README"); this names the blob or tree
>>    at the given path in the tree-ish object named by the part
>> -  before the colon. ":path" (with an empty part before the colon)
>> +  before the colon.
>> +  ":path" (with an empty part before the colon, e.g. ":README")
>>    is a special case of the syntax described next: content
>>    recorded in the index at the given path.
>>
>>  * A colon, optionally followed by a stage number (0 to 3) and a
>> -  colon, followed by a path; this names a blob object in the
>> -  index at the given path.  Missing stage number (and the colon
>> -  that follows it) names a stage 0 entry. During a merge, stage
>> +  colon, followed by a path (e.g. ":0:README"); this names a blob object in the
>> +  index at the given path. Missing stage number (and the colon
>> +  that follows it, e.g. ":README") names a stage 0 entry. During a merge, stage
>>    1 is the common ancestor, stage 2 is the target branch's version
>>    (typically the current branch), and stage 3 is the version from
>>    the branch being merged.
>> --
>> 1.7.1.621.g01d76
> 
> I tried to find a document describing documentation standards for 
> git (i.e., something similar to Documentation/CodingGuidelines),
> but could not find any such document. Did I just miss it, or does
> it not exist?

Ironically, I have tried to suggest something like that, together with a
series of patches implementing that. Feel free to try again ;)

As a general practical rule, I think we try to stay "locally
consistent", i.e. within the surrounding context.

For current asciidoc:
'foo' is emphasized
`foo` is monospaced and literal (not expanded)
`foo' is enclosed in single quotation marks
``foo'' is enclosed in double quotation marks

(In fact, for us `foo` is not foo because we compile with
no-inline-literal to shut off asciidoc 8.4 changes for inline literals.)

Michael

[PATCHv2] git-rev-parse.txt: Add more examples for caret and colon

[Michael J Gruber]

Several items in the caret, colon and friends section contain examples
already. Make sure they all come with examples, and that examples come
early so that they serve as a visual guide, as well.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
This is on top of the ":path" patch to git-rev-parse.txt.

I chose not to rewrap the paragraphs so that the diff is clearer,
especially with --color-words.

v3 now has the quoting style consistent at least locally (and the caret
spelled out), although the existing text changes style midway.

This is about as far as I will go with a "minimal change" patch trying
to alleviate the :something confusion. I really think the whole part
needs an overhaul not only to make it consistent, so bikeshedding before
that is pointless ;)

 Documentation/git-rev-parse.txt |   15 ++++++++-------
 1 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index d525e57..833a2a2 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -256,7 +256,7 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
   the branch the ref is set to build on top of.  Missing ref defaults
   to the current branch.
 
-* A suffix '{caret}' to a revision parameter means the first parent of
+* A suffix '{caret}' to a revision parameter (e.g. 'HEAD{caret}') means the first parent of
   that commit object.  '{caret}<n>' means the <n>th parent (i.e.
   'rev{caret}'
   is equivalent to 'rev{caret}1').  As a special rule,
@@ -282,23 +282,24 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
   and dereference the tag recursively until a non-tag object is
   found.
 
-* A colon, followed by a slash, followed by a text: this names
+* A colon, followed by a slash, followed by a text (e.g. `:/fix nasty bug`): this names
   a commit whose commit message starts with the specified text.
   This name returns the youngest matching commit which is
   reachable from any ref.  If the commit message starts with a
   '!', you have to repeat that;  the special sequence ':/!',
   followed by something else than '!' is reserved for now.
 
-* A suffix ':' followed by a path; this names the blob or tree
+* A suffix ':' followed by a path (e.g. `HEAD:README`); this names the blob or tree
   at the given path in the tree-ish object named by the part
-  before the colon. ":path" (with an empty part before the colon)
+  before the colon.
+  ':path' (with an empty part before the colon, e.g. `:README`)
   is a special case of the syntax described next: content
   recorded in the index at the given path.
 
 * A colon, optionally followed by a stage number (0 to 3) and a
-  colon, followed by a path; this names a blob object in the
-  index at the given path.  Missing stage number (and the colon
-  that follows it) names a stage 0 entry. During a merge, stage
+  colon, followed by a path (e.g. `:0:README`); this names a blob object in the
+  index at the given path. Missing stage number (and the colon
+  that follows it, e.g. `:README`) names a stage 0 entry. During a merge, stage
   1 is the common ancestor, stage 2 is the target branch's version
   (typically the current branch), and stage 3 is the version from
   the branch being merged.
-- 
1.7.1.621.g01d76