Cygwin: document W10 1803 per-directory case-sensitivity behaviour

Signed-off-by: Corinna Vinschen <corinna@vinschen.de>

1 files changed, 33 insertions, 0 deletions

diff --git a/winsup/doc/specialnames.xml b/winsup/doc/specialnames.xml
index bc4b0440d..f27836032 100644
--- a/winsup/doc/specialnames.xml
+++ b/winsup/doc/specialnames.xml
@@ -215,6 +215,39 @@ Read on for more information.</para>
 
 </sect2>
 
+<sect2 id="pathnames-casesensitivedirs">
+<title>Case sensitive directories</title>
+
+<para>Windows 10 1803 introduced a new feature: NTFS directories can be marked
+as case-sensitive, independently of the <literal>obcaseinsensitive</literal>
+registry key discussed in the previous section.  This new per-directory
+case-sensitivity requires setting a flag in the NTFS filesystem header which
+is, unfortunately, undocumented.  The result is that you have to activate
+<literal>Windows Subsystem for Linux</literal> (<literal>WSL</literal>), a
+feature available via <literal>Programs and Features</literal> ->
+<literal>Turn Windows features on or off</literal>.  You only have to activate
+<literal>WSL</literal>, you don't have to install any actual Linux.  After
+turning <literal>WSL</literal> on and performing the compulsory reboot,
+case-sensitive directories are activated.</para>
+
+<para>With <literal>WSL</literal> activated and starting with Cygwin 3.0,
+Cygwin's <command>mkdir</command> system call will automatically create all
+directories below the Cygwin installation directory as case-sensitive.
+Directories created outside the Cygwin installation tree will be left
+alone.  However, you can use Cygwin's new <xref linkend="chattr"></xref> tool
+with the <literal>-C</literal> option to control case-sensitivity of
+directories on NTFS filesystems.</para>
+
+<para>Please keep in mind that switching <emphasis>off</emphasis>
+case-sensitivity on a directory has a condition attached to it:  If
+the directory contains two files which only differ in case (e. g.,
+<filename>foo</filename> and <filename>FOO</filename>), Windows
+refuses to convert the dir back to case-insensitive.  First you have
+to fix the filename collision, i. e., you have to rename one of these
+files.</para>
+
+</sect2>
+
 <sect2 id="pathnames-posixdevices"> <title>POSIX devices</title>
 <para>While there is no need to create a POSIX <filename>/dev</filename> 
 directory, the directory is automatically created as part of a Cygwin