doc: added note to fs.watchFile on previousStat

Explains the expected behavior of previousStat in fs.watchFile() when a watched file disappears and reappears. PR-URL: #16099 Fixes: #15364 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Claudio Rodriguez <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Ben Noordhuis <[email protected]>
nodejs · Nov 28, 2017 · 8c070f9 · 8c070f9
1 parent 229a1fa
commit 8c070f9
Showing 1 changed file with 9 additions and 0 deletions.
diff --git a/doc/api/fs.md b/doc/api/fs.md
@@ -1925,6 +1925,15 @@ you need to compare `curr.mtime` and `prev.mtime`.
 `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