doc: clarify fs.watch and inodes on linux, os x by jorangreef · Pull Request #6099 · nodejs/node

jorangreef · 2016-04-07T12:42:21Z

Checklist

documentation is changed or added
the commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

On Linux and OS X systems, fs.watch resolves the watched path to an
inode. This clarifies that fs.watch watches the inode and not the
path. If the inode of the path subsequently changes, fs.watch will
continue watching the original inode and events for the path will no
longer be emitted. This is expected behavior.

Fixes: #5039

thefourtheye · 2016-04-07T13:30:31Z

@nodejs/documentation is it okay to use "you"?

@thefourtheye It's consistent with the context, see the previous section on Availability a few lines up:
You can still use...

@jorangreef Yes, I am not saying its not correct. I just wanted to know what the Docs WG think.

We encourage to avoid it. Redacted myself often about this too.
I'd see this as a nit, but worthwhile.
https://github.com/nodejs/docs/blob/master/STYLE-GUIDE.md

In general I'd like to see us move away from the informal use of "you" as a best practice. It will take a while to eliminate past usage but I'd prefer not to introduce new instances of it :-)

stevemao · 2016-04-07T14:19:46Z

I would link inode to Unix-style file system docs since this is actually not a problem of nodejs itself. The text makes perfect sense to me. Thanks @jorangreef 😄

jorangreef · 2016-04-07T14:26:33Z

Thanks @stevemao, it's linked to "Linux and OS X systems" in the markdown. Do you mean that everything is fine as is? Or would you like any changes?

Fishrock123 · 2016-04-07T14:49:49Z

fs.watch()

Knighton910 · 2016-04-07T17:03:29Z

LGTM when added @Fishrock123 change fs.watch()

eljefedelrodeodeljefe · 2016-04-07T17:10:43Z

LGTM with nits: you, brackets. Sorry if this was in the discussion, but does the same thing apply for BSDs too? Can be added after landing, since the writing is not exclusive about this.

jasnell · 2016-04-07T17:29:38Z

Generally LGTM but would prefer some of the nits addressed.

stevemao · 2016-04-07T23:31:29Z

@jorangreef
I meant maybe we could link inode to http://www.linux.org/threads/intro-to-inodes.4130/ here

The link is just an example. If there is better one use that. :)

jorangreef · 2016-04-08T06:06:35Z

Sure, will make the suggested changes.

jorangreef · 2016-04-08T07:51:51Z

@eljefedelrodeodeljefe I did not test on BSD so I am not sure if it applies (it probably does). Linux and OS X were used as examples because these notes are aimed at users coming from Windows who might not expect fs.watch() to work with inodes (see #5039). Users targeting platforms such as BSD, SunOS etc. will probably be aware of inodes. Also, I didn't want to use "Unix-style systems" or "Unix systems" because Windows users might not realize that this includes OS X.

jorangreef · 2016-04-08T07:52:23Z

Done, with suggestions applied.

eljefedelrodeodeljefe · 2016-04-08T07:54:39Z

@jorangreef fair enough, thx. LGTM then.

Knighton910 · 2016-04-08T14:38:57Z

+1

jasnell · 2016-04-08T15:42:10Z

Nit... Perhaps: When a watched path is deleted and then recreated, it is assigned a new [inode][]. A notification for the deletion event will be emitted but the watch will continue on the *original* inode. Events for the new inode will not be emitted. This is expected behavior.

jasnell · 2016-04-08T15:42:21Z

LGTM with a nit.

On Linux and OS X systems, `fs.watch()` resolves the watched path to an inode. This clarifies that `fs.watch()` watches the inode and not the path. If the inode of the path subsequently changes, `fs.watch()` will continue watching the original inode and events for the path will no longer be emitted. This is expected behavior. Fixes: #5039

jorangreef · 2016-04-09T09:11:14Z

Thanks @jasnell, updated the wording.

jorangreef · 2016-04-18T05:45:18Z

This should be ready to merge now?

eljefedelrodeodeljefe · 2016-04-18T08:39:52Z

Yeah. I think he was just incredible busy since then with a conference and related stuff. Guess there will be around when this lands soon.

Still LGTM and a friendly ping to @jasnell.

jasnell · 2016-04-18T16:49:31Z

Yep, sorry! LGTM! :-)

On Linux and OS X systems, `fs.watch()` resolves the watched path to an inode. This clarifies that `fs.watch()` watches the inode and not the path. If the inode of the path subsequently changes, `fs.watch()` will continue watching the original inode and events for the path will no longer be emitted. This is expected behavior. Fixes: #5039 PR-URL: #6099 Reviewed-By: James M Snell <jasnell@gmail.com>

jasnell · 2016-04-18T16:52:37Z

Landed in 88c35e7

