facebook / facebook/watchman

Add a guide/walkthrough document

Open
#753 2 comments 4 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
13.7k
Forks
1.1k
PR merge metrics
No merged PRs in 30d

Description

Hi!

First off all, let me say thank you for maintaining awesome docs for watchman: they are really thorough, and are greatly appreciated!

However, when I was recently familiarizing myself with watchmen, I've noticed that it took me a long time to get a solid understanding of the big picture. It looks like the docs do a good job at providing a comprehensive reference, but don't have a guide-like page which talks about all the concepts of watchman and how they relate to each other. I might want to use watchmen in [rust-analyzer](https://github.com/rust-analyzer/rust-analyzer), an experimental language server for rust, and for me it is important to understand how watchman works as a whole, rather than to figure out how to do a specific thing, like running a command if a css files changes.

Here are some concepts which I struggled with painting clearly in my mind:

* clocks
* roots (especially, what happens if a set of roots changes dynamically)
* guarantees that are provided by watchman (ie, initial scan makes sure that no file is missed)
* ways to interact with watchman (it is a daemon, but the docs mainly talk about CLI tool, but there's also a socket interface)

I think that the pages which helped me most were:

* https://facebook.github.io/watchman/docs/socket-interface.html
* https://facebook.github.io/watchman/docs/cmd/watch-project.html
* https://facebook.github.io/watchman/docs/cmd/query.html
* https://facebook.github.io/watchman/docs/clockspec.html
* https://facebook.github.io/watchman/docs/file-query.html
* https://facebook.github.io/watchman/docs/cmd/subscribe.html

It would awesome if there was a centralized document which talks, in brief, about each one of them.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.