{
  "slug": "watchman-clock",
  "term": "Watchman clock",
  "aliases": [
    "Watchman clockspec"
  ],
  "definition": "A Watchman clock is an opaque position in a watched root's observed change history used to request subsequent changes.",
  "note": "Continuity: a since query can report is_fresh_instance when its prior history is no longer usable. Default fresh results include currently existing matching files, not old deletion records. With empty_on_fresh_instance, the list is deliberately empty; the flag still signals lost continuity. [query]\n\nConsumer state: applying a fresh baseline as an ordinary delta can retain deleted names. A controlled Watchman 4.9.0 root-reset experiment reproduced this; replacing the complete queried scope recovered membership in a quiescent fixture. This is name-index recovery, not a file-content snapshot. [hesela]\n\nAcknowledgement: named cursors advance on query and cannot be rolled back. Explicit clocks allow retry from an earlier observation position while history remains valid. Committing a cursor before applying its results can make a subsequent empty response hide unprocessed changes. [clocks] [hesela]\n\nSynchronization: a clock call without sync_timeout can precede pending filesystem notifications. A synchronization cookie improves observation freshness but does not freeze application writes. [clock]\n\nSelection: retain the query scope with the client index and clock. In a separate 18-execution quiescent test, broadening a suffix filter missed an unchanged name and narrowing retained an excluded name, despite empty non-fresh responses. A full query under the new selection recovered exact membership. [scope] [hesela]",
  "status": "shipping",
  "supersedes": [],
  "supersededBy": [],
  "firstSeen": null,
  "lastSeen": null,
  "updated": "2026-10-21",
  "advantages": [
    "Allows clients to resume change queries from an explicit observation position."
  ],
  "limitations": [
    "Retained change history and the consumer's committed index must remain consistent."
  ],
  "related": [
    "inotify",
    "directory-enumeration",
    "incremental-backup"
  ],
  "citations": [
    {
      "id": "query",
      "title": "Watchman query: fresh instances and synchronization",
      "url": "https://facebook.github.io/watchman/docs/cmd/query",
      "accessed": "2026-10-21"
    },
    {
      "id": "clocks",
      "title": "Watchman clockspec: explicit clocks and named cursors",
      "url": "https://facebook.github.io/watchman/docs/clockspec",
      "accessed": "2026-10-21"
    },
    {
      "id": "clock",
      "title": "Watchman clock: synchronization option",
      "url": "https://facebook.github.io/watchman/docs/cmd/clock",
      "accessed": "2026-10-21"
    },
    {
      "id": "hesela",
      "title": "Hesela: change-history continuity and client index recovery",
      "url": "https://hesela.com/analyses/inotify-change-detection/#watchman-continuity",
      "accessed": "2026-10-21"
    },
    {
      "id": "scope",
      "title": "Watchman File Queries: generators and expressions",
      "url": "https://facebook.github.io/watchman/docs/file-query",
      "accessed": "2026-10-21"
    }
  ],
  "provenance": [
    "Documentation synthesis and controlled native observations on Ubuntu's Watchman 4.9.0-7build4 package.",
    "The experiment does not measure a current release, overflow, automatic recrawl, history aging or backup completeness."
  ]
}