Symlink/Junction improvements

README.md

@@ -211,10 +211,12 @@ Default: `false`
 ##### `options.useJunctions`
 
 When creating a symlink, whether or not a directory symlink should be created as a `junction`.
+This option is only relevant on Windows and ignored elsewhere. Please refer to
+the caveats section below.
 
 Type: `Boolean`
 
-Default: `true` on Windows, `false` on all other platforms
+Default: `true`
 
 ### `symlink(folder[, options])`
 
@@ -239,14 +241,6 @@ Type: `String`
 
 Default: `process.cwd()`
 
-##### `options.mode`
-
-The mode the symlinks should be created with.
-
-Type: `Number`
-
-Default: The `mode` of the input file (`file.stat.mode`) if any, or the process mode if the input file has no `mode` property.
-
 ##### `options.dirMode`
 
 The mode the directory should be created with.
@@ -274,10 +268,37 @@ Default: `false`
 ##### `options.useJunctions`
 
 Whether or not a directory symlink should be created as a `junction`.
+This option is only relevant on Windows and ignored elsewhere. Please refer to
+the caveats section below.
 
 Type: `Boolean`
 
-Default: `true` on Windows, `false` on all other platforms
+Default: `true`
+
+#### Symbolic links on Windows
+
+When creating symbolic links on Windows, we pass a `type` argument to Node's
+`fs` module which specifies the kind of target we link to (one of `'file'`,
+`'dir'` or `'junction'`). Specifically, this will be `'file'` when the target
+is a regular file, `'junction'` if the target is a directory, or `'dir'` if
+the target is a directory and the user overrides the `useJunctions` option
+default.
+
+However if the user tries to make a "dangling" link, pointing to a non-existent
+target, we won't be able to determine automatically which type we should use.
+In these cases, `vinyl-fs` will behave slightly differently depending on
+whether the dangling link is being created via `symlink()` or via `dest()`.
+
+For dangling links created via `symlink()`, the incoming vinyl represents the
+target and so we will look to its stats to guess the desired type. In
+particular, if `isDirectory()` returns false then we'll create a `'file'` type
+link, otherwise we will create a `'junction'` or a `'dir'` type link depending
+on the value of the `useJunctions` option.
+
+For dangling links created via `dest()`, the incoming vinyl represents the link,
+typically read off disk via `src()` with the `resolveSymlinks` option set to 
+false. In this case we won't be able to make any reasonable guess as to the 
+type of link and we default to using `'file'`.
 
 [glob-stream]: https://github.com/gulpjs/glob-stream
 [node-glob]: https://github.com/isaacs/node-glob

lib/dest/options.js

@@ -1,9 +1,5 @@
 'use strict';
 
