Clarify nocase documentation (specifically when setting it to not match OS behavior)

[ohadschn]

The docs state:

nocase should only be explicitly set when it is known that the filesystem's case sensitivity differs from the platform default. If set true on case-sensitive file systems, or false on case-insensitive file systems, then the walk may return more or less results than expected.

1. It's not clear what is meant by may return more or less results than expected - perhaps some example could be provided?
2. Commit 02b76fd (following nocase:true not working properly on linux #526) suggests that explicitly setting nocase as to not match the OS behavior, even when it is known that the filesystem's case sensitivity differs from the platform default, is a legitimate scenario. If that is indeed the case, the wording above would ideally reflect that (as I read it, it currently suggests the opposite).

[isaacs]

Good point, doc patch welcome or I'll get to it eventually. Brain dumping the answer here, unpolished.

You can do a case insensitive match on a case sensitive file system, though it's a bit less efficient, because it requires regexp comparisons in all path portions, instead of just those containing magic.

However, the reverse is not true; you cannot correctly do a case sensitive match on a case insensitive file system, because stat('FILE') will succeed if file exists, and there's no efficient and reliable way to determine the "real" canonical case across platforms.

As to "more or less results than expected": if the case sensitivity setting doesn't match the system (and the heuristic mentioned in the PR isn't triggered; for example, a case sensitive macOS fs), then if there's a file at foo/BAR,

• Foo/* will not find a match, because readdir('Foo') fails
• foo/Ba* will return foo/BAR because the pattern is converted to a case insensitive regexp
• foo/Bar will not find a match.
• Fo*/BAR will find the match

which, all together, is a confusing

In the other direction, where the fs is case insensitive, but we THINK it's case sensitive,

• Foo/* will find the match
• foo/Ba* will find not the match
• foo/Bar will find the match
• Fo*/BAR will not find the match

In other words:

• incorrectly set as nocase:true
  • patterns match more than they should
  • strings match less than expected
  • Foo will find a match, but Fo* will not
• incorrectly set as nocase:false
  • patterns match less than they should
  • Strings match more than expected
  • Fo* will not find a match, but Foo will

[ohadschn]

@isaacs thank you for the quick and detailed response!

May I suggest breaking down the nocase setting to the following:

1. fscase - overrides the node-glob inference of the FS case sensitivity. For this setting, keep the instruction should only be explicitly set when it is known that the filesystem's case sensitivity differs from the platform default.. It should be pretty self- explanatory that unexpected results are to be produced when glob is fed misleading information. I wouldn't even bother with the examples above, as I suspect they might do more harm (confusion) than good.
2. matchCaseSensitivity - default to the resolved fscase. In case the latter is case-sensitive, allow case-insensitive matches (using the slower regex approach). In case the FS case is case-insensitive, throw an error if case-sensitive matches are requested. Again - I don't think any example is necessary, it should be clear that one can't ask the FS for something it doesn't support (if it doesn't discern between cases, you can't ask for case sensitivity in your matches).