run-command: document use_shell option

It's unclear how run-command's use_shell option should impact the
arguments fed to a command. Plausibly it could mean that we glue all of
the arguments together into a string to pass to the shell, in which case
that opens the question of whether the caller needs to quote them.

But in fact we don't implement it that way (and even if we did, we'd
probably auto-quote the arguments as part of the glue step). And we must
not receive quoted arguments, because we might actually optimize out the
shell entirely (i.e., the caller does not even know if a shell will be
involved in the end or not).

Since this ambiguity may have been the cause of a recent bug, let's
document the option a bit.

Signed-off-by: Jeff King <peff@peff.net>
Reviewed-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/run-command.h b/run-command.h
index 6472b38bde448cd256697b0b3cbd962cdf3da333..d08414a92e734c8b0768b4dc142be8508d522d0d 100644 (file)
--- a/run-command.h
+++ b/run-command.h
@@ -126,8 +126,15 @@ struct child_process {
         */
        unsigned silent_exec_failure:1;
 
-       unsigned stdout_to_stderr:1;
+       /**
+        * Run the command from argv[0] using a shell (but note that we may
+        * still optimize out the shell call if the command contains no
+        * metacharacters). Note that further arguments to the command in
+        * argv[1], etc, do not need to be shell-quoted.
+        */
        unsigned use_shell:1;
+
+       unsigned stdout_to_stderr:1;
        unsigned clean_on_exit:1;
        unsigned wait_after_clean:1;
        void (*clean_on_exit_handler)(struct child_process *process);