Merge branch 'cc/bisect' (early part)

* 'cc/bisect' (early part):
  bisect: make "git bisect" use new "--next-all" bisect-helper function
  bisect: add "check_good_are_ancestors_of_bad" function
  bisect: implement the "check_merge_bases" function
  bisect: automatically sort sha1_array if needed when looking it up
  bisect: make skipped array functions more generic
  bisect: remove too much function nesting
  bisect: use new "struct argv_array" to prepare argv for "setup_revisions"
  bisect: store good revisions in a "sha1_array"
  bisect: implement "rev_argv_push" to fill an argv with revs
  bisect: use "sha1_array" to store skipped revisions
  am: simplify "sq" function by using "git rev-parse --sq-quote"
  bisect: use "git rev-parse --sq-quote" instead of a custom "sq" function
  rev-parse: add --sq-quote to shell quote arguments
  rev-list: remove stringed output flag from "show_bisect_vars"
  bisect--helper: remove "--next-vars" option as it is now useless
  bisect: use "git bisect--helper --next-exit" in "git-bisect.sh"
  bisect--helper: add "--next-exit" to output bisect results
  bisect: move common bisect functionality to "bisect_common"
  rev-list: refactor printing bisect vars
  rev-list: make "estimate_bisect_steps" non static

1 files changed, 34 insertions, 1 deletions

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 52c353e674..4bbdd056da 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -30,6 +30,11 @@ OPTIONS
 	Only meaningful in `--parseopt` mode. Tells the option parser to echo
 	out the first `--` met instead of skipping it.
 
+--sq-quote::
+	Use 'git-rev-parse' in shell quoting mode (see SQ-QUOTE
+	section below). In contrast to the `--sq` option below, this
+	mode does only quoting. Nothing else is done to command input.
+
 --revs-only::
 	Do not output flags and parameters not meant for
 	'git-rev-list' command.
@@ -64,7 +69,8 @@ OPTIONS
 	properly quoted for consumption by shell.  Useful when
 	you expect your parameter to contain whitespaces and
 	newlines (e.g. when using pickaxe `-S` with
-	'git-diff-\*').
+	'git-diff-\*'). In contrast to the `--sq-quote` option,
+	the command input is still interpreted as usual.
 
 --not::
 	When showing object names, prefix them with '{caret}' and
@@ -406,6 +412,33 @@ C?        option C with an optional argument"
 eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?`
 ------------
 
+SQ-QUOTE
+--------
+
+In `--sq-quote` mode, 'git-rev-parse' echoes on the standard output a
+single line suitable for `sh(1)` `eval`. This line is made by
+normalizing the arguments following `--sq-quote`. Nothing other than
+quoting the arguments is done.
+
+If you want command input to still be interpreted as usual by
+'git-rev-parse' before the output is shell quoted, see the `--sq`
+option.
+
+Example
+~~~~~~~
+
+------------
+$ cat >your-git-script.sh <<\EOF
+#!/bin/sh
+args=$(git rev-parse --sq-quote "$@")   # quote user-supplied arguments
+command="git frotz -n24 $args"          # and use it inside a handcrafted
+					# command line
+eval "$command"
+EOF
+
+$ sh your-git-script.sh "a b'c"
+------------
+
 EXAMPLES
 --------