# [PATCH] Documentation: fix missing text for rev-parse --verify 5 messages from 2014-07-21 to 2014-07-22. Participants: brian m. carlson, Jonathan Nieder. Thread: https://gitlist.dev/t/37186 ## brian m. carlson, 2014-07-21 23:00 Subject: [PATCH] Documentation: fix missing text for rev-parse --verify Message-ID: <1405983635-77468-1-git-send-email-sandals@crustytoothpaste.net> URL: https://gitlist.dev/e/1405983635-77468-1-git-send-email-sandals%40crustytoothpaste.net ``` The caret (^) is used as a markup symbol in AsciiDoc. Due to the inability of AsciiDoc to parse a line containing an unmatched caret, it omitted the line from the output, resulting in the man page missing the end of a sentence. Escape this caret so that the man page ends up with the complete text. Signed-off-by: brian m. carlson --- Documentation/git-rev-parse.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 9bd76a5..0b84769 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -102,7 +102,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" + If you want to make sure that the output actually names an object in your object database and/or can be used as a specific type of object -you require, you can add "^{type}" peeling operator to the parameter. +you require, you can add "\^{type}" peeling operator to the parameter. For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR` names an existing object that is a commit-ish (i.e. a commit, or an annotated tag that points at a commit). To make sure that `$VAR` -- 2.0.1 ``` ## Jonathan Nieder, 2014-07-21 23:14 Subject: Re: [PATCH] Documentation: fix missing text for rev-parse --verify Message-ID: <20140721231438.GZ12427@google.com> URL: https://gitlist.dev/e/20140721231438.GZ12427%40google.com In-Reply-To: <1405983635-77468-1-git-send-email-sandals@crustytoothpaste.net> ``` brian m. carlson wrote: > The caret (^) is used as a markup symbol in AsciiDoc. Due to the > inability of AsciiDoc to parse a line containing an unmatched caret, it > omitted the line from the output, resulting in the man page missing the > end of a sentence. Wow. Usually asciidoc is more forgiving than that. Are there other pages affected by this too (e.g., "the commit HEAD^" in user-manual.txt)? [...] > --- a/Documentation/git-rev-parse.txt > +++ b/Documentation/git-rev-parse.txt > @@ -102,7 +102,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" > + > If you want to make sure that the output actually names an object in > your object database and/or can be used as a specific type of object > -you require, you can add "^{type}" peeling operator to the parameter. > +you require, you can add "\^{type}" peeling operator to the parameter. Does using {caret} for ^ work, too? Generally in asciidoc using a backslash to escape delimiter characters leads to trouble when the number of delimiters changes or the text is copy+pasted, since in a context where the backslash is unneeded it ends up being rendered as a literal backslash. Alternatively, does "`^{type}`" work? Thanks, Jonathan ``` ## brian m. carlson, 2014-07-21 23:35 Subject: Re: [PATCH] Documentation: fix missing text for rev-parse --verify Message-ID: <20140721233554.GC5616@vauxhall.crustytoothpaste.net> URL: https://gitlist.dev/e/20140721233554.GC5616%40vauxhall.crustytoothpaste.net In-Reply-To: <20140721231438.GZ12427@google.com> ``` On Mon, Jul 21, 2014 at 04:14:38PM -0700, Jonathan Nieder wrote: > brian m. carlson wrote: > > > The caret (^) is used as a markup symbol in AsciiDoc. Due to the > > inability of AsciiDoc to parse a line containing an unmatched caret, it > > omitted the line from the output, resulting in the man page missing the > > end of a sentence. > > Wow. Usually asciidoc is more forgiving than that. Are there other > pages affected by this too (e.g., "the commit HEAD^" in > user-manual.txt)? I didn't look at any other pages before submitting this. I noticed when I was looking up git rev-parse --verify on my Debian sid laptop at work. I just looked, and the place you mentioned in user-manual.txt wasn't affected. It looks like this is the only place in running text that we don't use backticks around the caret-containing text. > > --- a/Documentation/git-rev-parse.txt > > +++ b/Documentation/git-rev-parse.txt > > @@ -102,7 +102,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" > > + > > If you want to make sure that the output actually names an object in > > your object database and/or can be used as a specific type of object > > -you require, you can add "^{type}" peeling operator to the parameter. > > +you require, you can add "\^{type}" peeling operator to the parameter. > > Does using {caret} for ^ work, too? Generally in asciidoc using a > backslash to escape delimiter characters leads to trouble when the > number of delimiters changes or the text is copy+pasted, since in a > context where the backslash is unneeded it ends up being rendered as a > literal backslash. {caret} does not work; it leaves the sentence broken still. `^{type}` does work. Since that seems a bit cleaner, and I think the resultant formatting is fine, I'll reroll with that change. -- brian m. carlson / brian with sandals: Houston, Texas, US +1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187 ``` ## brian m. carlson, 2014-07-22 23:38 Subject: [PATCH v2] Documentation: fix missing text for rev-parse --verify Message-ID: <1406072291-99812-1-git-send-email-sandals@crustytoothpaste.net> URL: https://gitlist.dev/e/1406072291-99812-1-git-send-email-sandals%40crustytoothpaste.net In-Reply-To: <20140721233554.GC5616@vauxhall.crustytoothpaste.net> ``` The caret (^) is used as a markup symbol in AsciiDoc. Due to the inability of AsciiDoc to parse a line containing an unmatched caret, it omitted the line from the output, resulting in the man page missing the end of a sentence. The rest of the documentation uses backticks whenever a caret is encountered in running text, so do the same here. Signed-off-by: brian m. carlson --- Documentation/git-rev-parse.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 9bd76a5..074030f 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -102,7 +102,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" + If you want to make sure that the output actually names an object in your object database and/or can be used as a specific type of object -you require, you can add "^{type}" peeling operator to the parameter. +you require, you can add "`^{type}`" peeling operator to the parameter. For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR` names an existing object that is a commit-ish (i.e. a commit, or an annotated tag that points at a commit). To make sure that `$VAR` -- 2.0.1 ``` ## Jonathan Nieder, 2014-07-22 23:41 Subject: Re: [PATCH v2] Documentation: fix missing text for rev-parse --verify Message-ID: <20140722234139.GB10991@google.com> URL: https://gitlist.dev/e/20140722234139.GB10991%40google.com In-Reply-To: <1406072291-99812-1-git-send-email-sandals@crustytoothpaste.net> ``` brian m. carlson wrote: > Signed-off-by: brian m. carlson > --- > Documentation/git-rev-parse.txt | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) Thanks again for catching and fixing it. Reviewed-by: Jonathan Nieder ```