On Linux and OS X systems, `fs.watch()` resolves the watched path to an inode. This clarifies that `fs.watch()` watches the inode and not the path. If the inode of the path subsequently changes, `fs.watch()` will continue watching the original inode and events for the path will no longer be emitted. This is expected behavior. Fixes: #5039 PR-URL: #6099 Reviewed-By: James M Snell <jasnell@gmail.com>

On Linux and OS X systems, `fs.watch()` resolves the watched path to an inode. This clarifies that `fs.watch()` watches the inode and not the path. If the inode of the path subsequently changes, `fs.watch()` will continue watching the original inode and events for the path will no longer be emitted. This is expected behavior. Fixes: nodejs#5039 PR-URL: nodejs#6099 Reviewed-By: James M Snell <jasnell@gmail.com>

On Linux and OS X systems, `fs.watch()` resolves the watched path to an inode. This clarifies that `fs.watch()` watches the inode and not the path. If the inode of the path subsequently changes, `fs.watch()` will continue watching the original inode and events for the path will no longer be emitted. This is expected behavior. Fixes: #5039 PR-URL: #6099 Reviewed-By: James M Snell <jasnell@gmail.com>

fatonsopa · 2017-10-30T16:35:50Z

Hi guys,

this is still happening:

npm -v 3.10.10
node -v v6.11.5
MacOS Sierra 10.12.6

The file.watch is triggering the change only once per file. In windows is working perfectly.

Researched a lot but couldn't find a working solution. Any idea?

Thanks,
Faton

thefourtheye · 2017-11-02T19:12:43Z

@fatonsopa That is the expected behavior. This PR just documented it properly.

fatonsopa · 2017-11-02T19:29:39Z

@thefourtheye Thanks. I didn't get the PR!
Is there any way I can make it work in all OS?

jorangreef mentioned this pull request Apr 7, 2016
Mac: fs.watch() not detecting changes to file from git operation #5039
Closed

r-52 added doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. lts-watch-v4.x labels Apr 7, 2016

thefourtheye reviewed Apr 7, 2016
View reviewed changes

Fishrock123 reviewed Apr 7, 2016
View reviewed changes

Comment threaddoc/api/fs.markdown Outdated
Fishrock123Apr 7, 2016
Copy link
Copy Markdown
Contributor
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
fs.watch()

stevemao reviewed Apr 7, 2016
View reviewed changes

jasnell reviewed Apr 8, 2016
View reviewed changes

jasnell closed this Apr 18, 2016

MylesBorins mentioned this pull request Apr 20, 2016
V5.10.2 proposal #6311
Closed

This was referenced Apr 21, 2016
V5.11.0 proposal #6321
Closed
V5.11.0 proposal #6322
Closed

MylesBorins added land-on-v4.x and removed lts-watch-v4.x labels May 3, 2016

MylesBorins mentioned this pull request May 18, 2016
v4.4.5 proposal #6824
Merged

jack-guy mentioned this pull request Jul 6, 2016
Out of workspace files: Changes from git operations not reflected microsoft/vscode#2592
Closed

bnoordhuis mentioned this pull request Sep 28, 2016
doc: dead external link in fs.md #8825
Closed

coderabbitaiBot mentioned this pull request Mar 22, 2026
[DNM] Feat/kanban board UI komunite/kalfa#11
Closed

coderabbitaiBot mentioned this pull request Jul 30, 2026
fix(kit,nuxt,vite): handle missed chokidar watch events nuxt/nuxt#35887
Merged

Uh oh!

Uh oh!

Conversation

jorangreef commented Apr 7, 2016

Checklist

Affected core subsystem(s)

Description of change

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevemao commented Apr 7, 2016

Uh oh!

jorangreef commented Apr 7, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Knighton910 commented Apr 7, 2016

Uh oh!

eljefedelrodeodeljefe commented Apr 7, 2016

Uh oh!

jasnell commented Apr 7, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorangreef commented Apr 8, 2016

Uh oh!

jorangreef commented Apr 8, 2016

Uh oh!

jorangreef commented Apr 8, 2016

Uh oh!

eljefedelrodeodeljefe commented Apr 8, 2016

Uh oh!

Knighton910 commented Apr 8, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasnell commented Apr 8, 2016

Uh oh!

jorangreef commented Apr 9, 2016

Uh oh!

jorangreef commented Apr 18, 2016

Uh oh!

eljefedelrodeodeljefe commented Apr 18, 2016

Uh oh!

jasnell commented Apr 18, 2016

Uh oh!

jasnell commented Apr 18, 2016

Uh oh!

fatonsopa commented Oct 30, 2017

Uh oh!

thefourtheye commented Nov 2, 2017

Uh oh!

fatonsopa commented Nov 2, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants