From 9f4a63b2c04fa2549d841f9a1858e296e93acc71 Mon Sep 17 00:00:00 2001 From: Blaine Bublitz Date: Sun, 7 Apr 2024 21:10:44 -0700 Subject: [PATCH] chore: Update glob docs with replacement to ordered globs --- docs/getting-started/6-explaining-globs.md | 28 +++++++++++++++------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/getting-started/6-explaining-globs.md b/docs/getting-started/6-explaining-globs.md index 11f34fae0..4517d8aaa 100644 --- a/docs/getting-started/6-explaining-globs.md +++ b/docs/getting-started/6-explaining-globs.md @@ -9,7 +9,7 @@ sidebar_label: Explaining Globs A glob is a string of literal and/or wildcard characters used to match filepaths. Globbing is the act of locating files on a filesystem using one or more globs. -The `src()` method expects a single glob string or an array of globs to determine which files your pipeline will operate on. At least one match must be found for your glob(s) otherwise `src()` will error. When an array of globs is used, they are matched in array order - especially useful for negative globs. +The `src()` method expects a single glob string or an array of globs to determine which files your pipeline will operate on. At least one match must be found for your glob(s) otherwise `src()` will error. When an array of globs is used, any negative globs will remove matches from any positive glob. ## Segments and separators @@ -49,26 +49,37 @@ Here, the glob is appropriately restricted to the `scripts/` directory. It will ## Special character: ! (negative) -Since globs are matched in array order, a negative glob must follow at least one non-negative glob in an array. The first finds a set of matches, then the negative glob removes a portion of those results. When excluding all files within a directory, you must add `/**` after the directory name, which the globbing library optimizes internally. +Globs prefixed with the `!` character will "negate" the glob, excluding the match completely. All negative globs are applied to every positive glob, which is a departure from gulp versions before v5. + +Here, the `scripts/` directory will be traversed for all files ending in `.js`, but all files from the `scripts/vendor/` directory will be excluded. ```js ['scripts/**/*.js', '!scripts/vendor/**'] ``` -If any non-negative globs follow a negative, nothing will be removed from the later set of matches. +Negative globs can be used as an alternative for restricting double-star globs. ```js -['scripts/**/*.js', '!scripts/vendor/**', 'scripts/vendor/react.js'] +['**/*.js', '!node_modules/**'] ``` -Negative globs can be used as an alternative for restricting double-star globs. +## Ordered globs + +Versions of gulp before v5 allowed "ordered globs"; however, that has been removed to align with most globbing libraries in the ecosystem. + +If you need the "ordered glob" functionality, you can use the [ordered-read-streams][ordered-read-streams-docs] library to combine streams: ```js -['**/*.js', '!node_modules/**'] +const order = require("ordered-read-streams"); + +exports.default = function () { + return order([ + gulp.src("input/jquery/dist/jquery.js"), + gulp.src("input/detect_swipe/jquery.detect_swipe.js"), + ]).pipe(gulp.dest('output/')); +} ``` -In the previous example, if the negative glob was `!node_modules/**/*.js`, the globbing library wouldn't optimize the negation and every match would have to be compared against the negative glob, which would be extremely slow. To ignore all files in a directory, only add the `/**` glob after the directory name. - ## Overlapping globs Two or more globs that (un)intentionally match the same file are considered overlapping. When overlapping globs are used within a single `src()`, gulp does its best to remove the duplicates, but doesn't attempt to deduplicate across separate `src()` calls. @@ -86,3 +97,4 @@ Most of what you'll need to work with globs in gulp is covered here. If you'd li [glob-primer-docs]: https://github.com/isaacs/node-glob#glob-primer [begin-globbing-docs]: https://github.com/begin/globbing#what-is-globbing [wikipedia-glob]: https://en.wikipedia.org/wiki/Glob_(programming) +[ordered-read-streams-docs]: https://github.com/gulpjs/ordered-read-streams#orderedstreams-options