From e552838d36926960e5eca14e14e0e3bded7ffa60 Mon Sep 17 00:00:00 2001
From: Robin Doermann <robin.doermann@mecklenburgcountync.gov>
Date: Fri, 28 Mar 2025 10:46:34 -0400
Subject: [PATCH 1/2] [DOCS] Add information about lack of support for symbolic
 file modes

---
 salt/states/file.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/salt/states/file.py b/salt/states/file.py
index 3f3582e0cff3..c28552067424 100644
--- a/salt/states/file.py
+++ b/salt/states/file.py
@@ -103,6 +103,11 @@ def run():
     value in single quotes. If the value is not wrapped in quotes it
     will be read by YAML as an integer and evaluated as an octal.
 
+.. note::
+    Salt only supports numeric mode specifications (like ``644``)
+    and does not support symbolic modes (like ``u+rw``) that are commonly used
+    with commands like ``chmod``.
+
 The ``names`` parameter, which is part of the state compiler, can be used to
 expand the contents of a single state declaration into multiple, single state
 declarations. Each item in the ``names`` list receives its own individual state
@@ -2556,6 +2561,11 @@ def managed(
         .. note::
             This option is **not** supported on Windows.
 
+        .. note::
+            Salt's file module only supports numeric mode specifications
+            (like ``644``) and does not support symbolic modes (like ``u+rw``)
+            that are commonly used with commands like ``chmod``.
+
         .. versionchanged:: 2016.11.0
             This option can be set to ``keep``, and Salt will keep the mode
             from the Salt fileserver. This is only supported when the
@@ -3851,6 +3861,10 @@ def directory(
         The default mode for new files and directories corresponds umask of salt
         process. For existing files and directories it's not enforced.
 
+        The file module only supports numeric mode specifications (like ``644``)
+        and does not support symbolic modes like ``u+rw``) that are commonly
+        used with commands like ``chmod``.
+
     makedirs
         If the directory is located in a path without a parent directory, then
         the state will fail. If makedirs is set to True, then the parent

From 8c6fd311bd4de192d3852e5642f35ed46dab2710 Mon Sep 17 00:00:00 2001
From: Robin Doermann <robin.doermann@mecklenburgcountync.gov>
Date: Fri, 28 Mar 2025 11:10:30 -0400
Subject: [PATCH 2/2] Add changelog entry for file module mode documentation,
 issue 64624

---
 changelog/64624.added.md | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelog/64624.added.md

diff --git a/changelog/64624.added.md b/changelog/64624.added.md
new file mode 100644
index 000000000000..10d0bb01df8a
--- /dev/null
+++ b/changelog/64624.added.md
@@ -0,0 +1 @@
+Adds documentation notes to clarify that Salt's file module only supports numeric mode specifications and does not support symbolic modes.