doc: `require` behavior on case-insensitive systems

This adds a paragraph in the Module Caching Caveats section about the
behavior of require when Node is running on top of a file system (e.g.
HFS) or operating system (e.g. Windows) that will not consider the case
of file paths to find files.

Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Alexis Campailla <orangemocha@nodejs.org>
Reviewed-By: Rod Vagg <rod@vagg.org>
Reviewed-By: Roman Reiss <me@silverwind.io>

diff --git a/doc/api/modules.markdown b/doc/api/modules.markdown
index bd715f9..4c4cacb 100644 (file)
--- a/doc/api/modules.markdown
+++ b/doc/api/modules.markdown
@@ -212,6 +212,12 @@ module (loading from `node_modules` folders), it is not a *guarantee*
 that `require('foo')` will always return the exact same object, if it
 would resolve to different files.
 
+Additionally, on case-insensitive file systems or operating systems, different
+resolved filenames can point to the same file, but the cache will still treat
+them as different modules and will reload the file multiple times. For example,
+`require('./foo')` and `require('./FOO')` return two different objects,
+irrespective of whether or not `./foo` and `./FOO` are the same file.
+
 ## Core Modules
 
 <!--type=misc-->