You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/api/symlink.md
+71-18
Original file line number
Diff line number
Diff line change
@@ -5,31 +5,84 @@ hide_title: true
5
5
sidebar_label: symlink()
6
6
-->
7
7
8
-
# `gulp.symlink(folder[, options])`
8
+
# symlink()
9
9
10
-
Functions exactly like `gulp.dest`, but will create symlinks instead of copying
11
-
a directory.
10
+
Creates a stream for linking [Vinyl][vinyl-concepts] objects to the file system.
12
11
13
-
## folder
14
-
Type: `String` or `Function`
12
+
## Usage
13
+
'
14
+
```js
15
+
const { src, symlink } =require('gulp');
15
16
16
-
A folder path or a function that receives in a file and returns a folder path.
17
+
functionlink() {
18
+
returnsrc('input/*.js')
19
+
.pipe(symlink('output/'));
20
+
}
17
21
18
-
## options
19
-
Type: `Object`
22
+
exports.link= link;
23
+
```
20
24
21
-
### options.cwd
22
-
Type: `String`
25
+
## Signature
23
26
24
-
Default: `process.cwd()`
27
+
```js
28
+
symlink(directory, [options])
29
+
```
25
30
26
-
`cwd` for the output folder, only has an effect if provided output folder is
27
-
relative.
31
+
### Parameters
28
32
29
-
### options.dirMode
30
-
Type: `String` or `Number`
33
+
| parameter | type | note |
34
+
|:--------------:|:-----:|--------|
35
+
| directory <br> **(required)**| string <br> function | The path of the output directory where symbolic links will be created. If a function is used, the function will be called with each Vinyl object and must return a string directory path. |
36
+
| options | object | Detailed in [Options][options-section] below. |
31
37
32
-
Default: Default is the process mode.
38
+
### Returns
33
39
34
-
Octal permission specifying the mode the directory should be created with: e.g.
35
-
`"0755"`, `0755` or `493` (`0755` in base 10).
40
+
A stream that can be used in the middle or at the end of a pipeline to create symbolic links on the file system.
41
+
Whenever a Vinyl object is passed through the stream, it creates a symbolic link to the original file on the file system at the given directory.
42
+
43
+
Whenever a symbolic link is created on the file system, the Vinyl object will be modified.
44
+
* The `cwd`, `base`, and `path` properties will be updated to match the created symbolic link.
45
+
* The `stat` property will be updated to match the symbolic link on the file system.
46
+
* The `contents` property will be set to `null`.
47
+
* The `symlink` property will be added or replaced with original path.
48
+
49
+
**Note:** On Windows, directory links are created using junctions by default. The `useJunctions` option disables this behavior.
50
+
51
+
52
+
### Errors
53
+
54
+
When `directory` is an empty string, throws an error with the message, "Invalid symlink() folder argument. Please specify a non-empty string or a function."
55
+
56
+
When `directory` is not a string or function, throws an error with the message, "Invalid symlink() folder argument. Please specify a non-empty string or a function."
57
+
58
+
When `directory` is a function that returns an empty string or `undefined`, emits an error with the message, "Invalid output folder".
59
+
60
+
### Options
61
+
62
+
**For options that accept a function, the passed function will be called with each Vinyl object and must return a value of another listed type.**
63
+
64
+
| name | type | default | note |
65
+
|:-------:|:------:|-----------|-------|
66
+
| cwd | string <br> function |`process.cwd()`|The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining `directory` with `path.join()`. |
67
+
| dirMode | number <br> function || The mode used when creating directories. If not set, the process' mode will be used. |
68
+
| overwrite | boolean <br> function | true | When true, overwrites existing files with the same path. |
69
+
| relativeSymlinks | boolean <br> function | false | When false, any symbolic links created will be absolute. <br> **Note**: Ignored if a junction is being created, as they must be absolute. |
70
+
| useJunctions | boolean <br> function | true | This option is only relevant on Windows and ignored elsewhere. When true, creates directory symbolic link as a junction. Detailed in [Symbolic links on Windows][symbolic-links-section] below. |
71
+
72
+
## Symbolic links on Windows
73
+
74
+
When creating symbolic links on Windows, a `type` argument is passed to Node's `fs.symlink()` method which specifies the type of target being linked. The link type is set to:
75
+
`'file'` when the target is a regular file
76
+
`'junction'` when the target is a directory
77
+
`'dir'` when the target is a directory and the user disables the `useJunctions` option
78
+
79
+
80
+
If you try to create a dangling (pointing to a non-existent target) link, the link type can't be determined automatically. In these cases, behavior will vary depending on whether the dangling link is being created via `symlink()` or via `dest()`.
81
+
82
+
For dangling links created via `symlink()`, the incoming Vinyl object represents the target, so its stats will determine the desired link type. If `isDirectory()` returns false then a `'file'` link is created, otherwise a `'junction'` or a `'dir'` link is created depending on the value of the `useJunctions` option.
83
+
84
+
For dangling links created via `dest()`, the incoming Vinyl object represents the link - typically loaded from disk via `src(..., { resolveSymlinks: false })`. In this case, the link type can't be reasonably determined and defaults to using `'file'`. This may cause unexpected behavior when creating a dangling link to a directory. **Avoid this scenario.**
0 commit comments