From 04a30d168b3501cf283de5b2abd6a551cfe57c85 Mon Sep 17 00:00:00 2001
From: Nate Fischer <ntfschr@google.com>
Date: Sun, 18 Feb 2024 01:04:02 -0800
Subject: [PATCH] deprecate config.globOptions

This deprecates support for configuring `config.globOptions`. Exposing
this variable makes it difficult to change (or upgrade) our glob
library. This discourages users from depending on this config option
going forward.

If anyone is using `config.globOptions` then it should continue to
function, however this support is not promised for the long-term.

As far as I know, this is not a commonly used option:
https://github.com/shelljs/shelljs/issues?q=globOptions currently shows
no GitHub issues of users using this option, and there was never really
a motivation for why this needed to be exposed (#400 exposed the option
just because we could, not because we should).

This is one step toward supporting Issue #828.
---
 README.md     | 12 ++++++++++--
 shell.js      | 12 ++++++++++--
 src/common.js |  8 +++++++-
 3 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 357e5a47..a467327d 100644
--- a/README.md
+++ b/README.md
@@ -854,7 +854,11 @@ rm -rf foo.txt bar.txt
 exec echo hello
 ```
 
-### config.globOptions
+### config.globOptions (deprecated)
+
+**Deprecated**: we recommend that you do not edit `config.globOptions`.
+Support for this configuration option may be changed or removed in a future
+ShellJS release.
 
 Example:
 
@@ -862,7 +866,11 @@ Example:
 config.globOptions = {nodir: true};
 ```
 
-Use this value for calls to `glob.sync()` instead of the default options.
+`config.globOptions` changes how ShellJS expands glob (wildcard)
+expressions. See
+[node-glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#options)
+for available options. Be aware that modifying `config.globOptions` **may
+break ShellJS functionality.**
 
 ### config.reset()
 
diff --git a/shell.js b/shell.js
index ad40740b..24df39a9 100644
--- a/shell.js
+++ b/shell.js
@@ -136,7 +136,11 @@ exports.config = common.config;
 //@ ```
 
 //@
-//@ ### config.globOptions
+//@ ### config.globOptions (deprecated)
+//@
+//@ **Deprecated**: we recommend that you do not edit `config.globOptions`.
+//@ Support for this configuration option may be changed or removed in a future
+//@ ShellJS release.
 //@
 //@ Example:
 //@
@@ -144,7 +148,11 @@ exports.config = common.config;
 //@ config.globOptions = {nodir: true};
 //@ ```
 //@
-//@ Use this value for calls to `glob.sync()` instead of the default options.
+//@ `config.globOptions` changes how ShellJS expands glob (wildcard)
+//@ expressions. See
+//@ [node-glob](https://github.com/isaacs/node-glob?tab=readme-ov-file#options)
+//@ for available options. Be aware that modifying `config.globOptions` **may
+//@ break ShellJS functionality.**
 
 //@
 //@ ### config.reset()
diff --git a/src/common.js b/src/common.js
index 0ec1f813..1ddbfabd 100644
--- a/src/common.js
+++ b/src/common.js
@@ -247,6 +247,12 @@ function parseOptions(opt, map, errorOptions) {
 }
 exports.parseOptions = parseOptions;
 
+function globOptions() {
+  // TODO(nfischer): if this changes glob implementation in the future, convert
+  // options back to node-glob's option format for backward compatibility.
+  return config.globOptions;
+}
+
 // Expands wildcards with matching (ie. existing) file names.
 // For example:
 //   expand(['file*.js']) = ['file1.js', 'file2.js', ...]
@@ -263,7 +269,7 @@ function expand(list) {
     } else {
       var ret;
       try {
-        ret = glob.sync(listEl, config.globOptions);
+        ret = glob.sync(listEl, globOptions());
         // if nothing matched, interpret the string literally
         ret = ret.length > 0 ? ret : [listEl];
       } catch (e) {