Reduced test case demonstrating incompatibility with Node "path" module

[Dan503]

I figured out what the real bug in Gulp 4 was :) This explains both issues #2093 & #2094.

The reason it was working in your reduced test case and it wasn't working in my environment was because my environment was using Nodes "path" module to generate the strings where as the reduced test case was only using explicit strings.

Every file added in this commit is a demonstration of the bug in action. They were generated by gulp when the should not be.

[jonschlinkert]

you should be using {cwd: src} and not using path.join() on glob patterns. Glob patterns are regular expressions, not paths. fwiw, using the path module might lead to unexpected patterns that do not work. For example, on windows path.join() will use backslashes. In regular expressions, backslashes are not path separators, they are escape characters.

[Dan503]

The point is that both Gulp 3 and Gulp 4-alpha.2 supported this feature so people will expect to be able to use that syntax in Gulp 4.0.0, especially since path is a native Node plugin.

In my experience on Windows, path.join() is essentially the equivalent of writing ['folder ','path'].join('\'). It does feature back slashes but they are escaped backslashes so I don't see that being an issue.

Not supporting path.join() could break a lot of gulp set ups and it isn't obvious why Gulp isn't acting the way it's supposed to. People just think Gulp is broken and might try and swap to using something else.

Can there at least be an error that is thrown when Gulp 4 encounters path.join() if you don't want to make it compatible? Or maybe just have it documented in the Gulp documentation for src, dest, & watch that path.join() should not be used to merge folder paths and instead use the ['folder ','path'].join('/') pattern?

It's really hard to figure out why Gulp isn't working properly if you do happen to use path.join() in your gulp file, especially since it has worked just fine with every previous version of Gulp.

[doowb]

Can there at least be an error that is thrown when Gulp 4 encounters path.join()

There's no way to tell that path.join was used. The string being input could be a glob pattern with escaped glob characters. The point is that gulp.src takes a glob pattern or array of glob patterns as the first argument and not file paths.

Below I'm linking to some related issues about why there are breaking changes in Gulp 4 and why path.join shouldn't be used for glob patterns.

• This issue has more details on what gulp.src expects: Problems with src and path since alpha3/v4  gulpjs/gulp#2085
• In this comment, @phated explains more about gulp 4 and the alpha versions: install gulp#v4.0.0-alpha.2 git damaged gulpjs/gulp#2078 (comment)
• This issue has information about work going on to update the README.md with new features and changes for gulp 4: [Docs] Add "New Features" section to README gulpjs/gulp#2089

Or maybe just have it documented in the Gulp documentation for src, dest, & watch that path.join() should not be used

Any help with updating documentation is appreciated. Check with the last bullet in the list to see what progress has been made.

[jonschlinkert]

The point is that both Gulp 3 and Gulp 4-alpha.2 supported this feature so people will expect to be able to use that syntax in Gulp 4.0.0, especially since path is a native Node plugin.

Joining a glob with node's path module is like creating a regex with the path module. As @doowb mentions, there is no way to know when you intended to use \\ as a path separator versus when it was intended to escape a character, like \\*. Since, believe it or not, * is a valid path character on some systems, as are all of the following characters: !@#$%^&*()[]. If we do what you are suggesting, then users will not be able to define globs to match paths with those characters.