From 14e2d67776e0210baebdda571785def39b578c2c Mon Sep 17 00:00:00 2001 From: Dan Fabulich Date: Wed, 31 Aug 2016 16:10:04 -0700 Subject: [PATCH] fs,doc: undeprecate existsSync MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This has been dragged through various long discussions and has been elevated to the CTC multiple times. As noted in https://github.com/nodejs/node/pull/7455#issuecomment-228961530, while this API is still generally considered an anti-pattern, there are still use-cases it is best suited for, such as checking if a git rebase is in progress by looking if ".git/rebase-apply/rebasing" exists. The general consensus is to undeprecate just the sync version, given that the async version still has the "arguments order inconsistency" problem. The consensus at the two last CTC meetings this came up at was also to undeprecate existsSync() but keep exists() deprecated. See: https://github.com/nodejs/node/issues/8242 & https://github.com/nodejs/node/issues/8330 (Description write-up by @Fishrock123) Fixes: https://github.com/nodejs/node/issues/1592 Refs: https://github.com/nodejs/node/pull/4217 Refs: https://github.com/nodejs/node/pull/7455 PR-URL: https://github.com/nodejs/node/pull/8364 Reviewed-By: James M Snell Reviewed-By: Ilkka Myller Reviewed-By: Matteo Collina Reviewed-By: Benjamin Gruenbaum Reviewed-By: Сковорода Никита Андреевич Reviewed-By: Jeremiah Senkpiel --- doc/api/fs.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 99e23e7a5a0f53..6bfc0e4e6788c3 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -693,6 +693,12 @@ fs.exists('/etc/passwd', (exists) => { }); ``` +**Note that the parameter to this callback is not consistent with other +Node.js callbacks.** Normally, the first parameter to a Node.js callback is +an `err` parameter, optionally followed by other parameters. The +`fs.exists()` callback has only one boolean parameter. This is one reason +`fs.access()` is recommended instead of `fs.exists()`. + Using `fs.exists()` to check for the existence of a file before calling `fs.open()`, `fs.readFile()` or `fs.writeFile()` is not recommended. Doing so introduces a race condition, since other processes may change the file's @@ -774,17 +780,18 @@ process. ## fs.existsSync(path) -> Stability: 0 - Deprecated: Use [`fs.statSync()`][] or [`fs.accessSync()`][] -> instead. - * `path` {String | Buffer} Synchronous version of [`fs.exists()`][]. Returns `true` if the file exists, `false` otherwise. +Note that `fs.exists()` is deprecated, but `fs.existsSync()` is not. +(The `callback` parameter to `fs.exists()` accepts parameters that are +inconsistent with other Node.js callbacks. `fs.existsSync()` does not use +a callback.) + ## fs.fchmod(fd, mode, callback)