GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — doc: clarify how fs.Dirent file types are determined by soreavis · Pull Request #64532 · nodejs/node

Conversation

@soreavis

@soreavis soreavis commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

The fs.Dirent docs don't say where entry file types come from — the confusion in #30646, where the type reported on a remotely mounted file system didn't match lstat() and @addaleax suggested documenting that "the type of the entry may be dependent on the file system and operating system". This adds one paragraph to the fs.Dirent class intro: the type of an entry from a directory read is the type reported by the operating system, it may depend on the file system, lstat() is only used as a fallback when the reported type is unknown, and fs.lstat() is the accurate alternative.

Verified against lib/internal/fs/utils.js (getDirent/getDirents fall back to lstat only on UV_DIRENT_UNKNOWN) and src/node_file.cc (the type comes from uv_fs_scandir_next, no stat call). The wording is scoped to directory reads (fs.readdir(), fs.opendir()) because fs.glob() with withFileTypes builds its dirents from lstat() directly.

I used an AI assistant while researching and drafting this change; I've verified the behavior and the wording against the source myself and take full responsibility for it.

Fixes: #30646

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@soreavis
doc: clarify how fs.Dirent file types are determined
b070d02
The file type of a directory entry returned by fs.readdir() or
fs.opendir() is the type reported by the operating system's directory
listing. Node.js falls back to lstat() only when the reported type is
unknown, and some file systems may report a type that differs from what
lstat() would return. Document this in the fs.Dirent class introduction,
with fs.lstat() as the accurate alternative.

Fixes: nodejs#30646
Signed-off-by: Julian Soreavis <[email protected]>
@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to Node.js documentation. fs Issues and PRs related to file-system APIs and the fs module. labels Jul 16, 2026
@soreavis soreavis mentioned this pull request Jul 16, 2026
readdir(p, { withFileTypes: true }) seemingly returns wrong type #30646
Closed
lpinca
lpinca approved these changes Jul 18, 2026
View reviewed changes

@lpinca lpinca left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RSLGTM

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@trivikr

trivikr commented Aug 18, 2026

Copy link
Copy Markdown
Member

cc @nodejs/fs

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

jazelly
jazelly approved these changes Aug 18, 2026
View reviewed changes
@trivikr trivikr added the commit-queue PRs queued for automated landing through the Commit Queue. label Aug 18, 2026
@nodejs-github-bot
nodejs-github-bot merged commit 29a083c into nodejs:main Aug 18, 2026
27 checks passed

Uh oh!

There was an error while loading. Please reload this page.

@nodejs-github-bot

nodejs-github-bot commented Aug 18, 2026

Copy link
Copy Markdown
Collaborator

Landed in 29a083c

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@nodejs-github-bot nodejs-github-bot removed the commit-queue PRs queued for automated landing through the Commit Queue. label Aug 18, 2026
@anonrig anonrig mentioned this pull request Aug 18, 2026
tools: keep multi-commit PRs in the commit queue #65386
Closed
aduh95 pushed a commit that referenced this pull request Aug 25, 2026
@soreavis @aduh95
doc: clarify how fs.Dirent file types are determined
c28bcfb
The file type of a directory entry returned by fs.readdir() or
fs.opendir() is the type reported by the operating system's directory
listing. Node.js falls back to lstat() only when the reported type is
unknown, and some file systems may report a type that differs from what
lstat() would return. Document this in the fs.Dirent class introduction,
with fs.lstat() as the accurate alternative.

Fixes: #30646
Signed-off-by: Julian Soreavis <[email protected]>
PR-URL: #64532
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jason Zhang <[email protected]>
aduh95 pushed a commit that referenced this pull request Aug 25, 2026
@soreavis @aduh95
doc: clarify how fs.Dirent file types are determined
89aba0c
The file type of a directory entry returned by fs.readdir() or
fs.opendir() is the type reported by the operating system's directory
listing. Node.js falls back to lstat() only when the reported type is
unknown, and some file systems may report a type that differs from what
lstat() would return. Document this in the fs.Dirent class introduction,
with fs.lstat() as the accurate alternative.

Fixes: #30646
Signed-off-by: Julian Soreavis <[email protected]>
PR-URL: #64532
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jason Zhang <[email protected]>
@github-actions github-actions Bot mentioned this pull request Aug 25, 2026
2026-08-26, Version 26.8.0 (Current) #65551
Merged
aduh95 pushed a commit that referenced this pull request Aug 27, 2026
@soreavis @aduh95
doc: clarify how fs.Dirent file types are determined
19dbd0d
The file type of a directory entry returned by fs.readdir() or
fs.opendir() is the type reported by the operating system's directory
listing. Node.js falls back to lstat() only when the reported type is
unknown, and some file systems may report a type that differs from what
lstat() would return. Document this in the fs.Dirent class introduction,
with fs.lstat() as the accurate alternative.

Fixes: #30646
Signed-off-by: Julian Soreavis <[email protected]>
PR-URL: #64532
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jason Zhang <[email protected]>
@github-actions github-actions Bot mentioned this pull request Sep 7, 2026
2026-09-08, Version 24.21.0 'Krypton' (LTS) #65873
Merged
aduh95 pushed a commit that referenced this pull request Sep 7, 2026
@soreavis @aduh95
doc: clarify how fs.Dirent file types are determined
64cd3a6
The file type of a directory entry returned by fs.readdir() or
fs.opendir() is the type reported by the operating system's directory
listing. Node.js falls back to lstat() only when the reported type is
unknown, and some file systems may report a type that differs from what
lstat() would return. Document this in the fs.Dirent class introduction,
with fs.lstat() as the accurate alternative.

Fixes: #30646
Signed-off-by: Julian Soreavis <[email protected]>
PR-URL: #64532
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Jason Zhang <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@lpinca lpinca lpinca approved these changes
@jazelly jazelly jazelly approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

doc Issues and PRs related to Node.js documentation. fs Issues and PRs related to file-system APIs and the fs module.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

readdir(p, { withFileTypes: true }) seemingly returns wrong type

Uh oh!

There was an error while loading. Please reload this page.

5 participants

@soreavis @trivikr @nodejs-github-bot @lpinca @jazelly
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.