1---
2pageid: cmd.flush-subscriptions
3title: flush-subscriptions
4layout: docs
5section: Commands
6permalink: docs/cmd/flush-subscriptions.html
7---
8
9*Since 4.8.*
10
11Flushes buffered updates to subscriptions associated with the current
12session, guaranteeing that they are up-to-date as of the time Watchman
13received the `flush-subscriptions` command.
14
15Subscription updates will be interleaved between the `flush-subscriptions`
16request and its response. Once the response has been received, subscriptions are
17up-to-date.
18
19This command is designed to be used by interactive programs that have a
20background process or daemon maintaining a subscription to Watchman. The typical
21pattern is for interactive commands to be forwarded to the process, which calls
22`flush-subscriptions` and then processes any subscription updates it received.
23This pattern eliminates races with files changed right before the interactive
24command.
25
26### Arguments
27
28* `sync_timeout`: Required. The number of milliseconds to wait to observe a
29  synchronization cookie. The synchronization cookie is created at the start of
30  the `flush-subscriptions` call, and once the cookie is observed, means that
31  the OS has sent watchman all the updates till at least the start of the
32  `flush-subscriptions` call.
33* `subscriptions`: Optional. Which subscriptions to flush. By default this
34  flushes all subscriptions associated with this project on this session.
35
36### Examples
37
38Assuming subscriptions `sub1`, `sub2` and `sub3` have been established on this
39session, if `sub1` has updates pending, `sub2` is up-to-date and `sub3` is
40currently dropping updates:
41
42```json
43["flush-subscriptions", "/path/to/root", {"sync_timeout": 1000}]
44```
45
46In response, Watchman will first emit a unilateral subscription PDU for `sub1`,
47then respond with
48
49```json
50{
51  "clock": "c:1446410081:18462:7:135",
52  "synced": ["sub1"],
53  "no_sync_needed": ["sub2"],
54  "dropped": ["sub3"]
55}
56```
57
58To flush updates for some but not all subscriptions associated with this
59session:
60
61```json
62["flush-subscriptions", "/path/to/root",
63  {
64    "sync_timeout": 1000,
65    "subscriptions": ["sub1", "sub2"]
66  }
67]
68```
69
70### Deferred and Dropped Updates
71
72Subscriptions will typically buffer individual updates until a *settle* period
73has expired. `flush-subscriptions` will force those updates through immediately.
74
75Subscriptions currently deferring updates because of `defer` or `defer_vcs`
76are updated immediately, without waiting for the `defer` or `defer_vcs` to
77end.
78
79Subscriptions currently dropping updates with a `drop` state will not get any
80updates. Their names will be returned in the `dropped` field.
81
82### Notes
83
84* `flush-subscriptions` can only be used to flush subscriptions associated with
85  the current session.
86* A single session can be subscribed to updates from multiple projects at the
87  same time. However, `flush-subscriptions` can only flush updates for one
88  project at a time.
89