@@ -234,13 +234,28 @@ int run_auto_maintenance(int quiet);
#define RUN_CLOSE_OBJECT_STORE (1<<7)
/**
- * Convenience functions that encapsulate a sequence of
- * start_command() followed by finish_command(). The argument argv
- * specifies the program and its arguments. The argument opt is zero
- * or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`,
- * `RUN_COMMAND_STDOUT_TO_STDERR`, or `RUN_SILENT_EXEC_FAILURE`
- * that correspond to the members .no_stdin, .git_cmd,
- * .stdout_to_stderr, .silent_exec_failure of `struct child_process`.
+ * The run_command_v_opt*() API is a convenience wrapper for an
+ * underlying run_command().
+ *
+ * It's intended to be used when the user already has an "argv" they'd
+ * like to use. As opposed to the "struct child_process"'s "args"
+ * member, which will be strvec_clear()'d by calling run_command(),
+ * the caller owns the "argv", which is not altered by invoking these
+ * functions.
+ *
+ * The "opt" flags that will cause various underlying run_command()
+ * members to be set. The flags and the corresponding struct members
+ * are:
+ *
+ * - RUN_COMMAND_NO_STDIN: .no_stdin
+ * - RUN_GIT_CMD: .git_cmd
+ * - RUN_COMMAND_STDOUT_TO_STDERR: .stdout_to_stderr
+ * - RUN_SILENT_EXEC_FAILURE: .silent_exec_failure
+ * - RUN_USING_SHELL: .use_shell
+ * - RUN_CLEAN_ON_EXIT: .clean_on_exit
+ * - RUN_WAIT_AFTER_CLEAN: .wait_after_clean
+ * - RUN_CLOSE_OBJECT_STORE: .close_object_store
+ *
* The argument dir corresponds the member .dir. The argument env
* corresponds to the member .env.
*/
Add a discussion of the flags that were missing to the run_command_v_opt*() docs, and in doing so format them such that we can easily add or remove flags from a table in the future, rather than having them tied up in prose. Let's also clarify why the user might want to use this API over run_command() itself. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> --- run-command.h | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-)