1--- 2pageid: cmd.subscribe 3title: subscribe 4layout: docs 5section: Commands 6permalink: docs/cmd/subscribe.html 7--- 8 9*Since 1.6* 10 11Subscribes to changes against a specified root and requests that they be sent 12to the client via its connection. The updates will continue to be sent while 13the connection is open. If the connection is closed, the subscription is 14implicitly removed. 15 16This makes the most sense in an application connecting via the socket 17interface, but you may also subscribe via the command line tool if you're 18interested in observing the changes for yourself: 19 20```bash 21$ watchman -j --server-encoding=json -p <<-EOT 22["subscribe", "/path/to/root", "mysubscriptionname", { 23 "expression": ["allof", 24 ["type", "f"], 25 ["not", "empty"], 26 ["suffix", "php"] 27 ], 28 "fields": ["name"] 29}] 30EOT 31``` 32 33The example above registers a subscription against the specified root with the 34name `mysubscriptionname`. 35 36The response to a subscribe command looks like this: 37 38```json 39{ 40 "version": "1.6", 41 "subscribe": "mysubscriptionname" 42} 43``` 44 45When the subscription is first established, the 46expression term is evaluated and if any files match, a subscription notification 47packet is generated and sent, unilaterally to the client. 48 49Then, each time a change is observed, and after the settle period has passed, 50the expression is evaluated again. If any files are matched, the server will 51unilaterally send the query results to the client with a packet that looks like 52this: 53 54```json 55{ 56 "version": "1.6", 57 "clock": "c:1234:123", 58 "files": ["one.php"], 59 "root": "/path/being/watched", 60 "subscription": "mysubscriptionname" 61} 62``` 63 64The subscribe command object allows the client to specify a since parameter; if 65present in the command, the initial set of subscription results will only 66include files that changed since the specified clockspec, equivalent to using 67the `query` command with the `since` generator. 68 69```json 70["subscribe", "/path/to/root", "myname", { 71 "since": "c:1234:123", 72 "expression": ["not", "empty"], 73 "fields": ["name"] 74}] 75``` 76 77The suggested mode of operation is for the client process to maintain its own 78local copy of the last "clock" value and use that to establish the subscription 79when it first connects. 80 81## Filesystem Settling 82 83Prior to watchman version 3.2, the settling behavior was to hold subscription 84notifications until the kernel notification stream was complete. 85 86Starting in watchman version 3.2, after the notification stream is complete, if 87the root appears to be a version control directory, subscription notifications 88will be held until an outstanding version control operation is complete (at the 89time of writing, this is based on the presence of either `.hg/wlock` or 90`.git/index.lock`). This behavior matches triggers and helps to avoid 91performing transient work in response to files changing, for example, during a 92rebase operation. 93 94In some circumstances it is desirable for a client to observe the creation of 95the control files at the start of a version control operation. You may specify 96that you want this behavior by passing the `defer_vcs` flag to your subscription 97command invocation: 98 99```bash 100$ watchman -j -p <<-EOT 101["subscribe", "/path/to/root", "mysubscriptionname", { 102 "expression": ["allof", 103 ["type", "f"], 104 ["not", "empty"], 105 ["suffix", "php"] 106 ], 107 "defer_vcs": false, 108 "fields": ["name"] 109}] 110EOT 111``` 112 113## Advanced Settling 114 115*Since 4.4* 116 117In more complex integrations it is desirable to be able to have a watchman 118aware application signal the beginning and end of some work that will 119generate a lot of change notifications. For example, Mercurial or Git could 120communicate with watchman before and after updating the working copy. 121 122Some applications will want to know that the update is in progress and 123continue to process notifications. Others may want to defer processing 124the notifications until the update completes, and some may wish to drop 125any notifications produced while the update was in progress. 126 127Watchman subscriptions provide the mechanism for each of these use cases and 128expose it via two new fields in the subscription object; `defer` and `drop` are 129described below. 130 131It can be difficult to mix `defer` and `drop` with multiple overlapping states 132in the context of a given subscription stream as there is a single cursor to 133track the subscription position. 134 135If your application uses multiple overlapping states and wants to `defer` some 136results and `drop` others, it is recommended that you use `drop` for all of 137the states and then issues queries with `since` terms bounded by the `clock` 138fields from the subscription state PDUs to ensure that it observes all of the 139results of interest. 140 141### defer 142 143```json 144["subscribe", "/path/to/root", "mysubscriptionname", { 145 "defer": ["mystatename"], 146 "fields": ["name"] 147}] 148``` 149 150The `defer` field specifies a list of state names for which the subscriber 151wishes to defer the notification stream. When a watchman client signals that 152a state has been entered via the 153[state-enter](/watchman/docs/cmd/state-enter.html) command, if the state name 154matches any in the `defer` list then the subscription will emit a unilateral 155subscription PDU like this: 156 157```json 158{ 159 "subscription": "mysubscriptionname", 160 "root": "/path/to/root", 161 "state-enter": "mystatename", 162 "clock": "<clock>", 163 "metadata": <metadata from the state-enter command> 164} 165``` 166 167Watchman will then defer sending any subscription PDUs with `files` payloads 168until the state is vacated either by a 169[state-leave](/watchman/docs/cmd/state-leave.html) command or by the client 170that entered the state disconnecting from the watchman service. 171 172Once the state is vacated, watchman will emit a unilateral subscription PDU 173like this: 174 175```json 176{ 177 "subscription": "mysubscriptionname", 178 "root": "/path/to/root", 179 "state-leave": "mystatename", 180 "clock": "<clock>", 181 "metadata": <metadata from the exit-state command> 182} 183``` 184 185The subscription stream will then be re-enabled and notifications received 186since the corresponding `state-enter` will be delivered to clients. 187 188### drop 189 190```json 191["subscribe", "/path/to/root", "mysubscriptionname", { 192 "drop": ["mystatename"], 193 "fields": ["name"] 194}] 195``` 196 197The `drop` field specifies a list of state names for which the subscriber 198wishes to discard the notification stream. It works very much like `defer` as 199described above, but when a state is vacated, the pending notification stream 200is fast-forwarded to the clock of the `state-leave` command, effectively 201suppressing any notifications that were generated between the `state-enter` 202and the `state-leave` commands. 203 204## Source Control Aware Subscriptions 205 206*Since 4.9* 207 208[Read more about these here](/watchman/docs/scm-query.html) 209 210