Inconsistent case handling in grunt.file.expand on case‑insensitive file systems

Answer to the core question

What happens when grunt.file.expand is asked to match files that differ only by letter case on a case‑insensitive file system?

On Windows (NTFS) and macOS (HFS+ or APFS with default options), the underlying file system treats foo.txt and Foo.txt as the same path. Node’s fs.readdir returns a single entry with the case that actually exists on disk. Minimatch, which Grunt 1.x+ uses for globbing, does not perform case folding unless the nocase option is explicitly set. Consequently:

• Both variants cannot exist simultaneously on a single case‑insensitive mount. If the directory contains only one of them, that single name is returned.
• When a pattern is case‑insensitive (the default on Windows/macOS), minimatch will match the single stored name once. The array returned by grunt.file.expand will contain that single entry, in the order fs.readdir delivers it.

On Linux (or any case‑sensitive mount), the file system distinguishes foo.txt and Foo.txt. Minimatch’s default is case‑sensitive, so:

• If you use a case‑sensitive pattern (e.g., foo.txt), only that exact file is returned.
• If you use a case‑insensitive pattern (e.g., **/*.txt with nocase:true), both files are matched and returned, again preserving the order from fs.readdir.

In short, grunt.file.expand never collapses duplicates; it simply aggregates matches from all directories visited. The result is deterministic only within a single file‑system mount. Mixing case‑insensitive and case‑sensitive mounts can produce unpredictable ordering or apparent duplicates.

Confirmed facts

1. Grunt 1.x+ uses the minimatch library for pattern matching.
2. Minimatch is case‑sensitive by default; it becomes case‑insensitive only if nocase:true is set.
3. Node’s fs.readdir returns names exactly as stored; on case‑insensitive systems it returns one entry per logical file.
4. There is no internal deduplication logic in grunt.file.expand.
5. Symlinks are resolved by fs.readdir; a symlink that points to a file with a different case name will appear as a distinct entry.

Practical verification steps

1. Create a test directory containing the files foo.txt and Foo.txt (on Linux only; Windows/macOS can only hold one).
2. In a Node REPL, load Grunt and run:

   const grunt = require('grunt');
   console.log(grunt.file.expand(['**/*.txt'], {cwd: '/path/to/test'}));
   

3. Record the output array on Windows, macOS, and Linux.
4. Repeat the test with the nocase:true option in the glob configuration to see the difference on Linux.
5. If your Gruntfile sets caseSensitive or nocase globally, adjust the test accordingly.

What to do for consistent results

If your build must behave the same on all platforms, you can enforce case sensitivity explicitly:

grunt.file.expand(['**/*.txt'], {caseSensitive: true});

or, in the Gruntfile, set the globOptions for all tasks:

grunt.initConfig({
  pkg: grunt.file.readJSON('package.json'),
  globOptions: {caseSensitive: true}
});

Beware that this will skip matches on case‑insensitive file systems if the pattern’s case does not match the stored case.

Missing diagnostic detail

Does your Gruntfile or any plugin explicitly set nocase or caseSensitive in the glob options?