-var os = require('os');
-
-var isWindows = (os.platform() === 'win32');
-
 var config = {
  cwd: {
  type: 'string',
@@ -34,14 +30,15 @@ var config = {
  default: false,
  },
  // Symlink options
- useJunctions: {
- type: 'boolean',
- default: isWindows,
- },
  relativeSymlinks: {
  type: 'boolean',
  default: false,
  },
+ // This option is ignored on non-Windows platforms
+ useJunctions: {
+ type: 'boolean',
+ default: true,
+ },
 };
 
 module.exports = config;

lib/dest/prepare.js

@@ -11,22 +11,23 @@ function prepareWrite(folderResolver, optResolver) {
  }
 
  function normalize(file, enc, cb) {
- var mode = optResolver.resolve('mode', file);
- var cwd = path.resolve(optResolver.resolve('cwd', file));
-
  var outFolderPath = folderResolver.resolve('outFolder', file);
  if (!outFolderPath) {
  return cb(new Error('Invalid output folder'));
  }
+ var cwd = path.resolve(optResolver.resolve('cwd', file));
  var basePath = path.resolve(cwd, outFolderPath);
  var writePath = path.resolve(basePath, file.relative);
 
  // Wire up new properties
- file.stat = (file.stat || new fs.Stats());
- file.stat.mode = mode;
  file.cwd = cwd;
  file.base = basePath;
  file.path = writePath;
+ if (!file.isSymbolic()) {
+ var mode = optResolver.resolve('mode', file);
+ file.stat = (file.stat || new fs.Stats());
+ file.stat.mode = mode;
+ }
 
  cb(null, file);
  }

lib/dest/write-contents/index.js

@@ -13,7 +13,7 @@ function writeContents(optResolver) {
 
  function writeFile(file, enc, callback) {
  // Write it as a symlink
- if (file.symlink) {
+ if (file.isSymbolic()) {
  return writeSymbolicLink(file, optResolver, onWritten);
  }
 

lib/dest/write-contents/write-symbolic-link.js

@@ -1,42 +1,74 @@
 'use strict';
 
+var os = require('os');
 var path = require('path');
 
 var fo = require('../../file-operations');
 
+var isWindows = (os.platform() === 'win32');
+
 function writeSymbolicLink(file, optResolver, onWritten) {
- var isDirectory = file.isDirectory();
-
- // This option provides a way to create a Junction instead of a
- // Directory symlink on Windows. This comes with the following caveats:
- // * NTFS Junctions cannot be relative.
- // * NTFS Junctions MUST be directories.
- // * NTFS Junctions must be on the same file system.
- // * Most products CANNOT detect a directory is a Junction:
- // This has the side effect of possibly having a whole directory
- // deleted when a product is deleting the Junction directory.
- // For example, JetBrains product lines will delete the entire
- // contents of the TARGET directory because the product does not
- // realize it's a symlink as the JVM and Node return false for isSymlink.
- var useJunctions = optResolver.resolve('useJunctions', file);
-
- var symDirType = useJunctions ? 'junction' : 'dir';
- var symType = isDirectory ? symDirType : 'file';
+ if (!file.symlink) {
+ return onWritten(new Error('Missing symlink property on symbolic vinyl'));
+ }
+
  var isRelative = optResolver.resolve('relativeSymlinks', file);
+ var flag = optResolver.resolve('flag', file);
 
- // This is done after prepare() to use the adjusted file.base property
- if (isRelative && symType !== 'junction') {
- file.symlink = path.relative(file.base, file.symlink);
+ if (!isWindows) {
+  // On non-Windows, just use 'file'
+ return createLinkWithType('file');
  }
 
- var flag = optResolver.resolve('flag', file);
+ fo.reflectStat(file.symlink, file, onReflect);
+
+ function onReflect(statErr) {
+ if (statErr && statErr.code !== 'ENOENT') {
+ return onWritten(statErr);
+ }
+
+ // This option provides a way to create a Junction instead of a
+ // Directory symlink on Windows. This comes with the following caveats:
+ // * NTFS Junctions cannot be relative.
+ // * NTFS Junctions MUST be directories.
+ // * NTFS Junctions must be on the same file system.
+ // * Most products CANNOT detect a directory is a Junction:
+ // This has the side effect of possibly having a whole directory
+ // deleted when a product is deleting the Junction directory.
+ // For example, JetBrains product lines will delete the entire contents
+ // of the TARGET directory because the product does not realize it's
+ // a symlink as the JVM and Node return false for isSymlink.
 
- var opts = {
- flag: flag,
- type: symType,
- };
+ // This function is Windows only, so we don't need to check again
+ var useJunctions = optResolver.resolve('useJunctions', file);
 
- fo.symlink(file.symlink, file.path, opts, onWritten);
+ var dirType = useJunctions ? 'junction' : 'dir';
+ // Dangling links are always 'file'
+ var type = !statErr && file.isDirectory() ? dirType : 'file';
+
+ createLinkWithType(type);
+ }
+
+ function createLinkWithType(type) {
+ // This is done after prepare() to use the adjusted file.base property
+ if (isRelative && type !== 'junction') {
+ file.symlink = path.relative(file.base, file.symlink);
+ }
+
+ var opts = {
+ flag: flag,
+ type: type,
+ };
+ fo.symlink(file.symlink, file.path, opts, onSymlink);
+
+ function onSymlink(symlinkErr) {
+ if (symlinkErr) {
+ return onWritten(symlinkErr);
+ }
+
+ fo.reflectLinkStat(file.path, file, onWritten);
+ }
+ }
 }
 
 module.exports = writeSymbolicLink;

lib/file-operations.js

@@ -155,6 +155,34 @@ function isOwner(fsStat) {
  return true;
 }
 
+function reflectStat(path, file, callback) {
+ // Set file.stat to the reflect current state on disk
+ fs.stat(path, onStat);
+
+ function onStat(statErr, stat) {
+ if (statErr) {
+ return callback(statErr);
+ }
+
+ file.stat = stat;
+ callback();
+ }
+}
+
+function reflectLinkStat(path, file, callback) {
+ // Set file.stat to the reflect current state on disk
+ fs.lstat(path, onLstat);
+
+ function onLstat(lstatErr, stat) {
+ if (lstatErr) {
+ return callback(lstatErr);
+ }
+
+ file.stat = stat;
+ callback();
+ }
+}
+
 function updateMetadata(fd, file, callback) {
 
  fs.fstat(fd, onStat);
@@ -413,6 +441,8 @@ module.exports = {
  getTimesDiff: getTimesDiff,
  getOwnerDiff: getOwnerDiff,
  isOwner: isOwner,
+ reflectStat: reflectStat,
+ reflectLinkStat: reflectLinkStat,
  updateMetadata: updateMetadata,
  symlink: symlink,
  writeFile: writeFile,

lib/src/resolve-symlinks.js

@@ -1,23 +1,21 @@
 'use strict';
 
 var through = require('through2');
-var fs = require('graceful-fs');
+var fo = require('../file-operations');
 
 function resolveSymlinks(optResolver) {
 
  // A stat property is exposed on file objects as a (wanted) side effect
  function resolveFile(file, enc, callback) {
 
- fs.lstat(file.path, onStat);
+ fo.reflectLinkStat(file.path, file, onReflect);
 
- function onStat(statErr, stat) {
+ function onReflect(statErr) {
  if (statErr) {
  return callback(statErr);
  }
 
- file.stat = stat;
-
- if (!stat.isSymbolicLink()) {
+ if (!file.stat.isSymbolicLink()) {
  return callback(null, file);
  }
 
@@ -27,8 +25,8 @@ function resolveSymlinks(optResolver) {
  return callback(null, file);
  }
 
- // Recurse to get real file stat
- fs.stat(file.path, onStat);
+ // Get target's stats
+ fo.reflectStat(file.path, file, onReflect);
  }
  }