gruntjs/grunt-contrib-symlink

Create symbolic links.

grunt-contrib-symlink v1.0.0

Create symbolic links.

Getting Started

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-contrib-symlink --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-contrib-symlink');

Symlink task

Run this task with the grunt symlink command.

Task targets, files and options may be specified according to the grunt Configuring tasks guide. Pay special attention to the Building the files object dynamically section, which explains how to create many src-dest file mappings all at once.

Note that the symlink mode (file, dir) is determined automatically based on the src file type.

Usage Examples

symlink: {
  options: {
    // Enable overwrite to delete symlinks before recreating them
    overwrite: false,
    // Enable force to overwrite symlinks outside the current working directory
    force: false
  },
  // The "build/target.txt" symlink will be created and linked to
  // "source/target.txt". It should appear like this in a file listing:
  // build/target.txt -> ../source/target.txt
  explicit: {
    src: 'source/target.txt',
    dest: 'build/target.txt'
  },
  // These examples using "expand" to generate src-dest file mappings:
  // http://gruntjs.com/configuring-tasks#building-the-files-object-dynamically
  expanded: {
    files: [
      // All child files and directories in "source", starting with "foo-" will
      // be symlinked into the "build" directory, with the leading "source"
      // stripped off.
      {
        expand: true,
        overwrite: false,
        cwd: 'source',
        src: ['foo-*'],
        dest: 'build'
      },
      // All child directories in "source" will be symlinked into the "build"
      // directory, with the leading "source" stripped off.
      {
        expand: true,
        overwrite: false,
        cwd: 'source',
        src: ['*'],
        dest: 'build',
        filter: 'isDirectory'
      }
    ]
  },
}

CLI overwrite option

To override the overwrite option via the CLI pass it as an option

  grunt symlink --overwrite

Usage tips on Microsoft Windows

Make sure your command prompt has administrative privileges, otherwise the task will not work.

Release History

• 2016-02-28   v1.0.0   Added force option when overwriting a symlink outside the current working directory.
• 2014-02-01   v0.3.0   Fixed symlinking to '.'. Add Windows usage hints. Added error logging and force failure when unable to create a symlink.
• 2013-07-26   v0.2.0   Initial release as rewritten, officially-maintained, contrib plugin.
• 2012-12-21   v0.1.1   Unofficial release.
• 2012-12-20   v0.1.0   Unofficial release.

---

Task submitted by "Cowboy" Ben Alman

This file was generated on Thu Apr 14 2016 09:11:03.

grunt-contrib-symlink's Issues

overwriting of symlinks to files outside the grunt directory fails

With overwrite: true set, if a symlink resolves to a file outside of the gruntfile's directory, then when it attempts to overwrite an old symlink it fails with: Warning: Cannot delete files outside the current working directory. Use --force to continue.

I think it should just unlink/change the old symlink.

"overwrite" option deletes previous files instead of unlinking

When using the options.overwrite = true option I'm seeing a very undesirable behavior.

Instead of unlinking the old link before overwriting it, it actually deletes the files for the old link. This is not the expected behavior.

Can you please change the command to perform an "unlink" command instead of an "rm" command?

grunt-contrib-hardlink: contributing new plugin to grunt-contrib

I just published grunt-contrib-hardlink (initially forked from grunt-contrib-symlink) which solves the problem of a recursive hard-linking grunt task. As demonstrated by the issues and pull requests below it's a feature people would find useful.

• gruntjs/grunt-contrib-copy#75
• gruntjs/grunt-contrib-copy#146
• gruntjs/grunt-contrib-copy#147
• gruntjs/grunt#797

I've opened this issue here because I couldn't open one at grunt-contrib, despite the instructions asking for that at the grunt web page contributing section.

Symlink creation not working in Windows (at least 8) using NTFS

I tested grunt-contrib-symlink in Windows 8 on NTFS, and it's not creating the symlink whereas that same code works in Ubuntu Linux.

I'm getting this:

Running tasks: symlink

Running "symlink" task

Running "symlink:assets" (symlink) task
Verifying property symlink.assets exists in config...OK
Files: public/assets/test.txt -> blog/test.txt
Linking (file) blog/test.txt -> ..\public\assets\test.txt...ERROR
>> Created 1 symbolic links.

