1---
2pageid: cmd.state-leave
3title: state-leave
4layout: docs
5section: Commands
6permalink: docs/cmd/state-leave.html
7---
8
9*Since 4.4*
10
11The `state-leave` command works in conjunction with
12[state-enter](/watchman/docs/cmd/state-enter.html) to facilitate [advanced
13settling in subscriptions](/watchman/docs/cmd/subscribe.html#advanced-settling).
14
15`state-leave` causes a watch to no longer be marked as being in a particular
16named state.
17
18### Examples
19
20This is the simplest example, vacating a state named `mystate`:
21
22```json
23["state-leave", "/path/to/root", "mystate"]
24```
25
26It will cause any subscribers to receive a unilateral subscription PDU from the
27watchman server:
28
29```json
30{
31  "subscription":  "mysubscriptionname",
32  "root":          "/path/to/root",
33  "state-leave":   "mystate",
34  "clock":         "c:1446410081:18462:7:135"
35}
36```
37
38The `clock` field in the response is the (synchronized; see below) clock at the
39time that the state was entered and can be used in subsequent queries, in
40combination with the corresponding `state-enter` subscription PDU clock, to
41locate things that changed while the state was asserted.
42
43A more complex example demonstrates passing metadata to any subscribers.  The
44`metadata` field is propagated through to the subscribers and is not
45interpreted by the watchman server.  It can be any JSON value.
46
47```json
48["state-leave", "/path/to/root", {
49  "name": "mystate",
50  "metadata": {
51    "foo": "bar"
52  }
53}]
54```
55
56This will emit the following unilateral subscription PDU to all subscribers:
57
58```json
59{
60  "subscription":  "mysubscriptionname",
61  "root":          "/path/to/root",
62  "state-leave":   "mystate",
63  "clock":         "c:1446410081:18462:7:137",
64  "metadata": {
65    "foo": "bar"
66  }
67}
68```
69
70### Abandoned State
71
72A state is implicitly vacated when the watchman client session that asserted it
73disconnects.  This helps to avoid breaking subscribers (since the typical
74action is to defer or drop notifications) if the tooling that initiated the
75state terminates unexpectedly.
76
77An abandoned state is reported to any subscribers via a unilateral subscription
78PDU with the `abandoned` field set to `true`:
79
80```json
81{
82  "subscription":  "mysubscriptionname",
83  "root":          "/path/to/root",
84  "state-leave":   "mystate",
85  "clock":         "c:1446410081:18462:7:137",
86  "abandoned":     true
87}
88```
89
90This allows the subscriber to take an appropriate action.
91
92### Synchronization
93
94States are synchronized with the state of the filesystem so that it is
95possible for subscribers to reason about when files changed with respect to
96the state.
97
98This means that issuing a `state-leave` command will [perform query
99synchronization](/watchman/docs/cookies.html#how-cookies-work) to ensure that
100things are in sync.
101
102The `state-leave` command will use a default `sync_timeout` of 60 seconds.
103If the synchronization cookie is not observed within the configured
104`sync_timeout`, an error will be returned and *the state will not be entered*.
105
106In some cases, perhaps during the initial crawl of a very large tree, You may
107specify an alternative value for the timeout; the value is expressed in
108*milliseconds*:
109
110```json
111["state-leave", "/path/to/root", {
112  "name": "mystate",
113  "sync_timeout": 10000,
114  "metadata": {
115    "foo": "bar"
116  }
117}]
118```
119
120You may also specify `0` for the timeout to disable synchronization for this
121particular command.   This may cause the state to appear to clients to have
122been vacated logically before it actually did in the case that there are
123buffered notifications that have not yet been processed by watchman at the time
124that the state was vacated.
125