1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
---
pageid: cmd.query
title: query
layout: docs
section: Commands
permalink: docs/cmd/query.html
---
*Since 1.6.*
```bash
$ watchman -j <<-EOT
["query", "/path/to/root", {
"suffix": "php",
"expression": ["allof",
["type", "f"],
["not", "empty"],
["ipcre", "test", "basename"]
],
"fields": ["name"]
}]
EOT
```
Executes a query against the specified root. This example uses the `-j` flag to
the watchman binary that tells it to read stdin and interpret it as the JSON
request object to send to the watchman service. This flag allows you to send
in a pretty JSON object (as shown above), but if you're using the socket
interface you must still format the object as a single line JSON request as
documented in the protocol spec.
The first argument to query is the path to the watched root. The second
argument holds a JSON object describing the query to be run. The query object
is processed by passing it to the query engine (see [File Queries](
/watchman/docs/file-query.html)) which will generate a set of matching files.
The query command will then consult the `fields` member of the query object;
if it is not present it will default to:
```json
"fields": ["name", "exists", "new", "size", "mode"]
```
For each file in the result set, the query command will generate a JSON object
value populated with the requested fields. For example, the default set of
fields will return a response something like this:
```json
{
"version": "2.9",
"clock": "c:80616:59",
"is_fresh_instance": false,
"files": [
{
"exists": true,
"mode": 33188,
"new": false,
"name": "argv.c",
"size": 1340,
}
]
}
```
For queries using the `since` generator, the `is_fresh_instance` member is true
if the particular clock value indicates that it was returned by a different
instance of watchman, or a named cursor hasn't been seen before. In that case,
only files that currently exist will be returned, and all files will have `new`
set to `true`. For all other queries, is_fresh_instance will always be true.
Advanced users may set the input parameter `empty_on_fresh_instance` to true,
in which case no files will be returned for fresh instances.
If the `fields` member consists of a single entry, the files result will be a
simple array of values; ```"fields": ["name"]``` produces:
```json
{
"version": "1.5",
"clock": "c:80616:59",
"files": ["argv.c", "foo.c"]
}
```
### Available fields
* `name` - string: the filename, relative to the watched root
* `exists` - bool: true if the file exists, false if it has been deleted
* `cclock` - string: the "created clock"; the clock value when we first
observed the file, or the clock value when it last switched from
!exists to exists.
* `oclock` - string: the "observed clock"; the clock value where we last
observed some change in this file or its metadata.
* `ctime`, `ctime_ms`, `ctime_us`, `ctime_ns`, `ctime_f` -
last inode change time measured in integer seconds, milliseconds,
microseconds, nanoseconds or floating point seconds respectively.
* `mtime`, `mtime_ms`, `mtime_us`, `mtime_ns`, `mtime_f` -
modified time measured in integer seconds, milliseconds,
microseconds, nanoseconds or floating point seconds respectively.
* `size` - integer: file size in bytes
* `mode` - integer: file (or directory) mode expressed as a decimal integer
* `uid` - integer: the owning uid
* `gid` - integer: the owning gid
* `ino` - integer: the inode number
* `dev` - integer: the device number
* `nlink` - integer: number of hard links
* `new` - bool: whether this entry is newer than the `since` generator criteria
*Since 3.1.*
* `type` - string: the file type. Has the
the values listed in [the type query expression](../expr/type.html)
*Since 4.6.*
* `symlink_target` - string: the target of a symbolic link if the file is a
symbolic link
### Synchronization timeout (since 2.1)
By default a `query` will wait for up to 60 seconds for the view of the
filesystem to become current. Watchman decides that the view is current by
creating a cookie file and waiting to observe the notification that it is
present. If the cookie is not observed within the sync_timeout period then the
query invocation will error out with a synchronization error message.
If your synchronization requirements differ from the default, you may pass in
your desired timeout when you construct your query; it must be an integer value
expressed in milliseconds:
```json
["query", "/path/to/root", {
"expression": ["exists"],
"fields": ["name"],
"sync_timeout": 60000
}]
```
You may specify `0` as the value if you do not wish for the query to create
a cookie and synchronize; the query will be evaluated over the present view
of the tree, which may lag behind the present state of the filesystem.
### Lock timeout
*Since 4.6.*
By default queries will wait for up to 60 seconds to acquire a lock to inspect
the view of the filesystem tree. In practice, this timeout should never be hit
(it is indicative of an environmental or load related issue). However, in some
situations it is important to ensure that the query attempt times out sooner
than this. You may use the `lock_timeout` field to control this behavior.
`lock_timeout` must be an integer value expressed in milliseconds:
```json
["query", "/path/to/root", {
"expression": ["exists"],
"fields": ["name"],
"lock_timeout": 60000,
"sync_timeout": 60000
}]
```
Prior to version 4.6, the `lock_timeout` could not be configured and had an
effective value of infinity.
### Case sensitivity
*Since 2.9.9.*
On systems where the watched root is a case insensitive filesystem (this is the
common case for OS X and Windows), various name matching operations default to
case insensitive.
*Since 4.7.*
You may override the case sensitivity of the various name matching operations
by setting the `case_sensitive` field in your query spec. It default to the
case sensitivity of the watched root. This is useful in cases where you know
that the contents of the tree are treated case sensitively by your various
tools but are running on a case insensitive filesystem. By forcing the name
matches to case sensitive mode the matches are faster and in some cases can be
accelerated by using alternative algorithms.
```bash
$ watchman -j <<-EOT
["query", "/path/to/root", {
"suffix": "php",
"expression": ["match", "foo*.c", "basename"],
"case_sensitive": true,
"fields": ["name"]
}]
EOT
```
|
