Crate watchman_client

This crate provides a client to the watchman file watching service.

Start with the Connector struct and use it to connect and return a Client struct, Client::resolve_root to resolve a path and initiate a watch, and then Client::query to perform a query.

This example shows how to connect and expand a glob from the current working directory:

use watchman_client::*;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
  let mut client = Connector::new().connect().await?;
  let resolved = client
     .resolve_root(CanonicalPath::canonicalize(".")?)
     .await?;

  // Basic globs -> names
  let files = client.glob(&resolved, &["**/*.rs"]).await?;
  println!("files: {:#?}", files);
  Ok(())
}

Macros

query_result_type

A macro to help define a type to hold file information from a query. This macro enables a type-safe way to define the set of fields to be returned and de-serialize only those fields.

Structs

CTimeAsFloatField	The field corresponding to the ctime_f field. ctime is the last inode change time measured in floating point seconds (including the fractional portion) since the unix epoch.
CTimeField	The field corresponding to the ctime field. ctime is the last inode change time measured in integer seconds since the unix epoch.
CanonicalPath	Represents a canonical path in the filesystem.
Client	A live connection to a watchman server. Use Connector to establish a connection.
ClockRequest	The clock command request.
ClockRequestParams
ClockResponse	The clock command response
ClockSpec	The fundamental clock specifier string. The contents of the string should be considered to be opaque to the client as the server occasionally evolves the meaning of the clockspec and its format is expressly not a stable API.
Connector	The Connector defines how to connect to the watchman server. You will typically use Connector::new to set up the connection with the environmental defaults. You might want to override those defaults in situations such as integration testing environments, or in extremely latency sensitive environments where the cost of performing discovery is a measurable overhead.
ContentSha1HexField	The field corresponding to the content.sha1hex field. For regular files this evaluates to the sha1 hash of the file contents.
CreatedClockField	The field corresponding to the cclock field. the cclock is the created clock; the clock value when we first observed the file, or the clock value when it last switched from !exists to exists.
DeviceNumberField	The field corresponding to the dev field. The dev field is the device number expressed as an integer. This field is not meaningful on Windows.
DirNameTerm	Match on the parent directory structure https://facebook.github.io/watchman/docs/expr/dirname.html
ExistsField	The field corresponding to the exists status of the file
FatClockData	Holds extended clock data that includes source control aware query metadata. https://facebook.github.io/watchman/docs/scm-query.html
FileTypeField	The field corresponding to the type field. The type field encodes the type of the file.
GetSockNameResponse	The get-sockname command response
InodeNumberField	The field corresponding to the ino field. The ino field is the inode number expressed as an integer. This field is not meaningful on Windows.
MTimeAsFloatField	The field corresponding to the mtime_f field. mtime is the last modified time measured in floating point seconds (including the fractional portion) since the unix epoch.
MTimeField	The field corresponding to the mtime field. mtime is the last modified time measured in integer seconds since the unix epoch.
MatchTerm	Encodes the match expression term https://facebook.github.io/watchman/docs/expr/match.html
ModeAndPermissionsField	The field corresponding to the mode field. This encodes the full file type and permission bits. Note that most programs and users are more comfortable with this value when printed in octal. It is recommended to use FileTypeField if all you need is the file type and not the permission bits, as it is cheaper to determine just the type in a virtualized filesystem.
NameField	The field corresponding to the name of the file.
NameOnly	Use the NameOnly struct when your desired field list in your query results consist only of the name field. It is not possible to use the query_result_type! macro to define an appropriate type due to limitations in the Rust macro system.
NameTerm	Performs an exact match against the file name. https://facebook.github.io/watchman/docs/expr/name.html
NewField	Deprecated The field corresponding to the new field. The new field evaluates to true if a file is newer than the since generator criteria.
NumberOfLinksField	The field corresponding to the nlink field. The nlink field is the number of hard links to the file expressed as an integer.
ObservedClockField	The field corresponding to the oclock field. the oclock is the observed clock; the clock value where we last observed some change in this file or its metadata.
OwnerGidField	The field corresponding to the gid field. The gid field is the owning gid expressed as an integer. This field is not meaningful on Windows.
OwnerUidField	The field corresponding to the uid field. The uid field is the owning uid expressed as an integer. This field is not meaningful on Windows.
PcreTerm	Use PCRE to match the filename. Note that this is an optional server feature and using this term on a server that doesn't support this feature will generate an error in response to the query. https://facebook.github.io/watchman/docs/expr/pcre.html
QueryRequest	The query request
QueryRequestCommon	The query parameters. There are a large number of fields that influence the behavior.
QueryResult	Holds the result of a query. The result is generic over a F type that you define. The F should deserialize the list of fields in your QueryRequestCommon struct.
ResolvedRoot	Data that describes a watched filesystem location. Watchman performs watch aggregation to project boundaries, so a request to watch a subdirectory will resolve to the higher level root path and a relative path offset. This struct encodes both pieces of information.
SavedStateClockData	Holds extended clock data that includes source control aware query metadata. https://facebook.github.io/watchman/docs/scm-query.html
ScmAwareClockData	Holds extended clock data that includes source control aware query metadata. https://facebook.github.io/watchman/docs/scm-query.html
SizeField	The field corresponding to the size field. This represents the size of the file in bytes.
SymlinkTargetField	The field corresponding to the symlink_target field. For files of type symlink this evaluates to the result of readlink(2) on the file.
WatchProjectRequest	The watch-project command request. You should use Client::resolve_root rather than directly constructing this type.
WatchProjectResponse	The watch-project response

Enums

Clock	A Clock is used to refer to a logical point in time. Internally, watchman maintains a monotonically increasing tick counter along with some additional data to detect A-B-A style situations if eg: the watchman server is restarted.
ContentSha1Hex	Reports the content SHA1 hash for a file. Since computing the hash can fail, this struct can also represent the error that happened during hash computation.
Error
Expr	An expression term used to filter candidate files from query results.
FileType	Encodes the file type field returned in query results and specified in expression terms.
PathGeneratorElement	When using the path generator, this specifies a path to be examined. https://facebook.github.io/watchman/docs/file-query.html#path-generator
RelOp	Specifies a relational comparison with an integer value
SinceTerm	Evaluates as true if the specified time property of the file is greater than the since value. https://facebook.github.io/watchman/docs/expr/since.html