1 files changed, 18 insertions, 0 deletions
diff --git a/docs/examples/file_system_events.md b/docs/examples/file_system_events.md
new file mode 100644
index 000000000..2abebc33e
--- /dev/null
+++ b/docs/examples/file_system_events.md
@@ -0,0 +1,18 @@
+### File system events
+
+To poll for file system events:
+
+```ts
+const watcher = Deno.watchFs("/");
+for await (const event of watcher) {
+  console.log(">>>> event", event);
+  // { kind: "create", paths: [ "/foo.txt" ] }
+}
+```
+
+Note that the exact ordering of the events can vary between operating systems.
+This feature uses different syscalls depending on the platform:
+
+- Linux: inotify
+- macOS: FSEvents
+- Windows: ReadDirectoryChangesW