---
name: "watchman-wait"
section: "1"
platform: "linux"
package: "python3-pywatchman"
version: "4.9.0-7+b2"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/watchman-wait"
---

# watchman-wait(1)

waits for changes to files.

## NAME

watchman-wait - waits for changes to files.

## SYNOPSIS

**watchman** \[-h\] \[--relative RELATIVE\] \[--fields FIELDS\]\
 \[-s SEPARATOR\] \[-m MAX\_EVENTS\] \[-p PATTERN \[PATTERN ...\]\]\
 \[-t TIMEOUT\]\
 path \[path ...\]\

## DESCRIPTION

**watchman-wait** uses the watchman service to efficiently and recursively watch your specified list of paths.

It is suitable for waiting for changes to files from shell scripts.

It can stop after a configurable number of events are observed. The default is a single event.  You may also remove the limit and allow it to execute continuously.

watchman-wait will print one event per line.  The event information includes your specified list of fields, with each field separated by a space (or your choice of --separator).

Events are consolidated and settled by the watchman server before they are dispatched to watchman-wait.

## USAGE

**OPTIONAL ARGUMENTS**

**-h, --help**

-

  `show this help message and exit`

**--relative RELATIVE**

-

  `print paths relative to this dir (default=PWD)`

**--fields FIELDS**

-

  `Comma separated list of file information fields to` `return. The default is just the name. For a list of` `possible fields, see: https://facebook.github.io/watch` `man/docs/cmd/query.html#available-fields`

**-s SEPARATOR, --separator SEPARATOR**

-

  `String to use as field separator for event output.`

**-m MAX\_EVENTS, --max-events MAX\_EVENTS**

-

  `Set the maximum number of events that will be processed. When the limit` `is reached, watchman-wait will exit. The default is 1. Setting the limit` `to 0 removes the limit, causing watchman-wait to execute indefinitely.`

**-p PATTERN \[PATTERN ...\], --pattern PATTERN \[PATTERN ...\]**

-

  `Only emit paths that match this list of patterns. Patterns are` `applied by the watchman server and are matched against the root-relative` `paths. You will almost certainly want to use quotes around your pattern` `list so that your shell doesn't interpret the pattern. The pattern syntax` `is wildmatch style; globbing with recursive matching via '**'.`

**-t TIMEOUT, --timeout TIMEOUT**

-

  `Exit if no events trigger within the specified timeout. If timeout` `is zero (the default) then keep running indefinitely.  `

**POSITIONAL ARGUMENTS**

**path**

-

  `path(s) to watch`

**EXIT STATUS**

**0**

-

  `After successfully waiting for event(s)`

**1**

-

  `In case of a runtime error of some kind`

**2**

-

  `The -t/--timeout option was used and that amount of time passed before` `an event was received`

**3**

-

  `Execution was interrupted (Ctrl-C)`

## SEE ALSO

[watchman(1)](/watchman/1.md), [watchman-make(1)](/watchman-make/1.md)

For more information, please refer the online documentation ⟨http://facebook.github.io/watchman/docs/cli-options.html⟩