How to still use existing $PATH in "cmd" modules

Enhances #21840

Added a code example on how to still use the existing $PATH environment
variables in cmd modules. The code was taken from a mail from Ethan
Erchinger to the salt-users list.

doc/man/salt.7

@@ -139505,6 +139505,22 @@ bar-script:
     - env: "PATH=/some/path:$PATH"
 .UNINDENT
 .UNINDENT
+.sp
+One can still use the existing $PATH with the help of some Jinja code:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}
+
+mycommand:
+  cmd.run:
+    - name: ls -l /
+    - env:
+      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
+.UNINDENT
+.UNINDENT
 .TP
 .B stateful
 The command being executed is expected to return data about executing
@@ -139649,6 +139665,22 @@ literal '$PATH':
     - env: "PATH=/some/path:$PATH"
 .UNINDENT
 .UNINDENT
+.sp
+One can still use the existing $PATH with the help of some Jinja code:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}
+
+mycommand:
+  cmd.run:
+    - name: ls -l /
+    - env:
+      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
+.UNINDENT
+.UNINDENT
 .TP
 .B umask
 The umask (in octal) to use when running the command.
@@ -139755,6 +139787,22 @@ script-bar:
     - env: "PATH=/some/path:$PATH"
 .UNINDENT
 .UNINDENT
+.sp
+One can still use the existing $PATH with the help of some Jinja code:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}
+
+mycommand:
+  cmd.run:
+    - name: ls -l /
+    - env:
+      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
+.UNINDENT
+.UNINDENT
 .TP
 .B umask
 The umask (in octal) to use when running the command.
@@ -139867,6 +139915,22 @@ literal '$PATH':
     - env: "PATH=/some/path:$PATH"
 .UNINDENT
 .UNINDENT
+.sp
+One can still use the existing $PATH with the help of some Jinja code:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}
+
+mycommand:
+  cmd.run:
+    - name: ls -l /
+    - env:
+      - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
+.UNINDENT
+.UNINDENT
 .TP
 .B umask
 The umask (in octal) to use when running the command.

salt/states/cmd.py

@@ -451,6 +451,18 @@ def wait(name,
               cmd.wait:
                 - env: "PATH=/some/path:$PATH"
 
+        One can still use the existing $PATH by using a bit of Jinja:
+
+        .. code-block:: yaml
+
+            {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}
+
+            mycommand:
+              cmd.run:
+                - name: ls -l /
+                - env:
+                  - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
+
     umask
          The umask (in octal) to use when running the command.
 
@@ -568,6 +580,18 @@ def wait_script(name,
               cmd.wait_script:
                 - env: "PATH=/some/path:$PATH"
 
+        One can still use the existing $PATH by using a bit of Jinja:
+
+        .. code-block:: yaml
+
+            {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}
+
+            mycommand:
+              cmd.run:
+                - name: ls -l /
+                - env:
+                  - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
+
     umask
          The umask (in octal) to use when running the command.
 
@@ -667,6 +691,18 @@ def run(name,
               cmd.run:
                 - env: "PATH=/some/path:$PATH"
 
+        One can still use the existing $PATH by using a bit of Jinja:
+
+        .. code-block:: yaml
+
+            {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}
+
+            mycommand:
+              cmd.run:
+                - name: ls -l /
+                - env:
+                  - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
+
     stateful
         The command being executed is expected to return data about executing
         a state
@@ -881,6 +917,18 @@ def script(name,
               cmd.script:
                 - env: "PATH=/some/path:$PATH"
 
+        One can still use the existing $PATH by using a bit of Jinja:
+
+        .. code-block:: yaml
+
+            {% set current_path = salt['environ.get']('PATH', '/bin:/usr/bin') %}
+
+            mycommand:
+              cmd.run:
+                - name: ls -l /
+                - env:
+                  - PATH: {{ [current_path, '/my/special/bin']|join(':') }}
+
     umask
          The umask (in octal) to use when running the command.