* [PATCH] git-cat-file.txt: Document --textconv @ 2010-06-24 10:14 Michael J Gruber 2010-06-24 11:53 ` Matthieu Moy 0 siblings, 1 reply; 22+ messages in thread From: Michael J Gruber @ 2010-06-24 10:14 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Clément Poulain, Diane Gasselin, Axel Bonnet 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 ^ permalink raw reply related [flat|nested] 22+ messages in thread
* Re: [PATCH] git-cat-file.txt: Document --textconv 2010-06-24 10:14 [PATCH] git-cat-file.txt: Document --textconv Michael J Gruber @ 2010-06-24 11:53 ` Matthieu Moy 2010-06-24 12:56 ` Michael J Gruber 0 siblings, 1 reply; 22+ messages in thread From: Matthieu Moy @ 2010-06-24 11:53 UTC (permalink / raw) To: Michael J Gruber Cc: git, Junio C Hamano, Clément Poulain, Diane Gasselin, Axel Bonnet 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/ ^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH] git-cat-file.txt: Document --textconv 2010-06-24 11:53 ` Matthieu Moy @ 2010-06-24 12:56 ` Michael J Gruber 2010-06-24 12:56 ` [PATCHv2] " Michael J Gruber ` (2 more replies) 0 siblings, 3 replies; 22+ messages in thread From: Michael J Gruber @ 2010-06-24 12:56 UTC (permalink / raw) To: Matthieu Moy Cc: git, Junio C Hamano, Clément Poulain, Diane Gasselin, Axel Bonnet 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 ^ permalink raw reply [flat|nested] 22+ messages in thread
* [PATCHv2] git-cat-file.txt: Document --textconv 2010-06-24 12:56 ` Michael J Gruber @ 2010-06-24 12:56 ` Michael J Gruber 2010-06-24 13:54 ` Matthieu Moy 2010-06-24 20:10 ` Junio C Hamano 2010-06-24 13:02 ` [PATCH] git-rev-parse.txt: Document ":path" specifier Michael J Gruber 2010-06-24 20:09 ` [PATCH] git-cat-file.txt: Document --textconv Junio C Hamano 2 siblings, 2 replies; 22+ messages in thread From: Michael J Gruber @ 2010-06-24 12:56 UTC (permalink / raw) To: git Cc: Junio C Hamano, Matthieu Moy, Clément Poulain, Diane Gasselin, Axel Bonnet 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 ^ permalink raw reply related [flat|nested] 22+ messages in thread
* Re: [PATCHv2] git-cat-file.txt: Document --textconv 2010-06-24 12:56 ` [PATCHv2] " Michael J Gruber @ 2010-06-24 13:54 ` Matthieu Moy 2010-06-24 20:10 ` Junio C Hamano 1 sibling, 0 replies; 22+ messages in thread From: Matthieu Moy @ 2010-06-24 13:54 UTC (permalink / raw) To: Michael J Gruber Cc: git, Junio C Hamano, Clément Poulain, Diane Gasselin, Axel Bonnet 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/ ^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCHv2] git-cat-file.txt: Document --textconv 2010-06-24 12:56 ` [PATCHv2] " Michael J Gruber 2010-06-24 13:54 ` Matthieu Moy @ 2010-06-24 20:10 ` Junio C Hamano 1 sibling, 0 replies; 22+ messages in thread From: Junio C Hamano @ 2010-06-24 20:10 UTC (permalink / raw) To: Michael J Gruber Cc: git, Matthieu Moy, Clément Poulain, Diane Gasselin, Axel Bonnet 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. ^ permalink raw reply [flat|nested] 22+ messages in thread
* [PATCH] git-rev-parse.txt: Document ":path" specifier 2010-06-24 12:56 ` Michael J Gruber 2010-06-24 12:56 ` [PATCHv2] " Michael J Gruber @ 2010-06-24 13:02 ` Michael J Gruber 2010-06-24 20:47 ` Junio C Hamano 2010-06-24 20:09 ` [PATCH] git-cat-file.txt: Document --textconv Junio C Hamano 2 siblings, 1 reply; 22+ messages in thread From: Michael J Gruber @ 2010-06-24 13:02 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Matthieu Moy 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 ^ permalink raw reply related [flat|nested] 22+ messages in thread
* Re: [PATCH] git-rev-parse.txt: Document ":path" specifier 2010-06-24 13:02 ` [PATCH] git-rev-parse.txt: Document ":path" specifier Michael J Gruber @ 2010-06-24 20:47 ` Junio C Hamano 2010-06-25 14:32 ` [PATCHv2] " Michael J Gruber 0 siblings, 1 reply; 22+ messages in thread From: Junio C Hamano @ 2010-06-24 20:47 UTC (permalink / raw) To: Michael J Gruber; +Cc: git, Matthieu Moy 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. ^ permalink raw reply [flat|nested] 22+ messages in thread
* [PATCHv2] git-rev-parse.txt: Document ":path" specifier 2010-06-24 20:47 ` Junio C Hamano @ 2010-06-25 14:32 ` Michael J Gruber 2010-06-25 15:25 ` Matthieu Moy 2010-06-25 15:53 ` [PATCHv2] git-rev-parse.txt: Document ":path" specifier Junio C Hamano 0 siblings, 2 replies; 22+ messages in thread From: Michael J Gruber @ 2010-06-25 14:32 UTC (permalink / raw) To: git; +Cc: Junio C Hamano 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 ^ permalink raw reply related [flat|nested] 22+ messages in thread
* Re: [PATCHv2] git-rev-parse.txt: Document ":path" specifier 2010-06-25 14:32 ` [PATCHv2] " Michael J Gruber @ 2010-06-25 15:25 ` Matthieu Moy 2010-06-25 17:52 ` Junio C Hamano 2010-06-25 15:53 ` [PATCHv2] git-rev-parse.txt: Document ":path" specifier Junio C Hamano 1 sibling, 1 reply; 22+ messages in thread From: Matthieu Moy @ 2010-06-25 15:25 UTC (permalink / raw) To: Michael J Gruber; +Cc: git, 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. 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/ ^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCHv2] git-rev-parse.txt: Document ":path" specifier 2010-06-25 15:25 ` Matthieu Moy @ 2010-06-25 17:52 ` Junio C Hamano 2010-06-27 13:15 ` [PATCHv3] " Michael J Gruber 0 siblings, 1 reply; 22+ messages in thread From: Junio C Hamano @ 2010-06-25 17:52 UTC (permalink / raw) To: Matthieu Moy; +Cc: Michael J Gruber, git 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. ^ permalink raw reply [flat|nested] 22+ messages in thread
* [PATCHv3] git-rev-parse.txt: Document ":path" specifier 2010-06-25 17:52 ` Junio C Hamano @ 2010-06-27 13:15 ` Michael J Gruber 2010-06-27 19:29 ` Junio C Hamano 0 siblings, 1 reply; 22+ messages in thread From: Michael J Gruber @ 2010-06-27 13:15 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Matthieu Moy 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 ^ permalink raw reply related [flat|nested] 22+ messages in thread
* Re: [PATCHv3] git-rev-parse.txt: Document ":path" specifier 2010-06-27 13:15 ` [PATCHv3] " Michael J Gruber @ 2010-06-27 19:29 ` Junio C Hamano 2010-06-27 19:41 ` Michael J Gruber ` (2 more replies) 0 siblings, 3 replies; 22+ messages in thread From: Junio C Hamano @ 2010-06-27 19:29 UTC (permalink / raw) To: Michael J Gruber; +Cc: git, Matthieu Moy 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. ^ permalink raw reply related [flat|nested] 22+ messages in thread
* Re: [PATCHv3] git-rev-parse.txt: Document ":path" specifier 2010-06-27 19:29 ` Junio C Hamano @ 2010-06-27 19:41 ` Michael J Gruber 2010-06-28 6:22 ` Matthieu Moy 2010-06-28 8:18 ` [PATCH] git-rev-parse.txt: Add more examples for caret and colon Michael J Gruber 2 siblings, 0 replies; 22+ messages in thread From: Michael J Gruber @ 2010-06-27 19:41 UTC (permalink / raw) To: Junio C Hamano; +Cc: git, Matthieu Moy 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 ^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCHv3] git-rev-parse.txt: Document ":path" specifier 2010-06-27 19:29 ` Junio C Hamano 2010-06-27 19:41 ` Michael J Gruber @ 2010-06-28 6:22 ` Matthieu Moy 2010-06-28 8:18 ` [PATCH] git-rev-parse.txt: Add more examples for caret and colon Michael J Gruber 2 siblings, 0 replies; 22+ messages in thread From: Matthieu Moy @ 2010-06-28 6:22 UTC (permalink / raw) To: Junio C Hamano; +Cc: Michael J Gruber, git 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/ ^ permalink raw reply [flat|nested] 22+ messages in thread
* [PATCH] git-rev-parse.txt: Add more examples for caret and colon 2010-06-27 19:29 ` Junio C Hamano 2010-06-27 19:41 ` Michael J Gruber 2010-06-28 6:22 ` Matthieu Moy @ 2010-06-28 8:18 ` Michael J Gruber 2010-06-28 10:03 ` Peter Kjellerstedt 2 siblings, 1 reply; 22+ messages in thread From: Michael J Gruber @ 2010-06-28 8:18 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Matthieu Moy 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 ^ permalink raw reply related [flat|nested] 22+ messages in thread
* RE: [PATCH] git-rev-parse.txt: Add more examples for caret and colon 2010-06-28 8:18 ` [PATCH] git-rev-parse.txt: Add more examples for caret and colon Michael J Gruber @ 2010-06-28 10:03 ` Peter Kjellerstedt 2010-06-28 10:27 ` Michael J Gruber 0 siblings, 1 reply; 22+ messages in thread From: Peter Kjellerstedt @ 2010-06-28 10:03 UTC (permalink / raw) To: Michael J Gruber, git; +Cc: Junio C Hamano, Matthieu Moy > -----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 ^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH] git-rev-parse.txt: Add more examples for caret and colon 2010-06-28 10:03 ` Peter Kjellerstedt @ 2010-06-28 10:27 ` Michael J Gruber 2010-06-28 19:01 ` [PATCHv2] " Michael J Gruber 0 siblings, 1 reply; 22+ messages in thread From: Michael J Gruber @ 2010-06-28 10:27 UTC (permalink / raw) To: Peter Kjellerstedt; +Cc: git, Junio C Hamano, Matthieu Moy 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 ^ permalink raw reply [flat|nested] 22+ messages in thread
* [PATCHv2] git-rev-parse.txt: Add more examples for caret and colon 2010-06-28 10:27 ` Michael J Gruber @ 2010-06-28 19:01 ` Michael J Gruber 0 siblings, 0 replies; 22+ messages in thread From: Michael J Gruber @ 2010-06-28 19:01 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Matthieu Moy, Peter Kjellerstedt 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 ^ permalink raw reply related [flat|nested] 22+ messages in thread
* Re: [PATCHv2] git-rev-parse.txt: Document ":path" specifier 2010-06-25 14:32 ` [PATCHv2] " Michael J Gruber 2010-06-25 15:25 ` Matthieu Moy @ 2010-06-25 15:53 ` Junio C Hamano 1 sibling, 0 replies; 22+ messages in thread From: Junio C Hamano @ 2010-06-25 15:53 UTC (permalink / raw) To: Michael J Gruber; +Cc: git 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? ^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH] git-cat-file.txt: Document --textconv 2010-06-24 12:56 ` Michael J Gruber 2010-06-24 12:56 ` [PATCHv2] " Michael J Gruber 2010-06-24 13:02 ` [PATCH] git-rev-parse.txt: Document ":path" specifier Michael J Gruber @ 2010-06-24 20:09 ` Junio C Hamano 2010-06-25 9:04 ` Michael J Gruber 2 siblings, 1 reply; 22+ messages in thread From: Junio C Hamano @ 2010-06-24 20:09 UTC (permalink / raw) To: Michael J Gruber Cc: Matthieu Moy, git, Clément Poulain, Diane Gasselin, Axel Bonnet 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. ^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH] git-cat-file.txt: Document --textconv 2010-06-24 20:09 ` [PATCH] git-cat-file.txt: Document --textconv Junio C Hamano @ 2010-06-25 9:04 ` Michael J Gruber 0 siblings, 0 replies; 22+ messages in thread From: Michael J Gruber @ 2010-06-25 9:04 UTC (permalink / raw) To: Junio C Hamano Cc: Matthieu Moy, git, Clément Poulain, Diane Gasselin, Axel Bonnet 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 ^ permalink raw reply related [flat|nested] 22+ messages in thread
end of thread, other threads:[~2010-06-28 19:01 UTC | newest] Thread overview: 22+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2010-06-24 10:14 [PATCH] git-cat-file.txt: Document --textconv Michael J Gruber 2010-06-24 11:53 ` Matthieu Moy 2010-06-24 12:56 ` Michael J Gruber 2010-06-24 12:56 ` [PATCHv2] " Michael J Gruber 2010-06-24 13:54 ` Matthieu Moy 2010-06-24 20:10 ` Junio C Hamano 2010-06-24 13:02 ` [PATCH] git-rev-parse.txt: Document ":path" specifier Michael J Gruber 2010-06-24 20:47 ` Junio C Hamano 2010-06-25 14:32 ` [PATCHv2] " Michael J Gruber 2010-06-25 15:25 ` Matthieu Moy 2010-06-25 17:52 ` Junio C Hamano 2010-06-27 13:15 ` [PATCHv3] " Michael J Gruber 2010-06-27 19:29 ` Junio C Hamano 2010-06-27 19:41 ` Michael J Gruber 2010-06-28 6:22 ` Matthieu Moy 2010-06-28 8:18 ` [PATCH] git-rev-parse.txt: Add more examples for caret and colon Michael J Gruber 2010-06-28 10:03 ` Peter Kjellerstedt 2010-06-28 10:27 ` Michael J Gruber 2010-06-28 19:01 ` [PATCHv2] " Michael J Gruber 2010-06-25 15:53 ` [PATCHv2] git-rev-parse.txt: Document ":path" specifier Junio C Hamano 2010-06-24 20:09 ` [PATCH] git-cat-file.txt: Document --textconv Junio C Hamano 2010-06-25 9:04 ` Michael J Gruber
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.