Deprecation Notice

gulp 4 adds built-in symlinks to the public API, making it really easy to create streams of symlinks. Therefore, this module has been deprecated.

You may replace this module with a call to vinyl-fs for gulp 3.x:

var vfs = require('vinyl-fs');

gulp.task('symlink', function () {
  return vfs.src('assets/some-large-video.mp4', {followSymlinks: false})
  .pipe(vfs.symlink('build/videos'));
});

gulp-symlink

Create symlinks during your gulp build.

Install

With npm do:

npm install gulp-symlink --save-dev

Example

var symlink = require('gulp-symlink');

gulp.task('default', function () {
  return gulp.src('assets/some-large-video.mp4')
    .pipe(symlink('build/videos')) // Write to the destination folder
    .pipe(symlink('build/videos/renamed-video.mp4')) // Write a renamed symlink to the destination folder
});

API

symlink(path, [options]), symlink.relative(path, [options]) or symlink.absolute(path, [options])

Pass a string or a function to create the symlink. The function is passed the vinyl object, so you can use file.base, file.path etc. For example:

gulp.task('symlink', function () {
  return gulp.src('assets/some-large-video.mp4')
    .pipe(symlink(function (file) {
      // Here we return a path as string
      return path.join(file.base, 'build', file.relative.replace('some-large', ''));
    }));
});

gulp.task('symlink-vinyl', function () {
  return gulp.src('assets/some-large-video.mp4')
    .pipe(symlink.absolute(function (file) {
        // Here we return a new Vinyl instance
        return new symlink.File({
          path: 'build/videos/video.mp4',
          cwd: process.cwd()
        });
    }, {force: true}));
})

The string options work in the same way. If you pass a string like 'build/videos', the symlink will be created in that directory. If you pass 'build/videos/video.mp4', the symlink will also be renamed. The function will be called as many times as there are sources.

You might also want to give an array of destination paths:

gulp.task('symlink-array', function () {
  return gulp.src(['modules/assets/', 'modules/client/'])
    .pipe(symlink(['./assets', './client']));
});

The default symlink performs a relative link. If you want an absolute symlink use symlink.absolute instead.

symlink.File

The vinyl module is exposed here. If you are creating new files with the function as shown above, please use this one.

Contributing

Pull requests are welcome. If you add functionality, then please add unit tests to cover it.

License

MIT © Ben Briggs