docs(chmod): briefly mention Windows file perms

nfischer · nfischer · commit 6538d92930c8 · 2022-01-15T12:11:59.000-08:00
File permissions on Windows are weird. This adds a brief note into the
README that this is something to watch out for. As far as I'm aware, WSL
completely avoids the weirdness because it's actually Linux (and so it
follows POSIX).
diff --git a/README.md b/README.md
@@ -187,6 +187,10 @@ Notable exceptions:
 + In symbolic modes, `a-r` and `-r` are identical.  No consideration is
   given to the `umask`.
 + There is no "quiet" option, since default behavior is to run silent.
++ Windows OS uses a very different permission model than POSIX. `chmod()`
+  does its best on Windows, but there are limits to how file permissions can
+  be set. Note that WSL (Windows subsystem for Linux) **does** follow POSIX,
+  so cross-platform compatibility should not be a concern there.
 
 Returns a [ShellString](#shellstringstr) indicating success or failure.
 
diff --git a/src/chmod.js b/src/chmod.js
@@ -59,6 +59,10 @@ common.register('chmod', _chmod, {
 //@ + In symbolic modes, `a-r` and `-r` are identical.  No consideration is
 //@   given to the `umask`.
 //@ + There is no "quiet" option, since default behavior is to run silent.
+//@ + Windows OS uses a very different permission model than POSIX. `chmod()`
+//@   does its best on Windows, but there are limits to how file permissions can
+//@   be set. Note that WSL (Windows subsystem for Linux) **does** follow POSIX,
+//@   so cross-platform compatibility should not be a concern there.
 //@
 //@ Returns a [ShellString](#shellstringstr) indicating success or failure.
 function _chmod(options, mode, filePattern) {
