Documentation/rev-parse: quoting is required with --parseopt

When calling rev-parse --parseopt, as in the (now fixed) documented
example

eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"

the outermost quoting is required, as otherwise all runs of arbitrary
whitespace inside the resulting 'set -- ...' call would be collapsed
into a single space.

This was exposed as a result of our new use of cat <<\EOF since
47e9cd2 (parseopt: wrap rev-parse --parseopt usage for eval
consumption, 2010-06-12), but has always been a problem when handling
arguments containing e.g. newlines.

Point this out in the documentation, and in particular correct the
example that did not have the quotes.

Noticed-by: Joshua Jensen <jjensen@workspacewhiz.com>
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 0727f431c6dc01296b04cc93204ba37d16b5a32b..be4c0533603443cd9b4df5bf732bbcdd31802a11 100644 (file)
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -184,10 +184,13 @@ scripts the same facilities C builtins have. It works as an option normalizer
 (e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
 
 It takes on the standard input the specification of the options to parse and
 (e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
 
 It takes on the standard input the specification of the options to parse and

-understand, and echoes on the standard output a line suitable for `sh(1)` `eval`
+understand, and echoes on the standard output a string suitable for `sh(1)` `eval`

 to replace the arguments with normalized ones.  In case of error, it outputs
 usage on the standard error stream, and exits with code 129.
 
 to replace the arguments with normalized ones.  In case of error, it outputs
 usage on the standard error stream, and exits with code 129.
 

+Note: Make sure you quote the result when passing it to `eval`.  See
+below for an example.
+

 Input Format
 ~~~~~~~~~~~~
 
 Input Format
 ~~~~~~~~~~~~
 


@@ -244,7 +247,7 @@ bar=      some cool option --bar with an argument
   An option group Header
 C?        option C with an optional argument"
 
   An option group Header
 C?        option C with an optional argument"
 

-eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?`
+eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"

 ------------
 
 SQ-QUOTE
 ------------
 
 SQ-QUOTE