From ead1635e782aec843ac69f70897c29176da40515 Mon Sep 17 00:00:00 2001 From: Nathan Phillip Brink Date: Mon, 11 Apr 2022 03:19:52 +0000 Subject: [PATCH 1/4] Fix documentation concerning glob expansion on UNIX. Fixes #4868. --- docs/index.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 2f8324e0a3..79bf37fb52 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2332,9 +2332,12 @@ $ mocha "./spec/**/*.js" ``` [You should _always_ quote your globs in npm scripts][article-globbing]. If you -use double quotes, it's the shell on UNIX that will expand the glob. On the -other hand, if you use single quotes, the [`node-glob`][npm-glob] module will -handle its expansion. +use double quotes or single quotes, the [`node-glob`][npm-glob] module will +handle its expansion. Single quotes are not supported on Windows, so you should +avoid them. Note that UNIX shells will perform +[parameter expansion](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03) +within double quotes, so avoid using a dollar sign or backslash in any of your +paths if you want to support UNIX. See this [tutorial][gist-globbing-tutorial] on using globs. From d5c86e23084af8c0f826ccc093f60867868a4f89 Mon Sep 17 00:00:00 2001 From: Nathan Phillip Brink Date: Tue, 5 Mar 2024 13:40:23 -0500 Subject: [PATCH 2/4] Increase concision. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Josh Goldberg ✨ --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 79bf37fb52..8fcf0f3c4d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2333,8 +2333,8 @@ $ mocha "./spec/**/*.js" [You should _always_ quote your globs in npm scripts][article-globbing]. If you use double quotes or single quotes, the [`node-glob`][npm-glob] module will -handle its expansion. Single quotes are not supported on Windows, so you should -avoid them. Note that UNIX shells will perform +handle its expansion. Single quotes are not supported on Windows. +Note that UNIX shells will perform [parameter expansion](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03) within double quotes, so avoid using a dollar sign or backslash in any of your paths if you want to support UNIX. From ab6bed3b4d8aaa32669aa4f314cbd5c63cb0d059 Mon Sep 17 00:00:00 2001 From: Nathan Phillip Brink Date: Tue, 12 Mar 2024 12:31:18 -0400 Subject: [PATCH 3/4] Remove reference to misleading article and any platforms MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit https://github.com/mochajs/mocha/pull/4869#pullrequestreview-1931377316 requested that platforms and shells not be mentioned. This means that rationale for the directions cannot be provided. The article which was originally linked suggests to use single quotes which do not work on Windows. For example, using single quotes for a glob expression referring to a folder or file with `&` in its name would break the expression into two commands on Windows. Since the rationale was removed and the linked article was misleading, instructions on how to correctly quote globs were added. The rationale is recorded here since it isn’t allowed in the instructions: * Since a Unix-like OS user would be accustomed to referencing a path containing `"` in it by writing `\"` within a double-quoted string, I mentioned that the double quote and backslash characters are forbidden. * Since a Windows user would be accustomed to including `$` in file names but double quoted strings have parameter expansion performed on them on on Unix-like OSes, I had to mention that `$` is a forbidden character. * Since Windows doesn’t support single quotes, I had to mention that double quotes are required. --- docs/index.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/index.md b/docs/index.md index 8fcf0f3c4d..fe627cb009 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2331,13 +2331,11 @@ Some shells support recursive matching by using the globstar (`**`) wildcard. Ba $ mocha "./spec/**/*.js" ``` -[You should _always_ quote your globs in npm scripts][article-globbing]. If you -use double quotes or single quotes, the [`node-glob`][npm-glob] module will -handle its expansion. Single quotes are not supported on Windows. -Note that UNIX shells will perform -[parameter expansion](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03) -within double quotes, so avoid using a dollar sign or backslash in any of your -paths if you want to support UNIX. +You should _always_ quote your globs in npm scripts. If you +use quotes, the [`node-glob`][npm-glob] module will +handle its expansion. To support popular platforms, you must +surround the entire expression with double quotes and refrain +from `$`, `"`, `^`, and `\` within your expression. See this [tutorial][gist-globbing-tutorial] on using globs. @@ -2430,7 +2428,6 @@ For discussions join the [Google Group][google-mocha]. For a running example of or the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js). [//]: # 'Cross reference section' -[article-globbing]: https://medium.com/@jakubsynowiec/you-should-always-quote-your-globs-in-npm-scripts-621887a2a784 [bash-globbing]: https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html [better-assert]: https://github.com/visionmedia/better-assert [caniuse-notifications]: https://caniuse.com/#feat=notifications From 7129fbfa186443838e50ab8d6063ec09f8c73b3a Mon Sep 17 00:00:00 2001 From: Nathan Phillip Brink Date: Tue, 12 Mar 2024 12:54:03 -0400 Subject: [PATCH 4/4] Accept wording change Co-authored-by: Pelle Wessman --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index fe627cb009..1b5cba3b53 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2333,7 +2333,7 @@ $ mocha "./spec/**/*.js" You should _always_ quote your globs in npm scripts. If you use quotes, the [`node-glob`][npm-glob] module will -handle its expansion. To support popular platforms, you must +handle its expansion. For maximum compatibility, surround the entire expression with double quotes and refrain from `$`, `"`, `^`, and `\` within your expression.