Struct watchman_client::pdu::QueryRequestCommon

pub struct QueryRequestCommon {
    pub glob: Option<Vec<String>>,
    pub glob_noescape: bool,
    pub glob_includedotfiles: bool,
    pub path: Option<Vec<PathGeneratorElement>>,
    pub suffix: Option<Vec<PathBuf>>,
    pub since: Option<Clock>,
    pub relative_root: Option<PathBuf>,
    pub expression: Option<Expr>,
    pub fields: Vec<&'static str>,
    pub empty_on_fresh_instance: bool,
    pub fail_if_no_saved_state: bool,
    pub case_sensitive: bool,
    pub sync_timeout: SyncTimeout,
    pub dedup_results: bool,
    pub lock_timeout: Option<i64>,
    pub request_id: Option<String>,
}

The query parameters. There are a large number of fields that influence the behavior.

A query consists of three phases:

1. Candidate generation
2. Result filtration (using the expression term)
3. Result rendering

The generation phase is explained in detail here: https://facebook.github.io/watchman/docs/file-query.html#generators

Note that it is legal to combine multiple generators but that it is often undesirable to do so. Not specifying a generator results in the default "all-files" generator being used to iterate all known files.

The filtration and expression syntax is explained here: https://facebook.github.io/watchman/docs/file-query.html#expressions

Fields

glob: Option<Vec<String>>

If set, enables the glob generator and specifies a set of globs that will be expanded into a list of file names and then filtered according to the expression field.

glob_noescape: bool

If using the glob generator and set to true, do not treat the backslash character as an escape sequence

glob_includedotfiles: bool

If using the glob generator and set to true, include files whose basename starts with . in the results. The default behavior for globs is to exclude those files from the results.

path: Option<Vec<PathGeneratorElement>>

If set, enables the use of the path generator. https://facebook.github.io/watchman/docs/file-query.html#path-generator

suffix: Option<Vec<PathBuf>>

If set, enables the use of the suffix generator, and specifies the list of filename suffixes. In virtualized filesystems this can result in an expensive O(project) filesystem walk, so it is strongly recommended that you scope this to a relatively shallow subdirectory.

https://facebook.github.io/watchman/docs/file-query.html#suffix-generator

since: Option<Clock>

If set, enables the use of the since generator and specifies the last time you queried the server and for which you wish to receive a delta of changes. You will typically thread the QueryResult.clock field back to a subsequent since query to process the continuity of matching file changes. https://facebook.github.io/watchman/docs/file-query.html#since-generator

relative_root: Option<PathBuf>

if set, indicates that all input paths are relative to this subdirectory in the project, and that all returned filenames will also be relative to this subdirectory. In large virtualized filesystems it is undesirable to leave this set to None as it makes it more likely that you will trigger an O(project) filesystem walk. This field is set automatically from the ResolvedRoot when you perform queries using Client::query.

expression: Option<Expr>

If set, specifies the expression to use to filter the candidate matches produced by the selected query generator. Each candidate is visited in turn and has the expression applied. Candidates for which the expression evaluates as true will be included in the returned list of files. If left unspecified, the server will assume Expr::True.

fields: Vec<&'static str>

Specifies the list of fields names returned by the server. The name field should be considered a required field and is the cheapest field to return. Depending on the watcher implementation, other metadata has varying cost. In general, avoid querying size and mode fields and instead prefer to query content.sha1hex and type instead to avoid materializing inodes in a virtualized filesystem.

empty_on_fresh_instance: bool

If true you indicate that you know how to 100% correctly deal with a fresh instance result set. It is strongly recommended that you leave this option alone as it is a common source of cache invalidation and divergence issues for clients.

fail_if_no_saved_state: bool

When requesting saved state information via SavedStateClockData, if fail_if_no_saved_state is set to true, the server will generate a query error in the case that the merge base change and no appropriate saved state could be found. Otherwise, the default behavior is to perform a normal watchman since query that may return a large number of changed files.

case_sensitive: bool

If true, treat filenames as case sensitive even on filesystems that otherwise appear to be case insensitive. This can improve performance of directory traversal in queries by turning O(directory-size) operations into an O(1) hash lookup. https://facebook.github.io/watchman/docs/cmd/query.html#case-sensitivity

sync_timeout: SyncTimeout

If set, override the default synchronization timeout. The timeout controls how long the server will wait to observe a cookie file through the notification stream. If the timeout is reached, the query will fail.

Specify SyncTimeout::DisableCookie to tell the server not to use a sync cookie. Disabling sync cookies means that your query results may be slightly out of date. You can safely perform a query with sync cookies disabled if you have explicitly synchronized. For example, you can perform a synchronized Client::clock call at the start of your processing run to ensure that the server is current up to that point in time, and then issue a large volume of additional queries with the sync cookie disabled and save approximately ~15ms of latency per query.

See also:

• https://facebook.github.io/watchman/docs/cookies.html
• https://facebook.github.io/watchman/docs/cmd/query.html#synchronization-timeout-since-21

dedup_results: bool

If set to true, when mixing generators (not recommended), dedup results by filename. This defaults to false. When not enabled, if multiple generators match the same file, it will appear twice in the result set. Turning on dedup_results will increase the memory cost of processing a query and build an O(result-size) hash map to dedup the results.

lock_timeout: Option<i64>

Controls the duration that the server will wait to obtain a lock on the filesystem view. You should not normally need to change this. https://facebook.github.io/watchman/docs/cmd/query.html#lock-timeout

request_id: Option<String>

If set, records the request_id in internal performance sampling data. It is also exported through the environment as HGREQUESTID so that the context of the request can be passed down to any child mercurial processes that might be spawned as part of processing source control aware queries.

Trait Implementations

impl Clone for QueryRequestCommon

fn clone(&self) -> QueryRequestCommon

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QueryRequestCommon

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for QueryRequestCommon

fn default() -> QueryRequestCommon

Returns the "default value" for a type.

impl Serialize for QueryRequestCommon

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.