1"use strict";(self.webpackChunkgulpjs_github_io=self.webpackChunkgulpjs_github_io||[]).push([[129],{150:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>l,default:()=>a,frontMatter:()=>r,metadata:()=>d,toc:()=>o});var i=t(4848),s=t(8453);const r={id:"symlink",title:"symlink()",hide_title:!0,sidebar_label:"symlink()"},l="symlink()",d={id:"api/symlink",title:"symlink()",description:"Creates a stream for linking Vinyl objects to the file system.",source:"@site/docs/api/symlink.md",sourceDirName:"api",slug:"/api/symlink",permalink:"/docs/en/api/symlink",draft:!1,unlisted:!1,tags:[],version:"current",frontMatter:{id:"symlink",title:"symlink()",hide_title:!0,sidebar_label:"symlink()"},sidebar:"docs",previous:{title:"dest()",permalink:"/docs/en/api/dest"},next:{title:"lastRun()",permalink:"/docs/en/api/lastrun"}},c={},o=[{value:"Usage",id:"usage",level:2},{value:"Signature",id:"signature",level:2},{value:"Parameters",id:"parameters",level:3},{value:"Returns",id:"returns",level:3},{value:"Errors",id:"errors",level:3},{value:"Options",id:"options",level:3},{value:"Symbolic links on Windows",id:"symbolic-links-on-windows",level:2}];function h(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,s.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.h1,{id:"symlink",children:"symlink()"}),"\n",(0,i.jsxs)(n.p,{children:["Creates a stream for linking ",(0,i.jsx)(n.a,{href:"/docs/en/api/concepts#vinyl",children:"Vinyl"})," objects to the file system."]}),"\n",(0,i.jsx)(n.h2,{id:"usage",children:"Usage"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"const { src, symlink } = require('gulp');\n\nfunction link() {\n return src('input/*.js')\n .pipe(symlink('output/'));\n}\n\nexports.link = link;\n"})}),"\n",(0,i.jsx)(n.h2,{id:"signature",children:"Signature"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-js",children:"symlink(directory, [options])\n"})}),"\n",(0,i.jsx)(n.h3,{id:"parameters",children:"Parameters"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{style:{textAlign:"center"},children:"parameter"}),(0,i.jsx)(n.th,{style:{textAlign:"center"},children:"type"}),(0,i.jsx)(n.th,{children:"note"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsxs)(n.td,{style:{textAlign:"center"},children:["directory",(0,i.jsx)("br",{}),(0,i.jsx)(n.strong,{children:"(required)"})]}),(0,i.jsxs)(n.td,{style:{textAlign:"center"},children:["string",(0,i.jsx)("br",{}),"function"]}),(0,i.jsx)(n.td,{children:"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."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"center"},children:"options"}),(0,i.jsx)(n.td,{style:{textAlign:"center"},children:"object"}),(0,i.jsxs)(n.td,{children:["Detailed in ",(0,i.jsx)(n.a,{href:"#options",children:"Options"})," below."]})]})]})]}),"\n",(0,i.jsx)(n.h3,{id:"returns",children:"Returns"}),"\n",(0,i.jsx)(n.p,{children:"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."}),"\n",(0,i.jsx)(n.p,{children:"Whenever a symbolic link is created on the file system, the Vinyl object will be modified."}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["The ",(0,i.jsx)(n.code,{children:"cwd"}),", ",(0,i.jsx)(n.code,{children:"base"}),", and ",(0,i.jsx)(n.code,{children:"path"})," properties will be updated to match the created symbolic link."]}),"\n",(0,i.jsxs)(n.li,{children:["The ",(0,i.jsx)(n.code,{children:"stat"})," property will be updated to match the symbolic link on the file system."]}),"\n",(0,i.jsxs)(n.li,{children:["The ",(0,i.jsx)(n.code,{children:"contents"})," property will be set to ",(0,i.jsx)(n.code,{children:"null"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:["The ",(0,i.jsx)(n.code,{children:"symlink"})," property will be added or replaced with original path."]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Note:"})," On Windows, directory links are created using junctions by default. The ",(0,i.jsx)(n.code,{children:"useJunctions"})," option disables this behavior."]}),"\n",(0,i.jsx)(n.h3,{id:"errors",children:"Errors"}),"\n",(0,i.jsxs)(n.p,{children:["When ",(0,i.jsx)(n.code,{children:"directory"}),' is an empty string, throws an error with the message, "Invalid symlink() folder argument. Please specify a non-empty string or a function."']}),"\n",(0,i.jsxs)(n.p,{children:["When ",(0,i.jsx)(n.code,{children:"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."']}),"\n",(0,i.jsxs)(n.p,{children:["When ",(0,i.jsx)(n.code,{children:"directory"})," is a function that returns an empty string or ",(0,i.jsx)(n.code,{children:"undefined"}),', emits an error with the message, "Invalid output folder".']}),"\n",(0,i.jsx)(n.h3,{id:"options",children:"Options"}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"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."})}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{style:{textAlign:"center"},children:"name"}),(0,i.jsx)(n.th,{style:{textAlign:"center"},children:"type"}),(0,i.jsx)(n.th,{children:"default"}),(0,i.jsx)(n.th,{children:"note"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"center"},children:"cwd"}),(0,i.jsxs)(n.td,{style:{textAlign:"center"},children:["string",(0,i.jsx)("br",{}),"function"]}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"process.cwd()"})}),(0,i.jsxs)(n.td,{children:["The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining ",(0,i.jsx)(n.code,{children:"directory"})," with ",(0,i.jsx)(n.code,{children:"path.join()"}),"."]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"center"},children:"dirMode"}),(0,i.jsxs)(n.td,{style:{textAlign:"center"},children:["number",(0,i.jsx)("br",{}),"function"]}),(0,i.jsx)(n.td,{}),(0,i.jsx)(n.td,{children:"The mode used when creating directories. If not set, the process' mode will be used."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"center"},children:"overwrite"}),(0,i.jsxs)(n.td,{style:{textAlign:"center"},children:["boolean",(0,i.jsx)("br",{}),"function"]}),(0,i.jsx)(n.td,{children:"true"}),(0,i.jsx)(n.td,{children:"When true, overwrites existing files with the same path."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"center"},children:"relativeSymlinks"}),(0,i.jsxs)(n.td,{style:{textAlign:"center"},children:["boolean",(0,i.jsx)("br",{}),"function"]}),(0,i.jsx)(n.td,{children:"false"}),(0,i.jsxs)(n.td,{children:["When false, any symbolic links created will be absolute.",(0,i.jsx)("br",{}),(0,i.jsx)(n.strong,{children:"Note"}),": Ignored if a junction is being created, as they must be absolute."]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{style:{textAlign:"center"},children:"useJunctions"}),(0,i.jsxs)(n.td,{style:{textAlign:"center"},children:["boolean",(0,i.jsx)("br",{}),"function"]}),(0,i.jsx)(n.td,{children:"true"}),(0,i.jsxs)(n.td,{children:["This option is only relevant on Windows and ignored elsewhere. When true, creates directory symbolic link as a junction. Detailed in ",(0,i.jsx)(n.a,{href:"#symbolic-links-on-windows",children:"Symbolic links on Windows"})," below."]})]})]})]}),"\n",(0,i.jsx)(n.h2,{id:"symbolic-links-on-windows",children:"Symbolic links on Windows"}),"\n",(0,i.jsxs)(n.p,{children:["When creating symbolic links on Windows, a ",(0,i.jsx)(n.code,{children:"type"})," argument is passed to Node's ",(0,i.jsx)(n.code,{children:"fs.symlink()"})," method which specifies the type of target being linked. The link type is set to:"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"'file'"})," when the target is a regular file"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"'junction'"})," when the target is a directory"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"'dir'"})," when the target is a directory and the user disables the ",(0,i.jsx)(n.code,{children:"useJunctions"})," option"]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["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 ",(0,i.jsx)(n.code,{children:"symlink()"})," or via ",(0,i.jsx)(n.code,{children:"dest()"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["For dangling links created via ",(0,i.jsx)(n.code,{children:"symlink()"}),", the incoming Vinyl object represents the target, so its stats will determine the desired link type. If ",(0,i.jsx)(n.code,{children:"isDirectory()"})," returns false then a ",(0,i.jsx)(n.code,{children:"'file'"})," link is created, otherwise a ",(0,i.jsx)(n.code,{children:"'junction'"})," or ",(0,i.jsx)(n.code,{children:"'dir'"})," link is created depending on the value of the ",(0,i.jsx)(n.code,{children:"useJunctions"})," option."]}),"\n",(0,i.jsxs)(n.p,{children:["For dangling links created via ",(0,i.jsx)(n.code,{children:"dest()"}),", the incoming Vinyl object represents the link - typically loaded from disk via ",(0,i.jsx)(n.code,{children:"src(..., { resolveSymlinks: false })"}),". In this case, the link type can't be reasonably determined and defaults to using ",(0,i.jsx)(n.code,{children:"'file'"}),". This may cause unexpected behavior when creating a dangling link to a directory. ",(0,i.jsx)(n.strong,{children:"Avoid this scenario."})]})]})}function a(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(h,{...e})}):h(e)}},8453:(e,n,t)=>{t.d(n,{R:()=>l,x:()=>d});var i=t(6540);const s={},r=i.createContext(s);function l(e){const n=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:l(e.components),i.createElement(r.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.