Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation for __dirname is misleading #5525

Closed
c-f-h opened this issue Mar 2, 2016 · 4 comments
Closed

Documentation for __dirname is misleading #5525

c-f-h opened this issue Mar 2, 2016 · 4 comments
Labels
doc Issues and PRs related to the documentations. module Issues and PRs related to the module subsystem.

Comments

@c-f-h
Copy link

c-f-h commented Mar 2, 2016

The documentation for __dirname states that it gives "The name of the directory that the currently executing script resides in."

This may be taken to imply that __dirname always refers to the path of the module that was invoked as a script from the command line. However, it actually always produces the path of the current module, no matter where it was required from.

Just to clarify: assume I have modules

a.js
b/b.js

and a.js requires b.js. I run node a.js, and b.js uses its __dirname, which will refer to the b subdirectory. The current wording implies that it might actually refer to the directory that a.js is contained in since that is the "script" that I ran from the command line.

@bnoordhuis bnoordhuis added doc Issues and PRs related to the documentations. module Issues and PRs related to the module subsystem. labels Mar 2, 2016
@cjihrig
Copy link
Contributor

cjihrig commented Mar 2, 2016

When b.js is running, it is the currently executing script, not a.js. If you can word it less ambiguously, a docs PR is welcome.

jasnell added a commit to jasnell/node that referenced this issue Apr 2, 2016
@jasnell jasnell closed this as completed in c06824b Apr 2, 2016
MylesBorins pushed a commit that referenced this issue Apr 5, 2016
Fixes: #5525
PR-URL: #6018
Reviewed-By: Sakthipriyan Vairamani <[email protected]>
Reviewed-By: Roman Klauke <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
MylesBorins pushed a commit that referenced this issue Apr 11, 2016
Fixes: #5525
PR-URL: #6018
Reviewed-By: Sakthipriyan Vairamani <[email protected]>
Reviewed-By: Roman Klauke <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
@mk-pmb
Copy link

mk-pmb commented Dec 7, 2016

Please re-open, as the documentation is still (or again?) misleading even in v7.2.1: http://web.archive.org/web/20161207142244/https://nodejs.org/api/globals.html .

To me it looks like __dirname always refers to the script in whose scope it is used, independent of whether that script is currently running. (b done shows that the script has finished before a calls the function it imported.)

File b/b.js:

console.log('b start', __dirname);
module.exports = function () { console.log('b func', __dirname); };
console.log('b done', __dirname);

File a/a.js:

console.log('a start', __dirname);
var b = require('./b/b.js');
console.log('a has required', __dirname);
b();
console.log('a done', __dirname);

Output of nodejs a/a.js:

a start /tmp/a
b start /tmp/b
b done /tmp/b
a has required /tmp/a
b func /tmp/b
a done /tmp/a

@sam-github
Copy link
Contributor

__dirname always refers to the script in whose scope it is used, independent of whether that script is currently running

"script use" and "script run" have same meaning, how do you think they are different? In your example, all uses of __dirname in b.js occur only when b.js is run. If b.js was not running.... console.log would not be called from b.js.

That said, I kindof like your description, but note that its almost there already: "__dirname isn't actually a global but rather local to each module". Local is of course a reference to scope, but that is not as explicit as it could be. Also, resolved is not so obvious in its meaning.

Would you care to PR a reword?

I think the bigger problem is that the __dirname and __filename docs have diverged, astoundingly, their docs should be almost identical, given that __dirname is path.dirname(__filename)! That they have different verbal gymnastics to describe the same concept should be fixed.

@mk-pmb
Copy link

mk-pmb commented Dec 7, 2016

"__dirname isn't actually a global but rather local to each module."

Thanks for showing me, I totally missed that because I only checked the first paragraph earlier.

In your example, all uses of __dirname in b.js occur only when b.js is run.

You're right, and my earlier example even allowed for a much too naive reading of "use". Here's a better one where none of the scripts mention __dirname as an identifier in their code:

