<p>Recursively monitors the current directory for changes, executing the command when a filesystem change is detected. By default, watchexec uses efficient kernel-level mechanisms to watch for changes.</p>
<p>At startup, the specified <var>command</var> (passing any supplied <var>argument</var>s) is run once, and watchexec begins monitoring for changes.</p>
<dtclass="flush"><var>command</var></dt><dd>Command to run when watched files are modified, and at startup, unless <code>--postpone</code> is specified. All <var>argument</var>s are passed to <var>command</var>. If you pass flags to the command, you should separate it with <code>--</code>, for example: <code>watchexec -w src -- rsync -a src dest</code>.</dd>
</dl>
<p>Behaviour depends on the value of <code>--shell</code>: for all except <code>none</code>, every part of <var>command</var> is joined together into one string with a single ascii space character, and given to the shell as described. For <code>none</code>, each distinct element of <var>command</var> is passed as per the <spanclass="man-ref">execvp<spanclass="s">(3)</span></span> convention: first argument is the program, as a file or searched in the <code>PATH</code>, rest are arguments.</p>
<dt><code>-e</code>, <code>--exts</code><var>extensions</var></dt><dd><p>Comma-separated list of file extensions to filter by. Leading dots (.rs) are allowed. (This is a shorthand for <code>-f</code>).</p></dd>
<dt><code>-f</code>, <code>--filter</code><var>pattern</var></dt><dd><p>Ignores modifications from paths that do not match <var>pattern</var>. This option can be specified multiple times, where a match on any given pattern causes the path to trigger <var>command</var>.</p></dd>
<dt><code>-s</code>, <code>--signal</code></dt><dd><p>Sends the specified signal (e.g. <code>SIGKILL</code>) to the command. Defaults to <code>SIGTERM</code>.</p></dd>
<dt><code>--shell</code><var>shell</var></dt><dd><p>Change the shell used to run the command. Set to <code>none</code> to run the command directly without a shell.</p></dd>
</dl>
<p>The special value <code>powershell</code> will use Microsoft Powershell's calling convention, otherwise <code>SHELL -c COMMAND</code>.</p>
<p>On Windows, the additional <code>cmd</code> special value uses CMD.EXE calling convention.</p>
<p>The <code>none</code> value is especially useful in combination with <code>--signal</code>, as the signal is then sent directly to the running command. While <code>--shell=none</code> is a little more performant than the default, it prevents using shell-features like pipes and redirects.</p>
<p>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 <spanclass="man-ref">execvp<spanclass="s">(3)</span></span>: first is shell program, rest are arguments to the shell, then <code>-c</code> is added, and finally the <code>COMMAND</code>.</p>
<p>See the <ahref="#EXAMPLES"title="EXAMPLES"data-bare-link="true">EXAMPLES</a> for uses of each of these.</p>
<dt><code>-i</code>, <code>--ignore</code><var>pattern</var></dt><dd><p>Ignores modifications from paths that match <var>pattern</var>. This option can be specified multiple times, and a match on any pattern causes the path to be ignored.</p></dd>
<dt><code>-w</code>, <code>--watch</code><var>path</var></dt><dd><p>Monitor a specific path for changes. By default, the current working directory is watched. This may be specified multiple times, where a change in any watched directory (and subdirectories) causes <var>command</var> to be executed.</p></dd>
<dt><code>-r</code>, <code>--restart</code></dt><dd><p>Terminates the command if it is still running when subsequent file modifications are detected. By default, sends <code>SIGTERM</code>; use <code>--signal</code> to change that.</p></dd>
<dt><code>-W</code>, <code>--watch-when-idle</code></dt><dd><p>Ignore events while the process is still running. This is distinct from <code>--restart</code> 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.</p></dd>
</dl>
<p>This behaviour will become the default in v2.0.</p>
<dt><code>-c</code>, <code>--clear</code></dt><dd><p>Clears the screen before executing <var>command</var>.</p></dd>
<dt><code>-p</code>, <code>--postpone</code></dt><dd><p>Postpone execution of <var>command</var> until the first file modification is detected.</p></dd>
<dt><code>--force-poll</code><var>interval</var></dt><dd><p>Poll for changes every <var>interval</var> ms instead of using system-specific notification mechanisms (such as inotify). This is useful when you are monitoring NFS shares.</p></dd>
<dt><code>-d</code>, <code>--debounce</code></dt><dd><p>Set the timeout between detected change and command execution, to avoid restarting too frequently when there are many events; defaults to 100ms.</p></dd>
<dt><code>--no-vcs-ignore</code></dt><dd><p>Skip loading of version control system (VCS) ignore files. By default, watchexec loads .gitignore files in the current directory (or parent directories) and uses them to populate the ignore list.</p></dd>
<dt><code>--no-default-ignore</code></dt><dd><p>Skip default ignore statements. By default, watchexec ignores common temporary files for you, for example <code>*.swp</code>, <code>*.pyc</code>, and <code>.DS_Store</code>.</p></dd>
<dt><code>-v</code>, <code>--verbose</code></dt><dd><p>Prints diagnostic messages to STDERR.</p></dd>
<dt><code>--changes-only</code></dt><dd><p>Prints the paths that have changed as diagnostics to STDERR, but not everything else that <code>--verbose</code> prints.</p></dd>
<p>Processes started by watchexec have environment variables set describing the modification(s) observed. Which variable is set depends on how many modifications were observed and/or what type they were.</p>
<p>If a single file changed (depending on the event type):</p>
<ul>
<li><code>$WATCHEXEC_CREATED_PATH</code>, the path of the file that was created</li>
<li><code>$WATCHEXEC_REMOVED_PATH</code>, the path of the file that was removed</li>
<li><code>$WATCHEXEC_RENAMED_PATH</code>, the path of the file that was renamed</li>
<li><code>$WATCHEXEC_WRITTEN_PATH</code>, the path of the file that was modified</li>
<li><code>$WATCHEXEC_META_CHANGED_PATH</code>, the path of the file whose metadata changed</li>
</ul>
<p>If multiple files changed:</p>
<ul>
<li><code>$WATCHEXEC_COMMON_PATH</code>, the longest common path of all of the files that triggered a change</li>
