From f1c7b555e17b4db2433ca17b92ded7164556a1d6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fe=CC=81lix=20Saparelli?= <felix@passcod.name>
Date: Sat, 17 Apr 2021 01:57:47 +1200
Subject: [PATCH] Document the --shell semantics in the manpage

---
 doc/watchexec.1.ronn | 25 +++++++++++++++++++++++++
 src/config.rs        |  2 +-
 src/process.rs       |  2 +-
 3 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/doc/watchexec.1.ronn b/doc/watchexec.1.ronn
index 715af446..38fcc468 100644
--- a/doc/watchexec.1.ronn
+++ b/doc/watchexec.1.ronn
@@ -30,8 +30,14 @@ Change the shell used to run the command. Set to `none` to run the command direc
 
 The special value `powershell` will use Microsoft Powershell's calling convention, otherwise `SHELL -c COMMAND`.
 
+On Windows, the additional `cmd` special value uses CMD.EXE calling convention.
+
 The `none` value is especially useful in combination with `--signal`, as the signal is then send directly to the specified command. While `--shell=none` is a little more performant than the default, it prevents using shell-features like pipes and redirects.
 
+If not a special value, the string provided may contain arguments to the shell as long as that is kept simple: the string is split along whitespace, and used as per execvp(3): first is shell program, rest are arguments to the shell, then `-c` is added, and finally the `COMMAND`.
+
+See the [EXAMPLES] for uses of each of these.
+
 * `--no-shell`:
 Deprecated. Alias for `--shell=none`.
 
@@ -126,3 +132,22 @@ Watch lib and src directories for changes, rebuilding each time:
 
     $ watchexec -w lib -w src make
 
+Use without shell:
+
+    $ watchexec -n -- zsh -x -o shwordsplit scr
+
+Use with powershell (default on windows from 2.0):
+
+    $ watchexec --shell=powershell -- test-connection localhost
+
+Use with cmd (default on windows until 2.0):
+
+    $ watchexec --shell=cmd -- dir
+
+Use with a different unix shell:
+
+    $ watchexec --shell=bash -- 'echo $BASH_VERSION'
+
+Use with a unix shell and options:
+
+    $ watchexec --shell='zsh -x -o shwordsplit' -- scr
diff --git a/src/config.rs b/src/config.rs
index 619c3196..eeb52218 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -26,7 +26,7 @@ use crate::run::OnBusyUpdate;
 pub struct Config {
     /// Command to execute.
     ///
-    /// When `shell` is [`Shell::None`], this is expected to be in “popen3”
+    /// When `shell` is [`Shell::None`], this is expected to be in “execvp(3)”
     /// format: first program, rest arguments. Otherwise, all elements will be
     /// joined together with a single space and passed to the shell. More
     /// control can then be obtained by providing a 1-element vec, and doing
diff --git a/src/process.rs b/src/process.rs
index f5786756..1a79aaf2 100644
--- a/src/process.rs
+++ b/src/process.rs
@@ -24,7 +24,7 @@ pub enum Shell {
     /// This means two things:
     /// - the program is invoked with `-c` followed by the command, and
     /// - the string will be split on space, and the resulting vec used as
-    ///   popen3 arguments: first is the shell program, rest are additional
+    ///   execvp(3) arguments: first is the shell program, rest are additional
     ///   arguments (which come before the `-c` mentioned above). This is a very
     ///   simplistic approach deliberately: it will not support quoted
     ///   arguments, for example. Use [`Shell::None`] with a custom command vec