doc,fs: keep consistent with fs.link and fs.linkSync

[yorkie]

So firstly, the destination has a little confusion like I got the log:

Error: EEXIST: file already exists, symlink 'dist/node_modules' -> 'node_modules'

And my source call is:

fs.symlinkSync('dist/node_modules', 'node_modules', 'dir');

Because I thought the first argument stands for destination as the original doc is telling, but it actually is source. Plus, I also make link* and symlinkSync be consistent :-)

[targos]

In man ln the arguments are called TARGET and LINK_NAME. Perhaps we should be consistent with that and pick target and linkName or just name instead ?

[evanlucas]

man ln will be different across platforms though. On OS X, it is source_file and target_file (or target_dir)

[yorkie]

Ah, I didn't know it's consistent with man command. BTW, if as @evanlucas said, this behaviors are different across platforms, shouldn't the cross-platform Node.js unify it?

(I'm using OSX).

[yorkie]

Oh, @targos @evanlucas Why do you reference the command ln, what I have changed on is symlink(2), am I right? After reading at the man symlink, which uses path1 and path2 as below:

A symbolic link path2 is created to path1 (path2 is the name of the file cre-
ated, path1 is the string used in creating the symbolic link). Either name
may be an arbitrary path name; the files need not be on the same file system.

Then now I'm able to understand why the author of this function used destination as the name of 1st one, because the context said there is a pointer to the file described by the 1st one, that we called it source at other function like fs.link.

However, not all Node.js user is such that familiar with Linux like me, then the naming of arguments in fs.link and fs.symlink were really really confused. So I still proposal that keep consistent with fs.link's naming rule, any thoughts?

[evanlucas]

Ahhh good point. I think that this is less confusing than the current documentation.

LGTM

[targos]

You also need to update mentions of "destination path" here.

[targos]

Fair enough, I didn't get that the point was to make it consistent with fs.link, sorry !

[yorkie]

Never mind @targos, fixed nits and updated the naming in source files, LGTY too?

[targos]

LGTM

CI: https://ci.nodejs.org/job/node-test-commit/1183/

[yorkie]

BTW, I found a typo of errors in fs.link and created a new PR at #3917 :-)

[jasnell]

@yorkie ... awesome. This LGTM but curious what @nodejs/ctc would think about the semver-iness of this change. It seems like a fairly significant mismatch between the docs, the API and the implementation in JS.

Also, minor nit, can you please update the title of the PR to be doc,fs: to reflect that it's a change to both the doc and the fs module?

[jasnell]

I'm going to mark this semver-major for now as a precaution.

[yorkie]

Done :-)

[yorkie]

How is this going? is the CI happy now? This seems to be suspended over 4 days :-)

[trevnorris]

Just to be clear, this change won't break any existing code or will it?

[piscisaureus]

The documentation change is incorrect. I reverted a similar change in in 5843ae8.

[piscisaureus]

Let me clarify a bit, too.

symlinkSync(destination, path) creates a symbolic link at path which points at destination.

If this patch gets landed, it becomes this:

symlinkSync(srcpath, dstpath) creates a symbolic link at dstpath which points at srcpath.
I find that wording very confusing, I (and I think most people) would assume the source to point at the destination, and not the other way round.

If the fs.link() documentation is unclear, I would prefer to see that fixed rather than applied to other documentation sections.

[yorkie]

Thanks @piscisaureus and now I have some explanations more about this question, the following is a description from man link/ln:

Given one or two arguments, ln creates a link to an existing file source_file.

The above manual seems to use source to stand for the existing file, and the below is also from manual:

How a link points to a file is one of the differences between a hard and symbolic link.

So I think the file pointed from the link should be unified by this manual.

creates a symbolic link at dstpath which points at srcpath

@piscisaureus as you said, I correct your words as: creates a symbolic link/pointer to the source_file, and this link/pointer is named by target_file, so I'm proposing that Node.js should use target instead of dest in link, symlink.

[targos]

creates a symbolic link/pointer to the source_file, and this link/pointer is named by target_file

It's not that easy. In the Linux doc, target is used for the path that the symlink points at: http://man7.org/linux/man-pages/man2/symlink.2.html

[piscisaureus]

@piscisaureus as you said, I correct your words as: creates a symbolic link/pointer to the source_file, and this link/pointer is named by target_file, so I'm proposing that Node.js should use target instead of dest in link, symlink.

A symbolic link points to another path. There doesn't actually need to be a file there. I think "target" is an appropriate name for the path that the symbolic link points to.

link() is different in the sense that it doesn't point at another path - it adds a new name for a file that already exists. It has more in common with rename(old_name, new_name) than it has with symlink - the difference being that link adds a name and rename changes the name. So I would suggest the link docs be made consistent with rename rather than symlink.

You can see the linux man pages do the same thing:

• int link(const char *oldpath, const char *newpath)
• int rename(const char *oldpath, const char *newpath)

versus

• int symlink(const char *target, const char *linkpath)

[yorkie]

@piscisaureus I do that agree with you 100%, and I now updated my commits to use target instead of destination. Could you take a look again, thank you guys :-)

[piscisaureus]

LGTM. Thanks for your patience @yorkie!

[evanlucas]

LGTM if CI is happy.

CI: https://ci.nodejs.org/job/node-test-pull-request/844/

[evanlucas]

@yorkie CI doesn't seem to be happy with this change.

https://ci.nodejs.org/job/node-test-commit-osx/1298/nodes=osx1010/console

[yorkie]

Sorry, I guess I have something forgot to update, I will check it again, sorry :-)

[targos]

That's right

[jasnell]

@Trott +1... label removed

[jasnell]

LGTM
(sorry for the delay reviewing @yorkie , just catching up after vacation ;-) )

[targos]

LGTM

[yorkie]

Btw, if semver is right to marjor, when this would get this merged? Does this get documented?

[yorkie]

Thank you guys :-)

[yorkie]

Ping guys

[Trott]

CI: https://ci.nodejs.org/job/node-test-pull-request/933/

[yorkie]

@Trott Why create a new CI? because I didn't push any changes to the last CI.

[Trott]

Whoops, my mistake.

[targos]

@yorkie your last push was 10 days ago, it can be possible that new commits on master make the changes in this PR fail

[Trott]

FWIW, the latest CI passed except for known-flaky tests on Windows (including one that would be fixed by #4062, hey someone go look at that and give it an LGTM if you're comfy with the change, will ya?).

[Trott]

Landed in 8c35903

(The patch didn't apply cleanly on fs.markdown so check my work carefully on that one to make sure I didn't mess anything up.)

[yorkie]

@Trott I guess you missed to add @trevnorris to reviewers list at 8c35903

[yorkie]

Never mind, that's my fault, thank you Trott :-)