watchman

README

Go Watchman Client

This Go module provides a client for Facebook's Watchman, a file watching service with support for recording and querying filesystem state. Two alternative APIs are provided. The high-level API is designed for common use cases. The low-level API is designed to enable advanced use cases.

Frequently Asked Questions

Why use Watchman instead of fsnotify/inotify/kevent/etc?

• Watchman conserves system resources by enabling applications to share watches instead of duplicating them.
• Watchman waits for changes to settle down before sending notifications.
• Watchman can also be queried for changes since a previous check, or queried for current filesystem state.
• Watchman has been battle hardened by use in projects such as Buck, Mercurial, and React Native.

Are all Watchman features supported?

All primitives necessary to access the full Watchman protocol are implemented, however this project is still a work in progress. Most Watchman commands still need to be mapped to more friendly data structures and methods. In addition, the eventual replacement of JSON ecoding with more efficient BSER encoding is planned but not yet implemented.

For details, see docs/status.md.

Roadmap

This is a personal project. I work on it when I feel like it. The following is a list of things I might work on. It is not a list of commitments.

Contributions are welcome.

0.3

• improved test coverage
• start testing on Windows
• expose existing command options

0.4

• support additional commands

Contributing

pre-commit install

Additional Resources

https://facebook.github.io/watchman/docs/install.html

https://www.facebook.com/notes/facebook-engineering/watchman-faster-builds-with-large-source-trees/10151457195103920/

Documentation

Overview

Package watchman provides tools to communicate with the Watchman file watching service. https://facebook.github.io/watchman/

Index

• type ChangeNotification
• type Client
  • func Connect() (c *Client, err error)
  • func (c *Client) AddWatch(path string) (*Watch, error)
  • func (c *Client) Close() error
  • func (c *Client) HasCapability(capability string) bool
  • func (c *Client) ListWatches() (roots []string, err error)
  • func (c *Client) Notifications() <-chan interface{}
  • func (c *Client) SockName() string
  • func (c *Client) Version() string
• type Subscription
  • func (s *Subscription) Unsubscribe() (err error)
• type Watch
  • func (w *Watch) Clock(syncTimeout time.Duration) (string, error)
  • func (w *Watch) RelativePath() string
  • func (w *Watch) Root() string
  • func (w *Watch) Subscribe(name string, query *query.Query) (s *Subscription, err error)

Types

type ChangeNotification

type ChangeNotification struct {
	IsFreshInstance bool
	Clock           string
	Subscription    string
	Files           []interface{}
}

A ChangeNotification represents changes two one or more filesystem entries.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client provides a high-level interface to Watchman.

func Connect

func Connect() (c *Client, err error)

Connect connects to or starts the Watchman server and returns a new Client.

func (*Client) AddWatch

func (c *Client) AddWatch(path string) (*Watch, error)

AddWatch requests that the Watchman server monitor a directory for changes.

Please note that Watchman may reuse an existing watch, or choose to start watching a parent of the requested directory.

For details, see: https://facebook.github.io/watchman/docs/cmd/watch-project.html

func (*Client) Close

func (c *Client) Close() error

Close closes the connection to the Watchman server.

func (*Client) HasCapability

func (c *Client) HasCapability(capability string) bool

HasCapability checks if the Watchman server supports a feature.

For details, see: https://facebook.github.io/watchman/docs/capabilities.html

func (*Client) ListWatches

func (c *Client) ListWatches() (roots []string, err error)

ListWatches returns a list of directories that Watchman is monitoring.

func (*Client) Notifications

func (c *Client) Notifications() <-chan interface{}

Notifications returns a channel that emits unilateral messages from the Watchman server.

func (*Client) SockName

func (c *Client) SockName() string

SockName returns the location of then UNIX domain socket used to communicate with the Watchman server.

func (*Client) Version

func (c *Client) Version() string

Version returns the version of the Watchman server.

type Subscription

type Subscription struct {
	// contains filtered or unexported fields
}

A Subscription represents a request to receive notification of changes to a watched root.

func (*Subscription) Unsubscribe

func (s *Subscription) Unsubscribe() (err error)

Unsubscribe cancels a subscription.

type Watch

type Watch struct {
	// contains filtered or unexported fields
}

A Watch represents a directory, or watched root, that Watchman is watching for changes.

func (*Watch) Clock

func (w *Watch) Clock(syncTimeout time.Duration) (string, error)

Clock returns the current clock value for a watched root.

For details, see: https://facebook.github.io/watchman/docs/cmd/clock.html

func (*Watch) RelativePath

func (w *Watch) RelativePath() string

func (*Watch) Root

func (w *Watch) Root() string

func (*Watch) Subscribe

func (w *Watch) Subscribe(name string, query *query.Query) (s *Subscription, err error)

Subscribe requests notification when changes occur under a watched root.