From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sun, 21 Jun 2020 18:33:03 +0000 (+0100)
Subject: README.md: Clarify `oot.command'
X-Git-Tag: nailing-cargo/1.0.0~106
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=5de5f8d79d86eaabd41eef09211c2c7d9bff4eae;p=nailing-cargo.git

README.md: Clarify `oot.command'

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

diff --git a/README.md b/README.md
index 4f5bbf9..aa65331 100644
--- 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>`.