From ee4e22554f3d1f4a9ab53dc7719434a9031a300a Mon Sep 17 00:00:00 2001 From: Jeff King Date: Fri, 22 Jan 2021 16:03:33 -0500 Subject: [PATCH] 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 Reviewed-by: Taylor Blau Signed-off-by: Junio C Hamano --- run-command.h | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/run-command.h b/run-command.h index 6472b38bde..d08414a92e 100644 --- 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);