From f32943bfd29d26a5ec558f8f7d28b5fe3a9c3610 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fe=CC=81lix=20Saparelli?= <felix@passcod.name>
Date: Sun, 11 Apr 2021 03:31:44 +1200
Subject: [PATCH] Document --watch-when-idle much more thoroughly

---
 completions/zsh      | 3 ++-
 doc/watchexec.1.ronn | 4 +++-
 src/args.rs          | 2 +-
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/completions/zsh b/completions/zsh
index 628b1dc..4186f5a 100644
--- a/completions/zsh
+++ b/completions/zsh
@@ -11,13 +11,14 @@ cmd="$words[1]"
 args=(
   '(-c --clear)'{-c,--clear}'[Clear screen before executing command]'
   '(-h --help)'{-h,--help}'[Prints help information]'
-  '--shell=[Change the wrapping shell, or `none` to disable]'
+  '--shell=[Change the wrapping shell, or set to none to disable]'
   '--no-shell[Deprecated, use --shell=none]'
   '-n[Shorthand for --shell=none]'
   '--no-environment[Do not set WATCHEXEC_*_PATH environment variables for command]'
   '--no-meta[Ignore metadata changes]'
   '(-p --postpone)'{-p,--postpone}'[Wait until first change to execute command]'
   '(-r --restart)'{-r,--restart}'[Restart the process if it''s still running]'
+  '(-W --watch-when-idle)'{-W,--watch-when-idle}'[Ignore events while the command is still running]'
   '(-V --version)'{-V,--version}'[Prints version information]'
   '(-v --verbose)'{-v,--verbose}'[Print debugging messages to stderr]'
   '--changes-only[Print changed paths to stderr for pattern debugging]'
diff --git a/doc/watchexec.1.ronn b/doc/watchexec.1.ronn
index c498048..47b53b3 100644
--- a/doc/watchexec.1.ronn
+++ b/doc/watchexec.1.ronn
@@ -54,7 +54,9 @@ Monitor a specific path for changes. By default, the current working directory i
 Terminates the command if it is still running when subsequent file modifications are detected. By default, sends `SIGTERM`; use `--signal` to change that.
 
 * `-W`, `--watch-when-idle`:
-Ignore events while the process is still running.
+Ignore events while the process is still running. This is distinct from `--restart` in that with this option, events received while the command is running will not trigger a new run immediately after the current command is done.
+
+This behaviour will become the default in v2.0.
 
 * `-c`, `--clear`:
 Clears the screen before executing <command>.
diff --git a/src/args.rs b/src/args.rs
index 1a8e4d3..ee2472e 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -130,7 +130,7 @@ where
                  .long("no-environment"))
         .arg(Arg::with_name("once").short("1").hidden(true))
         .arg(Arg::with_name("watch-when-idle")
-                 .help("Ignore events while the process is still running")
+                 .help("Ignore events while the process is still running. This is distinct from `--restart` in that with this option, events received while the command is running will not trigger a new run immediately after the current command is done. Will become the default in 2.0.")
                  .short("W")
                  .long("watch-when-idle"));