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