doc: added note to fs.watchFile on previousStat

niveditn · addaleax · commit 277438158775 · 2017-10-15T21:59:20.000+02:00
Explains the expected behavior of previousStat in fs.watchFile() when a watched file disappears and reappears. PR-URL: nodejs/node#16099 Fixes: nodejs/node#15364 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Claudio Rodriguez <cjrodr@yahoo.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
diff --git a/doc/api/fs.md b/doc/api/fs.md
@@ -2566,6 +2566,15 @@ v0.10.
 `fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and
 `fs.unwatchFile` when possible.
 
+*Note:* When a file being watched by `fs.watchFile()` disappears and reappears,
+then the `previousStat` reported in the second callback event (the file's
+reappearance) will be the same as the `previousStat` of the first callback
+event (its disappearance).
+
+This happens when:
+- the file is deleted, followed by a restore
+- the file is renamed twice - the second time back to its original name
+
 ## fs.write(fd, buffer[, offset[, length[, position]]], callback)
 <!-- YAML
 added: v0.0.2
