docs: fs: stat.isDirectory: added clarification

[coderaiser]

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

Added clarification to documentation, similar to one describes stat.isSymbolicLink which tells that
This method is only valid when using fs.lstat().

When use fs.lstat for a symbolic link to a directory it will return stat which isDirectory will always be false. This is not really obvious, and because of this both methods stat and lstat should be called to get true information about symbolic link to a directory.

Let's create symbolic link to root directory.

ln -s / 123
node

And then run in REPL:

> fs.statSync('123').isDirectory()
true
> fs.statSync('123').isSymbolicLink()
false
> fs.lstatSync('123').isDirectory()
false
> fs.lstatSync('123').isSymbolicLink()
true

[sam-github]

Sorry, this documentation isn't correct.

I'm not clear why you think it's not valid when using lstat(). lstat gets information for the link itself, and the link is not a directory (it's a link). From your code, I could equally (wrongly) say that isDirectory() is invalid when using stat(), because when you call stat('123'), 123 is not a directory, its a link, so isDirectory() should be false (but I wouldn't say that! it ignores the stat docs, which says it follows links).

You are also missing a test in the code you posted: call lstat() on /, and then call isDirectory, it will return true, which is valid, in contradiction of the sentence you added.

Is it possible you are just confused about the difference between stat and lstat? Perhaps some additional text is needed there? Or did you miss this sentence?

lstat() is identical to stat(), except that if path is a symbolic link, then the link itself is stat-ed, not the file that it refers to.

[coderaiser]

The thing is I'm working on a file manager, and use readify to get file list with attributes, such as size, type, mode, date.
There is regular files, and directories.
There is symlinks to files, and symlinks to a directories.
How do you think the last two should be distinguished if stat returns information about type (file/directory) and do not return information about is it symbolic link. and lstat do this vice versa.

I have stepped on this rake a lot times, so I propose to clarify this thing in documentation because it is not obvious. I understand the difference, but I don't know why do I should always remember this :). If everyone else always remember the difference, we can close the issue, I just thought that it's a good idea for improvement and that it can help people who see this stat, lstat stuff for the first time.

Also superstat can help not think at all about this.

[sam-github]

Sorry, still not quite understanding.

There is regular files, and directories.
There is symlinks to files, and symlinks to a directories.
How do you think the last two should be distinguished if stat returns information about type (file/directory) and do not return information about is it symbolic link. and lstat do this vice versa.

Most users don't want to know a path is a symlink, they want whatever they do to happen to the thing pointed to. In other words, whether they open (get stat, whatever) usgin a path to a file or to a symlink to a file, they don't want to know. fs.stat() (and fs.open()), etc., are all built for this kind of user.

If you are writing code that actually needs to know both that a path is a symlink, and what the link points to, then you need to make two stat calls. Always use fs.lstat() first, and if fs.isSymbolicLink() is true, (and you care about the file it links to), then call fs.stat() on the same path, and now you know everything there is to know about the two entities.

If I understand you correctly, you are hoping for some kind of "fs.Stats" structure to be returned that tells you both about the entity pointed to (its size, its inode, the device it is on, its creation time, owner, etc), and whether the path used to get that info went through symlink resolution. That's just not possible. Not structurally, because each property can have a different value for the symlink vs the entity it points to, so the structure doesn't work. Also, not possible because the POSIX system call to do a one-shot "get info on two things" don't exist.

In terms of naming, "lstat" gets the stat for the link itself ("l"), "stat" gets the stat for what the link points to, as most people want. I'm not going to say the names couldn't be more memorable, but they exactly mirror the UNIX system API names, so using the traditional name seems better than inventing a new one, and is consistent with the rest of the fs API.

I'm also not going to say the docs couldn't get better, I'm sure they can, but this particular change is inaccurate. The lstat vs stat distinction applies to ALL of fs.Stat, but you have singled out isDirectory as if its somehow special (it is not).

Perhaps a note right at the top of the fs.Stat class docs that refers to the two APIs that return it (stat and lstat), and mention that depending on the API used, Stat will either refer to the link itself, or the entity it points to, would be a more helpful change.

[coderaiser]

@sam-github I updated commit in accordance to changes you requested.

[sam-github]

The lstat vs stat distinction applies to ALL of fs.Stat, but you have singled out isDirectory as if its somehow special (it is not).

Your text is more clear, thank you, but the above problem is not fixed.

I suggest moving the text, as I requested:

Perhaps a note right at the top of the fs.Stat class docs that refers to the two APIs that return it (stat and lstat), and mention that depending on the API used, Stat will either refer to the link itself, or the entity it points to, would be a more helpful change.

[HarshithaKP]

What are the next steps on this PR ? and this needs a rebase.

[coderaiser]

What are the next steps on this PR ? and this needs a rebase.

Rebase is done :).

[jasnell]

@coderaiser ... the "merge commit" needs to be dropped. We do not use merge commits. Instead we use git rebase instead. Let us know if you need some help with that.

[coderaiser]

@jasnell rebase is done, now without merge commit :)

[jasnell]

Ping @sam-github ... does this look good to you now?

[aduh95]

Landed in 6c3326c