0
# Queries and Change Detection
1

2
Query the daemon for file information and changes, with support for time-based queries, pattern filtering, and advanced expression-based file selection. These commands provide powerful file discovery and change detection capabilities.
3

4
## Capabilities
5

6
### Find Files
7

8
Find all files that match optional patterns under a watched directory.
9

10
```bash { .api }
11
watchman find <path> [patterns...]
12
```
13

14
**JSON Protocol:**
15
```json
16
["find", "/absolute/path", "pattern1", "pattern2", ...]
17
```
18

19
**Parameters:**
20
- `path`: Absolute path to watched directory (required)
21
- `patterns`: Optional filename patterns using glob or regex syntax
22

23
**Response:**
24
```json
25
{
26
  "version": "2.0",
27
  "clock": "c:1234:567",
28
  "files": [
29
    {
30
      "name": "src/main.js",
31
      "exists": true,
32
      "size": 1024,
33
      "mode": 33188
34
    }
35
  ]
36
}
37
```
38

39
**Example:**
40
```bash
41
# Find all files
42
watchman find ~/project
43

44
# Find JavaScript files
45
watchman find ~/project '*.js'
46

47
# Find multiple file types
48
watchman find ~/project '*.js' '*.ts' '*.json'
49

50
# Find with regex patterns
51
watchman find ~/project -p '\.test\.(js|ts)$'
52
```
53

54
### Since Query
55

56
Find files that have changed since a specific clockspec, enabling efficient incremental monitoring.
57

58
```bash { .api }
59
watchman since <path> <clockspec> [patterns...]
60
```
61

62
**JSON Protocol:**
63
```json
64
["since", "/absolute/path", "clockspec", "pattern1", ...]
65
```
66

67
**Parameters:**
68
- `path`: Absolute path to watched directory (required)
69
- `clockspec`: Time specification (clock ID, named cursor, or timestamp)
70
- `patterns`: Optional filename patterns
71

72
**Clockspec formats:**
73
- **Clock ID**: `c:1234:567` (from previous query response)
74
- **Named cursor**: `n:mystate` (client-defined state name)
75
- **Unix timestamp**: `1234567890` (seconds since epoch)
76

77
**Response:**
78
```json
79
{
80
  "version": "2.0", 
81
  "clock": "c:1234:568",
82
  "files": [
83
    {
84
      "name": "src/updated.js",
85
      "exists": true,
86
      "size": 2048,
87
      "mode": 33188,
88
      "mtime": 1234567890,
89
      "new": false,
90
      "cclock": "c:1234:100",
91
      "oclock": "c:1234:568"
92
    }
93
  ]
94
}
95
```
96

97
**File object fields:**
98
- `name`: Relative path to file
99
- `exists`: Whether file currently exists
100
- `size`: File size in bytes
101
- `mode`: Unix file permissions
102
- `mtime`: Modification time (Unix timestamp)
103
- `new`: True if file was newly created since clockspec
104
- `cclock`: Creation clock (when first observed)
105
- `oclock`: Observation clock (when last changed)
106

107
**Example:**
108
```bash
109
# Get changes since named cursor
110
watchman since ~/project n:myapp
111

112
# Get changes since specific clock
113
watchman since ~/project c:1234:567
114

115
# Get changes with patterns
116
watchman since ~/project n:myapp '*.js'
117
```
118

119
### Advanced Query
120

121
Execute complex queries with custom expressions, field selection, and filtering options.
122

123
```bash { .api }
124
# Use JSON input for complex queries
125
watchman -j <<-EOT
126
["query", "/path", {
127
  "expression": [...],
128
  "fields": [...],
129
  "since": "clockspec"
130
}]
131
EOT
132
```
133

134
**JSON Protocol:**
135
```json
136
["query", "/absolute/path", {
137
  "expression": ["expression", "syntax"],
138
  "fields": ["name", "size", "mtime"],
139
  "since": "c:1234:567",
140
  "relative_root": "subdir"
141
}]
142
```
143

144
**Query object parameters:**
145
- `expression`: Query expression for filtering files
146
- `fields`: Array of file metadata fields to return
147
- `since`: Optional clockspec for change-based queries
148
- `relative_root`: Optional subdirectory to query within
149
- `suffix`: Optional file extension filter
150

151
**Available fields:**
152
- `name`: Relative file path
153
- `exists`: File existence flag
154
- `size`: File size in bytes
155
- `mode`: Unix file permissions
156
- `uid`, `gid`: User and group IDs
157
- `mtime`, `ctime`, `atime`: Modification, creation, access times
158
- `ino`: Inode number
159
- `dev`: Device ID
160
- `nlink`: Number of hard links
161
- `new`: True if newly created (since queries only)
162
- `cclock`: Creation clock value
163
- `oclock`: Last observation clock value
164

165
**Default fields:** `["name", "exists", "new", "size", "mode"]`
166

167
**Example:**
168
```bash
169
# Find large JavaScript files
170
watchman -j <<-EOT
171
["query", "/home/user/project", {
172
  "expression": ["allof", 
173
    ["type", "f"],
174
    ["suffix", "js"],
175
    ["size", "gt", 10000]
176
  ],
177
  "fields": ["name", "size"]
178
}]
179
EOT
180

181
# Find recently modified files
182
watchman -j <<-EOT  
183
["query", "/home/user/project", {
184
  "expression": ["since", 1234567890, "mtime"],
185
  "fields": ["name", "mtime", "size"]
186
}]
187
EOT
188

189
# Query subdirectory only
190
watchman -j <<-EOT
191
["query", "/home/user/project", {
192
  "relative_root": "src",
193
  "expression": ["suffix", "js"],
194
  "fields": ["name"]
195
}]
196
EOT
197
```
198

199
## Pattern Syntax
200

201
Watchman supports multiple pattern matching syntaxes:
202

203
### Glob Patterns
204
Standard shell-style wildcards using `fnmatch(3)`:
205
- `*.js` - Files ending in .js
206
- `src/**/*.ts` - TypeScript files in src subdirectories
207
- `test*.py` - Python files starting with "test"
208

209
### Exclusion Patterns
210
Use `!` prefix to exclude matches:
211
- `! *.log` - Exclude log files
212
- `! node_modules` - Exclude node_modules directory
213

214
### Regular Expressions
215
Use `-p` flag for Perl-compatible regex:
216
- `-p '\.test\.(js|ts)$'` - Test files with js/ts extensions
217
- `-p '^src/'` - Files in src directory
218

219
### Case-Insensitive Patterns
220
Use `-P` for case-insensitive regex:
221
- `-P '\.JS$'` - JavaScript files (any case)
222

223
## Clock Management and Named Cursors
224

225
### Clock Values
226
Watchman uses abstract clock values for race-free change detection:
227
- Format: `c:TICKS:PROCESS_ID`
228
- Increments with each file system change
229
- More reliable than timestamps for detecting changes
230

231
### Named Cursors
232
Client-defined names that store clock positions:
233
- `n:myapp_state` - Custom cursor name
234
- Watchman remembers the last clock value for each cursor
235
- Enables stateful incremental queries across client sessions
236

237
**Example workflow:**
238
```bash
239
# First query establishes cursor
240
watchman since ~/project n:myapp
241

242
# Subsequent queries get only new changes
243
watchman since ~/project n:myapp
244
```
245

246
## Error Handling
247

248
Common error conditions:
249

250
- **Root not watched**: Directory must be watched before querying
251
- **Invalid clockspec**: Malformed clock specification
252
- **Invalid expression**: Syntax error in query expression
253
- **Path not found**: Specified path does not exist
254
- **Permission denied**: Insufficient access to directory or files