third-party/watchman/src/website/_docs/cmd.query.markdown

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