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