Buck: Document Watchman bug related to symbolic links
Buck has currently one critical bug when Buck daemon is used in
combination with symbolic links: [1]. Document the workaround not
to use Buck daemon in this scenario.
[1] https://github.com/facebook/buck/issues/341
Change-Id: I7cdc19c7245b499e71196d16aab0785dda187fa3
diff --git a/Documentation/dev-buck.txt b/Documentation/dev-buck.txt
index 89cd849..bbc9ae2 100644
--- a/Documentation/dev-buck.txt
+++ b/Documentation/dev-buck.txt
@@ -651,6 +651,22 @@
buck test --no-results-cache
----
+== Known issues and bugs
+
+=== Symbolic links and `watchman`
+
+`Buck` with activated `Watchman` has currently a
+[known bug](https://github.com/facebook/buck/issues/341) related to
+symbolic links. The symbolic links are used very often with external
+plugins, that are linked per symbolic link to the plugins directory.
+With this use case Buck is failing to rebuild the plugin artefact
+after it was built. All attempts to convince Buck to rebuild will fail.
+The only known way to recover is to weep out `buck-out` directory. The
+better workaround is to avoid using Watchman in this specific use case.
+Watchman can either be de-installed or disabled. See
+link:#buck-daemon[Using Buck daemon] section above how to temporarily
+disable `buckd`.
+
== Troubleshooting Buck
In some cases problems with Buck itself need to be investigated. See for example
