README.md: Clarify `oot.command'

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/README.md b/README.md
index 4f5bbf98fd1a8ae32501f5872b84c4c0b97248ae..aa6533135e3808738dc7b4589b72cfc0476f6f7a 100644 (file)
--- a/README.md
+++ b/README.md
@@ -475,6 +475,26 @@ To control use of alternative `Cargo.lock` filename, use the section
 
  * `command`: The command to run for `command_sh` or `command_args`.
 
+   In both cases, this is a command and its arguments/options.  The
+   list will be passed to `execvp`.  The difference between
+   `command_args` and `command_sh` is in what nailing-cargo appends to
+   the specified `command` list:
+
+   For `command_args`, nailing cargo appends multiple more arguments;
+   each one should be passed as-is as a single argument to the actual
+   build command.  This is correct if `command` is a program like
+   `nice` or `really`, which takes a command and its arguments and
+   does not go via the shell.
+
+   For `command_sh`, nailing-cargo appends one single further
+   argument.  That argument is a shell command; nailing-cargo
+   constructs it by shell-quoting the real command and arguments and
+   wrapping them up in a small script, the text of which becomes the
+   extra argument to `command`.  This is correct if `command` will
+   pass its argument to a bournelike shell - for example, if `command`
+   is an ssh rune for a remote account whose shell is `/bin/sh` or
+   `/bin/bash`.
+
  * `user`: The build username, for `really` and `ssh`.  For `ssh`, can
    be just the local username (meaning `@localhost`), or
    `<user>@<host>`.