ac5d7d2f.72a58eb5.js

(window.webpackJsonp=window.webpackJsonp||[]).push([[22],{108:function(e,t,n){"use strict";n.d(t,"a",(function(){return p})),n.d(t,"b",(function(){return u}));var a=n(0),r=n.n(a);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function l(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function b(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?l(Object(n),!0).forEach((function(t){i(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):l(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function c(e,t){if(null==e)return{};var n,a,r=function(e,t){if(null==e)return{};var n,a,r={},i=Object.keys(e);for(a=0;a<i.length;a++)n=i[a],t.indexOf(n)>=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a<i.length;a++)n=i[a],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var o=r.a.createContext({}),s=function(e){var t=r.a.useContext(o),n=t;return e&&(n="function"==typeof e?e(t):b(b({},t),e)),n},p=function(e){var t=s(e.components);return r.a.createElement(o.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.a.createElement(r.a.Fragment,{},t)}},m=r.a.forwardRef((function(e,t){var n=e.components,a=e.mdxType,i=e.originalType,l=e.parentName,o=c(e,["components","mdxType","originalType","parentName"]),p=s(n),m=a,u=p["".concat(l,".").concat(m)]||p[m]||d[m]||i;return n?r.a.createElement(u,b(b({ref:t},o),{},{components:n})):r.a.createElement(u,b({ref:t},o))}));function u(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var i=n.length,l=new Array(i);l[0]=m;var b={};for(var c in t)hasOwnProperty.call(t,c)&&(b[c]=t[c]);b.originalType=e,b.mdxType="string"==typeof e?e:a,l[1]=b;for(var o=2;o<i;o++)l[o]=n[o];return r.a.createElement.apply(null,l)}return r.a.createElement.apply(null,n)}m.displayName="MDXCreateElement"},90:function(e,t,n){"use strict";n.r(t),n.d(t,"frontMatter",(function(){return l})),n.d(t,"metadata",(function(){return b})),n.d(t,"toc",(function(){return c})),n.d(t,"default",(function(){return s}));var a=n(3),r=n(8),i=(n(0),n(108)),l={id:"symlink",title:"symlink()",hide_title:!0,sidebar_label:"symlink()"},b={unversionedId:"api/symlink",id:"api/symlink",isDocsHomePage:!1,title:"symlink()",description:"symlink()",source:"@site/docs/api/symlink.md",slug:"/api/symlink",permalink:"/docs/en/api/symlink",version:"current",sidebar_label:"symlink()",sidebar:"docs",previous:{title:"dest()",permalink:"/docs/en/api/dest"},next:{title:"lastRun()",permalink:"/docs/en/api/lastrun"}},c=[{value:"Usage",id:"usage",children:[]},{value:"Signature",id:"signature",children:[{value:"Parameters",id:"parameters",children:[]},{value:"Returns",id:"returns",children:[]},{value:"Errors",id:"errors",children:[]},{value:"Options",id:"options",children:[]}]},{value:"Symbolic links on Windows",id:"symbolic-links-on-windows",children:[]}],o={toc:c};function s(e){var t=e.components,n=Object(r.a)(e,["components"]);return Object(i.b)("wrapper",Object(a.a)({},o,n,{components:t,mdxType:"MDXLayout"}),Object(i.b)("h1",{id:"symlink"},"symlink()"),Object(i.b)("p",null,"Creates a stream for linking ",Object(i.b)("a",Object(a.a)({parentName:"p"},{href:"/docs/en/api/concepts#vinyl"}),"Vinyl")," objects to the file system."),Object(i.b)("h2",{id:"usage"},"Usage"),Object(i.b)("pre",null,Object(i.b)("code",Object(a.a)({parentName:"pre"},{className:"language-js"}),"const { src, symlink } = require('gulp');\n\nfunction link() {\n  return src('input/*.js')\n    .pipe(symlink('output/'));\n}\n\nexports.link = link;\n")),Object(i.b)("h2",{id:"signature"},"Signature"),Object(i.b)("pre",null,Object(i.b)("code",Object(a.a)({parentName:"pre"},{className:"language-js"}),"symlink(directory, [options])\n")),Object(i.b)("h3",{id:"parameters"},"Parameters"),Object(i.b)("table",null,Object(i.b)("thead",{parentName:"table"},Object(i.b)("tr",{parentName:"thead"},Object(i.b)("th",Object(a.a)({parentName:"tr"},{align:"center"}),"parameter"),Object(i.b)("th",Object(a.a)({parentName:"tr"},{align:"center"}),"type"),Object(i.b)("th",Object(a.a)({parentName:"tr"},{align:null}),"note"))),Object(i.b)("tbody",{parentName:"table"},Object(i.b)("tr",{parentName:"tbody"},Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"directory",Object(i.b)("br",null),Object(i.b)("strong",{parentName:"td"},"(required)")),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"string",Object(i.b)("br",null),"function"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null}),"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.")),Object(i.b)("tr",{parentName:"tbody"},Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"options"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"object"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null}),"Detailed in ",Object(i.b)("a",Object(a.a)({parentName:"td"},{href:"#options"}),"Options")," below.")))),Object(i.b)("h3",{id:"returns"},"Returns"),Object(i.b)("p",null,"A stream that can be used in the middle or at the end of a pipeline to create symbolic links on the file system.\nWhenever 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."),Object(i.b)("p",null,"Whenever a symbolic link is created on the file system, the Vinyl object will be modified."),Object(i.b)("ul",null,Object(i.b)("li",{parentName:"ul"},"The ",Object(i.b)("inlineCode",{parentName:"li"},"cwd"),", ",Object(i.b)("inlineCode",{parentName:"li"},"base"),", and ",Object(i.b)("inlineCode",{parentName:"li"},"path")," properties will be updated to match the created symbolic link."),Object(i.b)("li",{parentName:"ul"},"The ",Object(i.b)("inlineCode",{parentName:"li"},"stat")," property will be updated to match the symbolic link on the file system."),Object(i.b)("li",{parentName:"ul"},"The ",Object(i.b)("inlineCode",{parentName:"li"},"contents")," property will be set to ",Object(i.b)("inlineCode",{parentName:"li"},"null"),"."),Object(i.b)("li",{parentName:"ul"},"The ",Object(i.b)("inlineCode",{parentName:"li"},"symlink")," property will be added or replaced with original path.")),Object(i.b)("p",null,Object(i.b)("strong",{parentName:"p"},"Note:")," On Windows, directory links are created using junctions by default. The ",Object(i.b)("inlineCode",{parentName:"p"},"useJunctions")," option disables this behavior."),Object(i.b)("h3",{id:"errors"},"Errors"),Object(i.b)("p",null,"When ",Object(i.b)("inlineCode",{parentName:"p"},"directory"),' is an empty string, throws an error with the message, "Invalid symlink() folder argument. Please specify a non-empty string or a function."'),Object(i.b)("p",null,"When ",Object(i.b)("inlineCode",{parentName:"p"},"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."'),Object(i.b)("p",null,"When ",Object(i.b)("inlineCode",{parentName:"p"},"directory")," is a function that returns an empty string or ",Object(i.b)("inlineCode",{parentName:"p"},"undefined"),', emits an error with the message, "Invalid output folder".'),Object(i.b)("h3",{id:"options"},"Options"),Object(i.b)("p",null,Object(i.b)("strong",{parentName:"p"},"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.")),Object(i.b)("table",null,Object(i.b)("thead",{parentName:"table"},Object(i.b)("tr",{parentName:"thead"},Object(i.b)("th",Object(a.a)({parentName:"tr"},{align:"center"}),"name"),Object(i.b)("th",Object(a.a)({parentName:"tr"},{align:"center"}),"type"),Object(i.b)("th",Object(a.a)({parentName:"tr"},{align:null}),"default"),Object(i.b)("th",Object(a.a)({parentName:"tr"},{align:null}),"note"))),Object(i.b)("tbody",{parentName:"table"},Object(i.b)("tr",{parentName:"tbody"},Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"cwd"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"string",Object(i.b)("br",null),"function"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null}),Object(i.b)("inlineCode",{parentName:"td"},"process.cwd()")),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null}),"The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining ",Object(i.b)("inlineCode",{parentName:"td"},"directory")," with ",Object(i.b)("inlineCode",{parentName:"td"},"path.join()"),".")),Object(i.b)("tr",{parentName:"tbody"},Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"dirMode"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"number",Object(i.b)("br",null),"function"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null})),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null}),"The mode used when creating directories. If not set, the process' mode will be used.")),Object(i.b)("tr",{parentName:"tbody"},Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"overwrite"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"boolean",Object(i.b)("br",null),"function"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null}),"true"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null}),"When true, overwrites existing files with the same path.")),Object(i.b)("tr",{parentName:"tbody"},Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"relativeSymlinks"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"boolean",Object(i.b)("br",null),"function"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null}),"false"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null}),"When false, any symbolic links created will be absolute.",Object(i.b)("br",null),Object(i.b)("strong",{parentName:"td"},"Note"),": Ignored if a junction is being created, as they must be absolute.")),Object(i.b)("tr",{parentName:"tbody"},Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"useJunctions"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:"center"}),"boolean",Object(i.b)("br",null),"function"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null}),"true"),Object(i.b)("td",Object(a.a)({parentName:"tr"},{align:null}),"This option is only relevant on Windows and ignored elsewhere. When true, creates directory symbolic link as a junction. Detailed in ",Object(i.b)("a",Object(a.a)({parentName:"td"},{href:"#symbolic-links-on-windows"}),"Symbolic links on Windows")," below.")))),Object(i.b)("h2",{id:"symbolic-links-on-windows"},"Symbolic links on Windows"),Object(i.b)("p",null,"When creating symbolic links on Windows, a ",Object(i.b)("inlineCode",{parentName:"p"},"type")," argument is passed to Node's ",Object(i.b)("inlineCode",{parentName:"p"},"fs.symlink()")," method which specifies the type of target being linked. The link type is set to:"),Object(i.b)("ul",null,Object(i.b)("li",{parentName:"ul"},Object(i.b)("inlineCode",{parentName:"li"},"'file'")," when the target is a regular file"),Object(i.b)("li",{parentName:"ul"},Object(i.b)("inlineCode",{parentName:"li"},"'junction'")," when the target is a directory"),Object(i.b)("li",{parentName:"ul"},Object(i.b)("inlineCode",{parentName:"li"},"'dir'")," when the target is a directory and the user disables the ",Object(i.b)("inlineCode",{parentName:"li"},"useJunctions")," option")),Object(i.b)("p",null,"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 ",Object(i.b)("inlineCode",{parentName:"p"},"symlink()")," or via ",Object(i.b)("inlineCode",{parentName:"p"},"dest()"),"."),Object(i.b)("p",null,"For dangling links created via ",Object(i.b)("inlineCode",{parentName:"p"},"symlink()"),", the incoming Vinyl object represents the target, so its stats will determine the desired link type. If ",Object(i.b)("inlineCode",{parentName:"p"},"isDirectory()")," returns false then a ",Object(i.b)("inlineCode",{parentName:"p"},"'file'")," link is created, otherwise a ",Object(i.b)("inlineCode",{parentName:"p"},"'junction'")," or ",Object(i.b)("inlineCode",{parentName:"p"},"'dir'")," link is created depending on the value of the ",Object(i.b)("inlineCode",{parentName:"p"},"useJunctions")," option."),Object(i.b)("p",null,"For dangling links created via ",Object(i.b)("inlineCode",{parentName:"p"},"dest()"),", the incoming Vinyl object represents the link - typically loaded from disk via ",Object(i.b)("inlineCode",{parentName:"p"},"src(..., { resolveSymlinks: false })"),". In this case, the link type can't be reasonably determined and defaults to using ",Object(i.b)("inlineCode",{parentName:"p"},"'file'"),". This may cause unexpected behavior when creating a dangling link to a directory. ",Object(i.b)("strong",{parentName:"p"},"Avoid this scenario.")))}s.isMDXComponent=!0}}]);