Whereas the same code in Linux nets me

Running tasks: symlink

Running "symlink" task

Running "symlink:assets" (symlink) task
Verifying property symlink.assets exists in config...OK
Files: public/assets/test.txt -> blog/test.txt
Linking (file) blog/test.txt -> ../public/assets/test.txt...OK
>> Created 1 symbolic links.

Done, without errors.
$ ls -lah blog/
total 8.0K
drwxr-sr-x 2 root www-dev 4.0K 2013-08-23 10:35 .
drwxr-sr-x 8 root www-dev 4.0K 2013-08-23 10:35 ..
lrwxrwxrwx 1 root www-dev   25 2013-08-23 10:35 test.txt -> ../public/assets/test.txt

Creating a symlink on Windows fails for regular users

Creating a symbolic link (hardlink) on Windows is a privileged operation. The operation fails with ERROR_ACCESS_DENIED if the SE_CREATE_SYMBOLIC_LINK_NAME has not bee granted, which only administrators have by default. Any user can create a directory junction (soft link) providing the file system permissions allow it.

While it can requested, that the user running Grunt has been granted the necessary privilege, it would be an additional step for the build environment and an exception from company policies would be needed. This can be saved, because junctions are mostly exactly what is needed on Windows.

The NodeJS symlink creation method offers the 'junction' type to solve the problem. The pull request #11 enables junction creation for this task without breaking current scenarios. It could be modified to use the special directory link mode only on Windows platform, if you found it better.

You may consider adding the force option too, to let the Grunt ignore errors, which are not critical for the build (pull request #14).

Can you update the README for idiots like me?

Hi there,

I thought that explicit was a keyword and I didn't know hot to create a second symlink. Maybe it will be nice to replace this explicit by theNameYouWant or something like this (for people who are new to grunt structure).

Best,

Thanks for the lib btw!

Update npm version

Hi,

Could you please publish v0.3.0 to npm?

Thank you!

Create a new release containing the "force" option

This option was added in 2014, but has still not made it into a release on npm. I'm running into an issue with my build where I would like to use this flag to work around it.

Thanks!

EPERM, operation not permitted at win8.1

      test: {
        src: 'package.json',
        dest: 'dist/package.json'
      },

D:\Workspace\Code\9game\ninegameclient\android-h5 (master)                                                
λ grunt symlink:test                                                                                      
Running "symlink:test" (symlink) task                                                                     
>> Error: EPERM, operation not permitted '..\package.json'                                                
Warning: Failed to create symlink: (file) dist/package.json -> ..\package.json. Use --force to continue.  

Create a new release because Windows junction support is missing in 1.0.0?

Is it possible to release a 1.0.1because Windows junction support disappeared in 1.0.0 ?

The current master again contains junction support.

Thanks.

Arguments to path.join must be strings

grunt symlink -v

Running "symlink:bower" (symlink) task
Verifying property symlink.bower exists in config...OK
Files: [no src] -> app/static/bower_components
Warning: Arguments to path.join must be strings Use --force to continue.

My config

symlink: {
    options: {
        overwrite: false
    },
    // dest -> src
    bower: {
        src: '.tmp/static/bower_components',
        dest: 'app/static/bower_components'
    }
},

I have no idea what is wrong.

Non existing source shows invalid file

Try config

symlink: {
    options: {
        overwrite: true
    },
    test: {
        files: [
            {
                src: 'nonexistingfolder',
                dest: 'new'
            }
        ]
    },
}

It will return:

grunt symlink:test
Running "symlink:test" (symlink) task
Warning: Arguments to path.join must be strings Use --force to continue.

Aborted due to warnings.

Instead of File not exist

Cannot create a symlink on windows even after running as admin. Operation not permitted erro

I have tried to create a symlink to copy the files from node_modules to vendor folder but getting an operation not permitted error . Please note i have ran as admin as well

symlink: {
options: {
overwrite: false,
force: false
},
explicit: {
src: 'node_modules',
dest: 'vendor'
}
}

Feature request for hardlinks.

Could there be an option to add hard links?

It would solve some issues with symlinks, especially in Windows.

There's also an issue of "deleting files outside the CWD", when the source of the symlinks are not within the build dir.