$ head */*.js && echo $'\n== Test it! ==' && nodejs lab/test.js
==> foo/bar.js <==
module.exports = function (x) { return eval(x); };

==> lab/test.js <==
var remoteEval = require('../foo/bar.js'), varname;
console.log('re:', typeof remoteEval);
varname = [ 'me', 'rna', '__di' ].reverse().join('');
console.log('dn:', remoteEval(varname));

== Test it! ==
re: function
dn: /tmp/foo

People less familiar with closure might really think that some part of bar.js might be running even after the "re:" log call, because they confuse to which point in time the explanation of "currently executing script" applies.

Would you care to PR a reword?

Nope, don't have time to word it as perfectionist as I'd expect for a node PR. ;-)

sam-github added a commit to sam-github/node that referenced this issue Jan 3, 2017
__dirname is path.dirname(__filename), but its docs, specifically the
attempt to describe javascript scope in terms of "running" and
"executing" had drifted apart. Rework to describe one as a variation of
the other, move the example, and just describe the names in terms of the
module, and it's local variables rather than the ill defined execution
concepts.

Fix: nodejs#5525
PR-URL: nodejs#10527
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Gibson Fahnestock <[email protected]>
evanlucas pushed a commit that referenced this issue Jan 4, 2017
__dirname is path.dirname(__filename), but its docs, specifically the
attempt to describe javascript scope in terms of "running" and
"executing" had drifted apart. Rework to describe one as a variation of
the other, move the example, and just describe the names in terms of the
module, and it's local variables rather than the ill defined execution
concepts.

Fix: #5525
PR-URL: #10527
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Gibson Fahnestock <[email protected]>
MylesBorins pushed a commit that referenced this issue Jan 23, 2017
__dirname is path.dirname(__filename), but its docs, specifically the
attempt to describe javascript scope in terms of "running" and
"executing" had drifted apart. Rework to describe one as a variation of
the other, move the example, and just describe the names in terms of the
module, and it's local variables rather than the ill defined execution
concepts.

Fix: #5525
PR-URL: #10527
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Gibson Fahnestock <[email protected]>
MylesBorins pushed a commit that referenced this issue Jan 24, 2017
__dirname is path.dirname(__filename), but its docs, specifically the
attempt to describe javascript scope in terms of "running" and
"executing" had drifted apart. Rework to describe one as a variation of
the other, move the example, and just describe the names in terms of the
module, and it's local variables rather than the ill defined execution
concepts.

Fix: #5525
PR-URL: #10527
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Gibson Fahnestock <[email protected]>
MylesBorins pushed a commit that referenced this issue Jan 31, 2017
__dirname is path.dirname(__filename), but its docs, specifically the
attempt to describe javascript scope in terms of "running" and
"executing" had drifted apart. Rework to describe one as a variation of
the other, move the example, and just describe the names in terms of the
module, and it's local variables rather than the ill defined execution
concepts.

Fix: #5525
PR-URL: #10527
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Gibson Fahnestock <[email protected]>
sam-github added a commit to sam-github/node that referenced this issue Feb 13, 2017
__dirname is path.dirname(__filename), but its docs, specifically the
attempt to describe javascript scope in terms of "running" and
"executing" had drifted apart. Rework to describe one as a variation of
the other, move the example, and just describe the names in terms of the
module, and it's local variables rather than the ill defined execution
concepts.

Fix: nodejs#5525
PR-URL: nodejs#10527
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Gibson Fahnestock <[email protected]>
MylesBorins pushed a commit that referenced this issue Feb 21, 2017
__dirname is path.dirname(__filename), but its docs, specifically the
attempt to describe javascript scope in terms of "running" and
"executing" had drifted apart. Rework to describe one as a variation of
the other, move the example, and just describe the names in terms of the
module, and it's local variables rather than the ill defined execution
concepts.

Fix: #5525
PR-URL: #10527
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Gibson Fahnestock <[email protected]>
MylesBorins pushed a commit that referenced this issue Feb 21, 2017
__dirname is path.dirname(__filename), but its docs, specifically the
attempt to describe javascript scope in terms of "running" and
"executing" had drifted apart. Rework to describe one as a variation of
the other, move the example, and just describe the names in terms of the
module, and it's local variables rather than the ill defined execution
concepts.

Fix: #5525
PR-URL: #10527
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Gibson Fahnestock <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. module Issues and PRs related to the module subsystem.
Projects
None yet
Development

No branches or pull requests

5 participants