{"thread":{"id":"24184","subject":"[PATCH] git-cat-file.txt: Document --textconv","startedAt":"2010-06-24T10:14:49Z","lastAt":"2010-06-28T19:01:07Z","messageCount":22,"participants":["Michael J Gruber","Matthieu Moy","Junio C Hamano","Peter Kjellerstedt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"144128","messageId":"2251bbc1e40505dcb80103bf5daebea07dc0e9f7.1277374210.git.git@drmicha.warpmail.net","threadId":"24184","inReplyTo":null,"subject":"[PATCH] git-cat-file.txt: Document --textconv","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-06-24T10:14:49Z","receivedAt":"2010-06-24T10:14:49Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n---\nThis formulation is based on my understanding that you can't cat-file\n --textconv something in the index or worktree.\n\n Documentation/git-cat-file.txt |   10 ++++++++--\n 1 files changed, 8 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\nindex 58c8d65..da932ab 100644\n--- a/Documentation/git-cat-file.txt\n+++ b/Documentation/git-cat-file.txt\n@@ -9,14 +9,15 @@ git-cat-file - Provide content or type and size information for repository objec\n SYNOPSIS\n --------\n [verse]\n-'git cat-file' (-t | -s | -e | -p | <type>) <object>\n+'git cat-file' (-t | -s | -e | -p | <type> | --textconv ) <object>\n 'git cat-file' (--batch | --batch-check) < <list-of-objects>\n \n DESCRIPTION\n -----------\n In its first form, the command provides the content or the type of an object in\n the repository. The type is required unless '-t' or '-p' is used to find the\n-object type, or '-s' is used to find the object size.\n+object type, or '-s' is used to find the object size, or '--textconv' is used\n+(which implies type \"blob\").\n \n In the second form, a list of objects (separated by linefeeds) is provided on\n stdin, and the SHA1, type, and size of each object is printed on stdout.\n@@ -51,6 +52,11 @@ OPTIONS\n \tor to ask for a \"blob\" with <object> being a tag object that\n \tpoints at it.\n \n+--textconv::\n+\tShow the content as transformed by a textconv filter. In this case,\n+\t<object> has be of the form <treeish:path>, with treeish defaulting to\n+\tHEAD.\n+\n --batch::\n \tPrint the SHA1, type, size, and contents of each object provided on\n \tstdin. May not be combined with any other options or arguments.\n-- \n1.7.1.621.g01d76\n"},{"id":"144143","messageId":"vpqmxukir3e.fsf@bauges.imag.fr","threadId":"24184","inReplyTo":"2251bbc1e40505dcb80103bf5daebea07dc0e9f7.1277374210.git.git@drmicha.warpmail.net","subject":"Re: [PATCH] git-cat-file.txt: Document --textconv","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-06-24T11:53:57Z","receivedAt":"2010-06-24T11:53:57Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Michael J Gruber <git@drmicha.warpmail.net> writes:\n\n> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n> ---\n> This formulation is based on my understanding that you can't cat-file\n>  --textconv something in the index or worktree.\n\nActually, you can't textconv from the worktree, but you can from the\nindex, saying\n\ngit cat-file --textconv :path/to/file\n\n(the :<path> syntax is not specific here, you can use it in other Git\ncommands)\n\n> +--textconv::\n> +\tShow the content as transformed by a textconv filter. In this case,\n> +\t<object> has be of the form <treeish:path>, with treeish defaulting to\n> +\tHEAD.\n\nSo the \"defaulting to HEAD\" is incorrect. Also, I prefer\n<treeish>:<path> to <treeish:path>, to make it clear the : is actually\na :.\n\nWhat about this:\n\n--textconv:: \n\tShow the content as transformed by a textconv filter. In this\n\tcase, <object> has be of the form <treeish>:<path>, or :<path>\n\tto run the filter on the file <path> stored in the index.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"144146","messageId":"4C2355EF.7030604@drmicha.warpmail.net","threadId":"24184","inReplyTo":"vpqmxukir3e.fsf@bauges.imag.fr","subject":"Re: [PATCH] git-cat-file.txt: Document --textconv","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-06-24T12:56:15Z","receivedAt":"2010-06-24T12:56:15Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Matthieu Moy venit, vidit, dixit 24.06.2010 13:53:\n> Michael J Gruber <git@drmicha.warpmail.net> writes:\n> \n>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n>> ---\n>> This formulation is based on my understanding that you can't cat-file\n>>  --textconv something in the index or worktree.\n> \n> Actually, you can't textconv from the worktree, but you can from the\n> index, saying\n> \n> git cat-file --textconv :path/to/file\n> \n> (the :<path> syntax is not specific here, you can use it in other Git\n> commands)\n> \n>> +--textconv::\n>> +\tShow the content as transformed by a textconv filter. In this case,\n>> +\t<object> has be of the form <treeish:path>, with treeish defaulting to\n>> +\tHEAD.\n> \n> So the \"defaulting to HEAD\" is incorrect. \n\nOh no, this is bad! I'd say every git command defaults to HEAD when a\ncommitish/treeish is not specified!!\n\nWait a minute:\n\ngit show HEAD:path >a\ngit show :path >b\ndiff a b\n\nOh no! We've been having this all along. This is bad but probably\nunchangeable.\n\n> Also, I prefer\n> <treeish>:<path> to <treeish:path>, to make it clear the : is actually\n> a :.\n\nI was going with the usage line, but you are right: <a>:<b> makes more\nsense semantically and is clearer.\n\n> \n> What about this:\n> \n> --textconv:: \n> \tShow the content as transformed by a textconv filter. In this\n> \tcase, <object> has be of the form <treeish>:<path>, or :<path>\n> \tto run the filter on the file <path> stored in the index.\n> \n\nI'll be more mathematically stubborn about \"file\", see v2;)\n\nMichael\n"},{"id":"144147","messageId":"735c21d857407c7f0cb18da13d556d3a77a358db.1277383590.git.git@drmicha.warpmail.net","threadId":"24184","inReplyTo":"4C2355EF.7030604@drmicha.warpmail.net","subject":"[PATCHv2] git-cat-file.txt: Document --textconv","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-06-24T12:56:55Z","receivedAt":"2010-06-24T12:56:55Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n---\nv2 based on clarification by Matthieu Moy.\n\n Documentation/git-cat-file.txt |   10 ++++++++--\n 1 files changed, 8 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\nindex 58c8d65..9ebbe94 100644\n--- a/Documentation/git-cat-file.txt\n+++ b/Documentation/git-cat-file.txt\n@@ -9,14 +9,15 @@ git-cat-file - Provide content or type and size information for repository objec\n SYNOPSIS\n --------\n [verse]\n-'git cat-file' (-t | -s | -e | -p | <type>) <object>\n+'git cat-file' (-t | -s | -e | -p | <type> | --textconv ) <object>\n 'git cat-file' (--batch | --batch-check) < <list-of-objects>\n \n DESCRIPTION\n -----------\n In its first form, the command provides the content or the type of an object in\n the repository. The type is required unless '-t' or '-p' is used to find the\n-object type, or '-s' is used to find the object size.\n+object type, or '-s' is used to find the object size, or '--textconv' is used\n+(which implies type \"blob\").\n \n In the second form, a list of objects (separated by linefeeds) is provided on\n stdin, and the SHA1, type, and size of each object is printed on stdout.\n@@ -51,6 +52,11 @@ OPTIONS\n \tor to ask for a \"blob\" with <object> being a tag object that\n \tpoints at it.\n \n+--textconv::\n+\tShow the content as transformed by a textconv filter. In this case,\n+\t<object> has be of the form <treeish>:<path>, or :<path> in order\n+\tto apply the filter to the content recorded in the index at <path>.\n+\n --batch::\n \tPrint the SHA1, type, size, and contents of each object provided on\n \tstdin. May not be combined with any other options or arguments.\n-- \n1.7.1.621.g01d76\n"},{"id":"144148","messageId":"2f6ddf1fa551acf6074140865fbc2940ab45ed83.1277384506.git.git@drmicha.warpmail.net","threadId":"24184","inReplyTo":"4C2355EF.7030604@drmicha.warpmail.net","subject":"[PATCH] git-rev-parse.txt: Document \":path\" specifier","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-06-24T13:02:27Z","receivedAt":"2010-06-24T13:02:27Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"The empty treeish in \":path\" means \"index\", not \"HEAD\" like in probably\nevery other place.\n\nDon't even try to change this, but at least document it.\n\nSigned-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n---\n Documentation/git-rev-parse.txt |    5 +++--\n 1 files changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex 8db600f..f964de4 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -290,8 +290,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n   followed by something else than '!' is reserved for now.\n \n * A suffix ':' followed by a path; this names the blob or tree\n-  at the given path in the tree-ish object named by the part\n-  before the colon.\n+  at the given path in the tree-ish object named by the ref\n+  before the colon. An empty ref before ':' denotes the content\n+  recorded in the index at the given path.\n \n * A colon, optionally followed by a stage number (0 to 3) and a\n   colon, followed by a path; this names a blob object in the\n-- \n1.7.1.621.g01d76\n"},{"id":"144153","messageId":"vpqd3vgcz9h.fsf@bauges.imag.fr","threadId":"24184","inReplyTo":"735c21d857407c7f0cb18da13d556d3a77a358db.1277383590.git.git@drmicha.warpmail.net","subject":"Re: [PATCHv2] git-cat-file.txt: Document --textconv","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-06-24T13:54:02Z","receivedAt":"2010-06-24T13:54:02Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Michael J Gruber <git@drmicha.warpmail.net> writes:\n\n> +--textconv::\n> +\tShow the content as transformed by a textconv filter. In this case,\n> +\t<object> has be of the form <treeish>:<path>, or :<path> in order\n> +\tto apply the filter to the content recorded in the index at <path>.\n\nGood, I was not totally happy with my wording, yours is definitely\nbetter.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"144189","messageId":"7vocf0chwa.fsf@alter.siamese.dyndns.org","threadId":"24184","inReplyTo":"4C2355EF.7030604@drmicha.warpmail.net","subject":"Re: [PATCH] git-cat-file.txt: Document --textconv","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-06-24T20:09:09Z","receivedAt":"2010-06-24T20:09:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber <git@drmicha.warpmail.net> writes:\n\n> Wait a minute:\n>\n> git show HEAD:path >a\n> git show :path >b\n> diff a b\n>\n> Oh no! We've been having this all along. This is bad but probably\n> unchangeable.\n\nThere is nothing \"bad\" about this, unless you forgot about the index.\nThe comparision target of \"git diff\" defaults to the index, not HEAD, if\nyou want other precedents.\n\nIf you kept telling others that \"everything defaults to HEAD\", it is\nindeed bad, but that can be fixed ;-).\n\n> I was going with the usage line, but you are right: <a>:<b> makes more\n> sense semantically and is clearer.\n>> \n>> What about this:\n>> \n>> --textconv:: \n>> \tShow the content as transformed by a textconv filter. In this\n>> \tcase, <object> has be of the form <treeish>:<path>, or :<path>\n>> \tto run the filter on the file <path> stored in the index.\n>\n> I'll be more mathematically stubborn about \"file\", see v2;)\n\nIf you want to be mathematically stubborn, then I think you should prefer\n<path> in a context like this, since <treeish>:<path> is the notation to\nreach to a <blob> inside the treeish.  <file> is merely one of the two\npossible manifestations of <blob> when it is accessed through the tree\nthat immediately contains it (other being <symlink>).\n\nMost importantly, \"cat-file blob <blob>\" codepath has nothing to do with\nthat \"should this <blob> materialize as a <file> or a <symlink>?\" logic,\nso saying <file> is doubly wrong in this context.\n"},{"id":"144190","messageId":"7vk4pochuo.fsf@alter.siamese.dyndns.org","threadId":"24184","inReplyTo":"735c21d857407c7f0cb18da13d556d3a77a358db.1277383590.git.git@drmicha.warpmail.net","subject":"Re: [PATCHv2] git-cat-file.txt: Document --textconv","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-06-24T20:10:07Z","receivedAt":"2010-06-24T20:10:07Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber <git@drmicha.warpmail.net> writes:\n\n> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n> ---\n> v2 based on clarification by Matthieu Moy.\n\nLooks good; thanks.\n"},{"id":"144204","messageId":"7vvd98b1jh.fsf@alter.siamese.dyndns.org","threadId":"24184","inReplyTo":"2f6ddf1fa551acf6074140865fbc2940ab45ed83.1277384506.git.git@drmicha.warpmail.net","subject":"Re: [PATCH] git-rev-parse.txt: Document \":path\" specifier","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-06-24T20:47:46Z","receivedAt":"2010-06-24T20:47:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber <git@drmicha.warpmail.net> writes:\n\n> The empty treeish in \":path\" means \"index\", not \"HEAD\" like in probably\n> every other place.\n\nI would suggest dropping the ', not \"HEAD\"... place.' part from the above.\nIt is more confusing than useful to the readers.  \n\nE.g. \"git diff <treeish>\" compares with the named tree-ish, but \"git diff\"\ncompares with the index, even though the latter obviously lacks <treeish>\nand does not default to HEAD.\n\nThe rule is more like \"the index is used by default for missing value, but\nwith an operation that does not make sense with the index, it defaults to\nthe HEAD\", I think.\n"},{"id":"144232","messageId":"4C24710A.7000506@drmicha.warpmail.net","threadId":"24184","inReplyTo":"7vocf0chwa.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] git-cat-file.txt: Document --textconv","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-06-25T09:04:10Z","receivedAt":"2010-06-25T09:04:10Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Junio C Hamano venit, vidit, dixit 24.06.2010 22:09:\n> Michael J Gruber <git@drmicha.warpmail.net> writes:\n> \n>> Wait a minute:\n>>\n>> git show HEAD:path >a\n>> git show :path >b\n>> diff a b\n>>\n>> Oh no! We've been having this all along. This is bad but probably\n>> unchangeable.\n> \n> There is nothing \"bad\" about this, unless you forgot about the index.\n\nI'll object to the \"unless\"...\n\n> The comparision target of \"git diff\" defaults to the index, not HEAD, if\n> you want other precedents.\n\n...but agree here. Do we have a logic/principle which determines whether\n\"empty ref\" means HEAD or INDEX (which doesn't exist, of course)?\n\n> \n> If you kept telling others that \"everything defaults to HEAD\", it is\n> indeed bad, but that can be fixed ;-).\n\nI'll promise to be more careful ;-)\n\nBut I still think the situation is unfortunate:\n\nrm -Rf tt && mkdir tt && cd tt && git init\necho a >f && git add f && git commit -m a\necho b >f && git add f && git commit -m b\necho c >f && git add f && echo d >f\nfor c in \"show --oneline f\" \"show --oneline :f\" \"diff f\"; do\n  echo \"#git $c\"\n  git $c\ndone\n\nproduces\n\n#git show --oneline f\n3b977dc b\ndiff --git a/f b/f\nindex 7898192..6178079 100644\n--- a/f\n+++ b/f\n@@ -1 +1 @@\n-a\n+b\n#git show --oneline :f\nc\n#git diff f\ndiff --git i/f w/f\nindex f2ad6c7..4bcfe98 100644\n--- i/f\n+++ w/f\n@@ -1 +1 @@\n-c\n+d\n\n[I don't need \"f\" with \"show\" or \"diff\" nor \"--oneline\" with \":f\", of\ncourse.]\n\nI know why it does that, but I think it's confusing that \"show :f\" does\nnot show the version of f which is the endpoint of the comparison for\nthe diff shown by \"git show\", which is the only parameter to show.\n\ndiff is different in that it really has two parameters for the two\npoints of comparison (which default to INDEX and WORKTREE), and by\ngiving one you specify the startpoint.\n\n> \n>> I was going with the usage line, but you are right: <a>:<b> makes more\n>> sense semantically and is clearer.\n>>>\n>>> What about this:\n>>>\n>>> --textconv:: \n>>> \tShow the content as transformed by a textco+nv filter. In this\n>>> \tcase, <object> has be of the form <treeish>:<path>, or :<path>\n>>> \tto run the filter on the file <path> stored in the index.\n>>\n>> I'll be more mathematically stubborn about \"file\", see v2;)\n> \n> If you want to be mathematically stubborn, then I think you should prefer\n> <path> in a context like this, since <treeish>:<path> is the notation to\n> reach to a <blob> inside the treeish.  <file> is merely one of the two\n> possible manifestations of <blob> when it is accessed through the tree\n> that immediately contains it (other being <symlink>).\n> \n> Most importantly, \"cat-file blob <blob>\" codepath has nothing to do with\n> that \"should this <blob> materialize as a <file> or a <symlink>?\" logic,\n> so saying <file> is doubly wrong in this context.\n\nYes. Maybe my remark was ambiguous, but from my v2 you can see what I\nmeant: not \"on the file <path> stored in the index\", but \"content\nrecorded in the index at <path>\".\n\nMichael\n"},{"id":"144245","messageId":"633f42d1967049780d66cf72552b22ae17bbbead.1277476258.git.git@drmicha.warpmail.net","threadId":"24184","inReplyTo":"7vvd98b1jh.fsf@alter.siamese.dyndns.org","subject":"[PATCHv2] git-rev-parse.txt: Document \":path\" specifier","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-06-25T14:32:16Z","receivedAt":"2010-06-25T14:32:16Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"The empty treeish in \":path\" means \"index\". Document this.\n\nSigned-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n---\n Documentation/git-rev-parse.txt |    5 +++--\n 1 files changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex 8db600f..f964de4 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -290,8 +290,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n   followed by something else than '!' is reserved for now.\n \n * A suffix ':' followed by a path; this names the blob or tree\n-  at the given path in the tree-ish object named by the part\n-  before the colon.\n+  at the given path in the tree-ish object named by the ref\n+  before the colon. An empty ref before ':' denotes the content\n+  recorded in the index at the given path.\n \n * A colon, optionally followed by a stage number (0 to 3) and a\n   colon, followed by a path; this names a blob object in the\n-- \n1.7.1.621.g01d76\n"},{"id":"144250","messageId":"vpqvd97rv5q.fsf@bauges.imag.fr","threadId":"24184","inReplyTo":"633f42d1967049780d66cf72552b22ae17bbbead.1277476258.git.git@drmicha.warpmail.net","subject":"Re: [PATCHv2] git-rev-parse.txt: Document \":path\" specifier","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-06-25T15:25:53Z","receivedAt":"2010-06-25T15:25:53Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Michael J Gruber <git@drmicha.warpmail.net> writes:\n\n> The empty treeish in \":path\" means \"index\". Document this.\n>\n> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n> ---\n>  Documentation/git-rev-parse.txt |    5 +++--\n>  1 files changed, 3 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\n> index 8db600f..f964de4 100644\n> --- a/Documentation/git-rev-parse.txt\n> +++ b/Documentation/git-rev-parse.txt\n> @@ -290,8 +290,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n>    followed by something else than '!' is reserved for now.\n>  \n>  * A suffix ':' followed by a path; this names the blob or tree\n> -  at the given path in the tree-ish object named by the part\n> -  before the colon.\n> +  at the given path in the tree-ish object named by the ref\n> +  before the colon. An empty ref before ':' denotes the content\n> +  recorded in the index at the given path.\n\nActually, what you're adding is precisely what was already documented\nright below:\n\n>  * A colon, optionally followed by a stage number (0 to 3) and a\n>    colon, followed by a path; this names a blob object in the\n     index at the given path.  Missing stage number (and the colon\n     that follows it) names a stage 0 entry. During a merge, stage\n     1 is the common ancestor, stage 2 is the target branch's version\n     (typically the current branch), and stage 3 is the version from\n     the branch being merged.\n\nProbably it's not obvious enough and your patch is worth it, but then\nit would be less confusing if you added \"(see next item).\" at the end\nof your sentence.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"144252","messageId":"7vd3vfkt17.fsf@alter.siamese.dyndns.org","threadId":"24184","inReplyTo":"633f42d1967049780d66cf72552b22ae17bbbead.1277476258.git.git@drmicha.warpmail.net","subject":"Re: [PATCHv2] git-rev-parse.txt: Document \":path\" specifier","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-06-25T15:53:40Z","receivedAt":"2010-06-25T15:53:40Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber <git@drmicha.warpmail.net> writes:\n\n> The empty treeish in \":path\" means \"index\". Document this.\n>\n> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n> ---\n>  Documentation/git-rev-parse.txt |    5 +++--\n>  1 files changed, 3 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\n> index 8db600f..f964de4 100644\n> --- a/Documentation/git-rev-parse.txt\n> +++ b/Documentation/git-rev-parse.txt\n> @@ -290,8 +290,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n>    followed by something else than '!' is reserved for now.\n>  \n>  * A suffix ':' followed by a path; this names the blob or tree\n> -  at the given path in the tree-ish object named by the part\n> -  before the colon.\n> +  at the given path in the tree-ish object named by the ref\n> +  before the colon. An empty ref before ':' denotes the content\n> +  recorded in the index at the given path.\n\nI am wondering if it is less confusing to present these two cases as two\nindependent entries...\n\n    A colon ':' followed by a path names the blob at the given path in the\n    index.\n\n    A tree-ish, followed by a colon ':', followed by a path names the blob\n    or tree at the given path  in the tree-ish.\n\nIt is not like we treat the index as a pseudo tree, but your wording\nimplies we do in this syntax.  We of course cannot treat the index as a\npseudo tree in all operations, and people can get confused and ask \"When\ncan I say empty to mean index?\"...\n\nThoughts?\n"},{"id":"144258","messageId":"7vpqzfj8zi.fsf@alter.siamese.dyndns.org","threadId":"24184","inReplyTo":"vpqvd97rv5q.fsf@bauges.imag.fr","subject":"Re: [PATCHv2] git-rev-parse.txt: Document \":path\" specifier","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-06-25T17:52:01Z","receivedAt":"2010-06-25T17:52:01Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:\n\n> Actually, what you're adding is precisely what was already documented\n> right below:\n>\n>>  * A colon, optionally followed by a stage number (0 to 3) and a\n>>    colon, followed by a path; this names a blob object in the\n>      index at the given path.  Missing stage number (and the colon\n>      that follows it) names a stage 0 entry. During a merge, stage\n>      1 is the common ancestor, stage 2 is the target branch's version\n>      (typically the current branch), and stage 3 is the version from\n>      the branch being merged.\n>\n> Probably it's not obvious enough and your patch is worth it, but then\n> it would be less confusing if you added \"(see next item).\" at the end\n> of your sentence.\n\nAnother possibility is to swap the order of presentation.  It might reduce\nthe confusion of ':path' form appearing to be a variant of 'tree:path',\nand that is what invited the \"what happens when tree is an empty string\"\nquestion, I think.\n"},{"id":"144348","messageId":"6af64ac563a9a165bec7fddc779b31ae5bcb9997.1277644307.git.git@drmicha.warpmail.net","threadId":"24184","inReplyTo":"7vpqzfj8zi.fsf@alter.siamese.dyndns.org","subject":"[PATCHv3] git-rev-parse.txt: Document \":path\" specifier","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-06-27T13:15:22Z","receivedAt":"2010-06-27T13:15:22Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"The empty treeish in \":path\" means \"index\". This is actually a special\ncase of the \":stage:path\" syntax where it is documented, but mentioning\nit also together with \"treeish:path\" is helpful, so do it.\n\nSigned-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n---\nHow about this? Short description at \"rev:path\" but still pointing\nto \":stage:path\".\n\n Documentation/git-rev-parse.txt |    4 +++-\n 1 files changed, 3 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex 8db600f..d525e57 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -291,7 +291,9 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n \n * A suffix ':' followed by a path; this names the blob or tree\n   at the given path in the tree-ish object named by the part\n-  before the colon.\n+  before the colon. \":path\" (with an empty part before the colon)\n+  is a special case of the syntax described next: content\n+  recorded in the index at the given path.\n \n * A colon, optionally followed by a stage number (0 to 3) and a\n   colon, followed by a path; this names a blob object in the\n-- \n1.7.1.621.g01d76\n"},{"id":"144356","messageId":"7vocewff4b.fsf@alter.siamese.dyndns.org","threadId":"24184","inReplyTo":"6af64ac563a9a165bec7fddc779b31ae5bcb9997.1277644307.git.git@drmicha.warpmail.net","subject":"Re: [PATCHv3] git-rev-parse.txt: Document \":path\" specifier","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-06-27T19:29:56Z","receivedAt":"2010-06-27T19:29:56Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thanks, will replace v2 with this versoin, but I suspect that swapping the\ntwo bullets in the existing documentation without anything else may be a\nsimpler and easier-to-read alternative.\n\nOrthogonal to this, it would probably make sense to give a simplest\nexample in-line in the text, i.e.\n\n Documentation/git-rev-parse.txt |    6 +++---\n 1 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex 8db600f..c03f31d 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -291,12 +291,12 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n \n * A suffix ':' followed by a path; this names the blob or tree\n   at the given path in the tree-ish object named by the part\n-  before the colon.\n+  before the colon (e.g. \"HEAD:README\").\n \n * A colon, optionally followed by a stage number (0 to 3) and a\n   colon, followed by a path; this names a blob object in the\n-  index at the given path.  Missing stage number (and the colon\n-  that follows it) names a stage 0 entry. During a merge, stage\n+  index at the given path (e.g. \":0:README\").  Missing stage number (and the colon\n+  that follows it) names a stage 0 entry (e.g. \":README\"). During a merge, stage\n   1 is the common ancestor, stage 2 is the target branch's version\n   (typically the current branch), and stage 3 is the version from\n   the branch being merged.\n"},{"id":"144357","messageId":"4C27A982.9080006@drmicha.warpmail.net","threadId":"24184","inReplyTo":"7vocewff4b.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCHv3] git-rev-parse.txt: Document \":path\" specifier","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-06-27T19:41:54Z","receivedAt":"2010-06-27T19:41:54Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Junio C Hamano venit, vidit, dixit 27.06.2010 21:29:\n> Thanks, will replace v2 with this versoin, but I suspect that swapping the\n> two bullets in the existing documentation without anything else may be a\n> simpler and easier-to-read alternative.\n> \n> Orthogonal to this, it would probably make sense to give a simplest\n> example in-line in the text, i.e.\n> \n>  Documentation/git-rev-parse.txt |    6 +++---\n>  1 files changed, 3 insertions(+), 3 deletions(-)\n> \n> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\n> index 8db600f..c03f31d 100644\n> --- a/Documentation/git-rev-parse.txt\n> +++ b/Documentation/git-rev-parse.txt\n> @@ -291,12 +291,12 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n>  \n>  * A suffix ':' followed by a path; this names the blob or tree\n>    at the given path in the tree-ish object named by the part\n> -  before the colon.\n> +  before the colon (e.g. \"HEAD:README\").\n\nYep, I think the whole discussion there is quite theoretical, often\ndescribing symbols like slash and colon by words rather then writing\nthem out. That could be the topic for a more extensive rewrite. But I'm\noften wondering whether git-rev-parse(1) really is the place for that,\nor whether the whole revision syntax should into, say, gitrevision, to\ngo with gitglossary etc.\n\nMichael\n"},{"id":"144368","messageId":"vpqy6dzislq.fsf@bauges.imag.fr","threadId":"24184","inReplyTo":"7vocewff4b.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCHv3] git-rev-parse.txt: Document \":path\" specifier","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-06-28T06:22:41Z","receivedAt":"2010-06-28T06:22:41Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Orthogonal to this, it would probably make sense to give a simplest\n> example in-line in the text, i.e.\n\nDefinitely, yes.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"144376","messageId":"97667b60355ab334a390985cae56a28f7a622eb3.1277712897.git.git@drmicha.warpmail.net","threadId":"24184","inReplyTo":"7vocewff4b.fsf@alter.siamese.dyndns.org","subject":"[PATCH] git-rev-parse.txt: Add more examples for caret and colon","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-06-28T08:18:09Z","receivedAt":"2010-06-28T08:18:09Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Several items in the caret, colon and friends section contain examples\nalready. Make sure they all come with examples, and that examples come\nearly so that they serve as a visual guide, as well.\n\nSuggested-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n---\nThis is on top of the \":path\" patch to git-rev-parse.txt.\n\nI chose not to rewrap the paragraphs so that the diff is clearer,\nespecially with --color-words.\nI don't know what the best patch workflow guideline is here. Maybe\nrewrapping a v2?\n\n Documentation/git-rev-parse.txt |   15 ++++++++-------\n 1 files changed, 8 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex d525e57..da5cdf4 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -256,7 +256,7 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n   the branch the ref is set to build on top of.  Missing ref defaults\n   to the current branch.\n \n-* A suffix '{caret}' to a revision parameter means the first parent of\n+* A suffix '{caret}' to a revision parameter (e.g. \"HEAD^\") means the first parent of\n   that commit object.  '{caret}<n>' means the <n>th parent (i.e.\n   'rev{caret}'\n   is equivalent to 'rev{caret}1').  As a special rule,\n@@ -282,23 +282,24 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n   and dereference the tag recursively until a non-tag object is\n   found.\n \n-* A colon, followed by a slash, followed by a text: this names\n+* A colon, followed by a slash, followed by a text (e.g. \":/fix nasty bug\"): this names\n   a commit whose commit message starts with the specified text.\n   This name returns the youngest matching commit which is\n   reachable from any ref.  If the commit message starts with a\n   '!', you have to repeat that;  the special sequence ':/!',\n   followed by something else than '!' is reserved for now.\n \n-* A suffix ':' followed by a path; this names the blob or tree\n+* A suffix ':' followed by a path (e.g. \"HEAD:README\"); this names the blob or tree\n   at the given path in the tree-ish object named by the part\n-  before the colon. \":path\" (with an empty part before the colon)\n+  before the colon.\n+  \":path\" (with an empty part before the colon, e.g. \":README\")\n   is a special case of the syntax described next: content\n   recorded in the index at the given path.\n \n * A colon, optionally followed by a stage number (0 to 3) and a\n-  colon, followed by a path; this names a blob object in the\n-  index at the given path.  Missing stage number (and the colon\n-  that follows it) names a stage 0 entry. During a merge, stage\n+  colon, followed by a path (e.g. \":0:README\"); this names a blob object in the\n+  index at the given path. Missing stage number (and the colon\n+  that follows it, e.g. \":README\") names a stage 0 entry. During a merge, stage\n   1 is the common ancestor, stage 2 is the target branch's version\n   (typically the current branch), and stage 3 is the version from\n   the branch being merged.\n-- \n1.7.1.621.g01d76\n"},{"id":"144382","messageId":"A612847CFE53224C91B23E3A5B48BAC74483CEF65C@xmail3.se.axis.com","threadId":"24184","inReplyTo":"97667b60355ab334a390985cae56a28f7a622eb3.1277712897.git.git@drmicha.warpmail.net","subject":"RE: [PATCH] git-rev-parse.txt: Add more examples for caret and colon","fromName":"Peter Kjellerstedt","fromEmail":"peter.kjellerstedt@axis.com","sentAt":"2010-06-28T10:03:43Z","receivedAt":"2010-06-28T10:03:43Z","isPatch":true,"sender":{"key":"peter.kjellerstedt@axis.com","avatar":"https://gravatar.com/avatar/6d5a0182283c8eccd7b134a54dbfd5f30038f3ad4d38b96f424884b614a61ca2?d=mp&s=160"},"body":"> -----Original Message-----\n> From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On\n> Behalf Of Michael J Gruber\n> Sent: den 28 juni 2010 10:18\n> To: git@vger.kernel.org\n> Cc: Junio C Hamano; Matthieu Moy\n> Subject: [PATCH] git-rev-parse.txt: Add more examples for caret and\n> colon\n> \n> Several items in the caret, colon and friends section contain examples\n> already. Make sure they all come with examples, and that examples come\n> early so that they serve as a visual guide, as well.\n> \n> Suggested-by: Junio C Hamano <gitster@pobox.com>\n> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n> ---\n> This is on top of the \":path\" patch to git-rev-parse.txt.\n> \n> I chose not to rewrap the paragraphs so that the diff is clearer,\n> especially with --color-words.\n> I don't know what the best patch workflow guideline is here. Maybe\n> rewrapping a v2?\n> \n>  Documentation/git-rev-parse.txt |   15 ++++++++-------\n>  1 files changed, 8 insertions(+), 7 deletions(-)\n> \n> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-\n> parse.txt\n> index d525e57..da5cdf4 100644\n> --- a/Documentation/git-rev-parse.txt\n> +++ b/Documentation/git-rev-parse.txt\n> @@ -256,7 +256,7 @@ the `$GIT_DIR/refs` directory or from the\n> `$GIT_DIR/packed-refs` file.\n>    the branch the ref is set to build on top of.  Missing ref defaults\n>    to the current branch.\n> \n> -* A suffix '{caret}' to a revision parameter means the first parent of\n> +* A suffix '{caret}' to a revision parameter (e.g. \"HEAD^\") means the first parent of\n\nShouldn't that be\n\n* A suffix '{caret}' to a revision parameter (e.g. `HEAD{caret}`) means the first parent of\n\nfor consistency?\n\n>    that commit object.  '{caret}<n>' means the <n>th parent (i.e.\n>    'rev{caret}'\n>    is equivalent to 'rev{caret}1').  As a special rule,\n> @@ -282,23 +282,24 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n>    and dereference the tag recursively until a non-tag object is\n>    found.\n> \n> -* A colon, followed by a slash, followed by a text: this names\n> +* A colon, followed by a slash, followed by a text (e.g. \":/fix nasty bug\"): this names\n\nMost examples in this file seem to use `` rather than \"\".\n\n>    a commit whose commit message starts with the specified text.\n>    This name returns the youngest matching commit which is\n>    reachable from any ref.  If the commit message starts with a\n>    '!', you have to repeat that;  the special sequence ':/!',\n>    followed by something else than '!' is reserved for now.\n> \n> -* A suffix ':' followed by a path; this names the blob or tree\n> +* A suffix ':' followed by a path (e.g. \"HEAD:README\"); this names the blob or tree\n>    at the given path in the tree-ish object named by the part\n> -  before the colon. \":path\" (with an empty part before the colon)\n> +  before the colon.\n> +  \":path\" (with an empty part before the colon, e.g. \":README\")\n>    is a special case of the syntax described next: content\n>    recorded in the index at the given path.\n> \n>  * A colon, optionally followed by a stage number (0 to 3) and a\n> -  colon, followed by a path; this names a blob object in the\n> -  index at the given path.  Missing stage number (and the colon\n> -  that follows it) names a stage 0 entry. During a merge, stage\n> +  colon, followed by a path (e.g. \":0:README\"); this names a blob object in the\n> +  index at the given path. Missing stage number (and the colon\n> +  that follows it, e.g. \":README\") names a stage 0 entry. During a merge, stage\n>    1 is the common ancestor, stage 2 is the target branch's version\n>    (typically the current branch), and stage 3 is the version from\n>    the branch being merged.\n> --\n> 1.7.1.621.g01d76\n\nI tried to find a document describing documentation standards for \ngit (i.e., something similar to Documentation/CodingGuidelines),\nbut could not find any such document. Did I just miss it, or does\nit not exist?\n\n//Peter\n"},{"id":"144385","messageId":"4C28790C.2050301@drmicha.warpmail.net","threadId":"24184","inReplyTo":"A612847CFE53224C91B23E3A5B48BAC74483CEF65C@xmail3.se.axis.com","subject":"Re: [PATCH] git-rev-parse.txt: Add more examples for caret and colon","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-06-28T10:27:24Z","receivedAt":"2010-06-28T10:27:24Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Peter Kjellerstedt venit, vidit, dixit 28.06.2010 12:03:\n>> -----Original Message-----\n>> From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On\n>> Behalf Of Michael J Gruber\n>> Sent: den 28 juni 2010 10:18\n>> To: git@vger.kernel.org\n>> Cc: Junio C Hamano; Matthieu Moy\n>> Subject: [PATCH] git-rev-parse.txt: Add more examples for caret and\n>> colon\n>>\n>> Several items in the caret, colon and friends section contain examples\n>> already. Make sure they all come with examples, and that examples come\n>> early so that they serve as a visual guide, as well.\n>>\n>> Suggested-by: Junio C Hamano <gitster@pobox.com>\n>> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n>> ---\n>> This is on top of the \":path\" patch to git-rev-parse.txt.\n>>\n>> I chose not to rewrap the paragraphs so that the diff is clearer,\n>> especially with --color-words.\n>> I don't know what the best patch workflow guideline is here. Maybe\n>> rewrapping a v2?\n>>\n>>  Documentation/git-rev-parse.txt |   15 ++++++++-------\n>>  1 files changed, 8 insertions(+), 7 deletions(-)\n>>\n>> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-\n>> parse.txt\n>> index d525e57..da5cdf4 100644\n>> --- a/Documentation/git-rev-parse.txt\n>> +++ b/Documentation/git-rev-parse.txt\n>> @@ -256,7 +256,7 @@ the `$GIT_DIR/refs` directory or from the\n>> `$GIT_DIR/packed-refs` file.\n>>    the branch the ref is set to build on top of.  Missing ref defaults\n>>    to the current branch.\n>>\n>> -* A suffix '{caret}' to a revision parameter means the first parent of\n>> +* A suffix '{caret}' to a revision parameter (e.g. \"HEAD^\") means the first parent of\n> \n> Shouldn't that be\n> \n> * A suffix '{caret}' to a revision parameter (e.g. `HEAD{caret}`) means the first parent of\n> \n> for consistency?\n\nBoth of them render the same with my asciidoc. I don't mind making it\nconsistent.\n\n~ and ^ are dangerous with asciidoc 8, but we compile with\nasciidoc7compatible, so this is a non-issue.\n\n> \n>>    that commit object.  '{caret}<n>' means the <n>th parent (i.e.\n>>    'rev{caret}'\n>>    is equivalent to 'rev{caret}1').  As a special rule,\n>> @@ -282,23 +282,24 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n>>    and dereference the tag recursively until a non-tag object is\n>>    found.\n>>\n>> -* A colon, followed by a slash, followed by a text: this names\n>> +* A colon, followed by a slash, followed by a text (e.g. \":/fix nasty bug\"): this names\n> \n> Most examples in this file seem to use `` rather than \"\".\n\nI did not do the statistics, many use `, many use ', and many use \".\nThe first two often render in the same way.\n\n> \n>>    a commit whose commit message starts with the specified text.\n>>    This name returns the youngest matching commit which is\n>>    reachable from any ref.  If the commit message starts with a\n>>    '!', you have to repeat that;  the special sequence ':/!',\n>>    followed by something else than '!' is reserved for now.\n>>\n>> -* A suffix ':' followed by a path; this names the blob or tree\n>> +* A suffix ':' followed by a path (e.g. \"HEAD:README\"); this names the blob or tree\n>>    at the given path in the tree-ish object named by the part\n>> -  before the colon. \":path\" (with an empty part before the colon)\n>> +  before the colon.\n>> +  \":path\" (with an empty part before the colon, e.g. \":README\")\n>>    is a special case of the syntax described next: content\n>>    recorded in the index at the given path.\n>>\n>>  * A colon, optionally followed by a stage number (0 to 3) and a\n>> -  colon, followed by a path; this names a blob object in the\n>> -  index at the given path.  Missing stage number (and the colon\n>> -  that follows it) names a stage 0 entry. During a merge, stage\n>> +  colon, followed by a path (e.g. \":0:README\"); this names a blob object in the\n>> +  index at the given path. Missing stage number (and the colon\n>> +  that follows it, e.g. \":README\") names a stage 0 entry. During a merge, stage\n>>    1 is the common ancestor, stage 2 is the target branch's version\n>>    (typically the current branch), and stage 3 is the version from\n>>    the branch being merged.\n>> --\n>> 1.7.1.621.g01d76\n> \n> I tried to find a document describing documentation standards for \n> git (i.e., something similar to Documentation/CodingGuidelines),\n> but could not find any such document. Did I just miss it, or does\n> it not exist?\n\nIronically, I have tried to suggest something like that, together with a\nseries of patches implementing that. Feel free to try again ;)\n\nAs a general practical rule, I think we try to stay \"locally\nconsistent\", i.e. within the surrounding context.\n\nFor current asciidoc:\n'foo' is emphasized\n`foo` is monospaced and literal (not expanded)\n`foo' is enclosed in single quotation marks\n``foo'' is enclosed in double quotation marks\n\n(In fact, for us `foo` is not foo because we compile with\nno-inline-literal to shut off asciidoc 8.4 changes for inline literals.)\n\nMichael\n"},{"id":"144407","messageId":"d67020fd6ee18ac22cedaf482faf2b98e1cce1a9.1277750432.git.git@drmicha.warpmail.net","threadId":"24184","inReplyTo":"4C28790C.2050301@drmicha.warpmail.net","subject":"[PATCHv2] git-rev-parse.txt: Add more examples for caret and colon","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-06-28T19:01:07Z","receivedAt":"2010-06-28T19:01:07Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Several items in the caret, colon and friends section contain examples\nalready. Make sure they all come with examples, and that examples come\nearly so that they serve as a visual guide, as well.\n\nSigned-off-by: Michael J Gruber <git@drmicha.warpmail.net>\n---\nThis is on top of the \":path\" patch to git-rev-parse.txt.\n\nI chose not to rewrap the paragraphs so that the diff is clearer,\nespecially with --color-words.\n\nv3 now has the quoting style consistent at least locally (and the caret\nspelled out), although the existing text changes style midway.\n\nThis is about as far as I will go with a \"minimal change\" patch trying\nto alleviate the :something confusion. I really think the whole part\nneeds an overhaul not only to make it consistent, so bikeshedding before\nthat is pointless ;)\n\n Documentation/git-rev-parse.txt |   15 ++++++++-------\n 1 files changed, 8 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex d525e57..833a2a2 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -256,7 +256,7 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n   the branch the ref is set to build on top of.  Missing ref defaults\n   to the current branch.\n \n-* A suffix '{caret}' to a revision parameter means the first parent of\n+* A suffix '{caret}' to a revision parameter (e.g. 'HEAD{caret}') means the first parent of\n   that commit object.  '{caret}<n>' means the <n>th parent (i.e.\n   'rev{caret}'\n   is equivalent to 'rev{caret}1').  As a special rule,\n@@ -282,23 +282,24 @@ the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.\n   and dereference the tag recursively until a non-tag object is\n   found.\n \n-* A colon, followed by a slash, followed by a text: this names\n+* A colon, followed by a slash, followed by a text (e.g. `:/fix nasty bug`): this names\n   a commit whose commit message starts with the specified text.\n   This name returns the youngest matching commit which is\n   reachable from any ref.  If the commit message starts with a\n   '!', you have to repeat that;  the special sequence ':/!',\n   followed by something else than '!' is reserved for now.\n \n-* A suffix ':' followed by a path; this names the blob or tree\n+* A suffix ':' followed by a path (e.g. `HEAD:README`); this names the blob or tree\n   at the given path in the tree-ish object named by the part\n-  before the colon. \":path\" (with an empty part before the colon)\n+  before the colon.\n+  ':path' (with an empty part before the colon, e.g. `:README`)\n   is a special case of the syntax described next: content\n   recorded in the index at the given path.\n \n * A colon, optionally followed by a stage number (0 to 3) and a\n-  colon, followed by a path; this names a blob object in the\n-  index at the given path.  Missing stage number (and the colon\n-  that follows it) names a stage 0 entry. During a merge, stage\n+  colon, followed by a path (e.g. `:0:README`); this names a blob object in the\n+  index at the given path. Missing stage number (and the colon\n+  that follows it, e.g. `:README`) names a stage 0 entry. During a merge, stage\n   1 is the common ancestor, stage 2 is the target branch's version\n   (typically the current branch), and stage 3 is the version from\n   the branch being merged.\n-- \n1.7.1.621.g01d76\n"}]}