Add a guide/walkthrough document
- 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
Assessment
This issue has not been assessed yet.