From 1341784184c15603abd4091bbbecfe9cd769d26d Mon Sep 17 00:00:00 2001
From: "Markus \"Shorty\" Uckelmann" <shorty@koeln.de>
Date: Thu, 16 Apr 2015 11:20:20 +0200
Subject: [PATCH] improve cmd.run env documentation

Resolves #21840

Improved documentation to cmd.run(et.al.) env argument by mentioning
that variables as values will not be evaluated.
---
 doc/man/salt.7     | 62 ++++++++++++++++++++++++++++++++++++++++++----
 salt/states/cmd.py | 46 ++++++++++++++++++++++++++++++----
 2 files changed, 98 insertions(+), 10 deletions(-)

diff --git a/doc/man/salt.7 b/doc/man/salt.7
index 59f6f067e6..5f1bf17642 100644
--- a/doc/man/salt.7
+++ b/doc/man/salt.7
@@ -138136,8 +138136,8 @@ Example:
 .sp
 .nf
 .ft C
-salt://scripts/foo.sh:
-  cmd.script:
+foo-script:
+  cmd.run:
     \- env:
       \- BATCH: \(aqyes\(aq
 .ft P
@@ -138155,6 +138155,19 @@ quotes to be used as strings. More info on this (and other) PyYAML
 idiosyncrasies can be found \fBhere\fP\&.
 .UNINDENT
 .UNINDENT
+.sp
+Variables as values are not evaluated. So $PATH in the following example is a
+literal '$PATH':
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+bar-script:
+  cmd.run:
+    - env: "PATH=/some/path:$PATH"
+.UNINDENT
+.UNINDENT
 .TP
 .B stateful
 The command being executed is expected to return data about executing
@@ -138286,6 +138299,19 @@ quotes to be used as strings. More info on this (and other) PyYAML
 idiosyncrasies can be found \fBhere\fP\&.
 .UNINDENT
 .UNINDENT
+.sp
+Variables as values are not evaluated. So $PATH in the following example is a
+literal '$PATH':
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ salt://scripts/bar.sh:
+  cmd.script:
+    - env: "PATH=/some/path:$PATH"
+.UNINDENT
+.UNINDENT
 .TP
 .B umask
 The umask (in octal) to use when running the command.
@@ -138360,8 +138386,8 @@ Example:
 .sp
 .nf
 .ft C
-salt://scripts/foo.sh:
-  cmd.script:
+script-foo:
+  cmd.wait:
     \- env:
       \- BATCH: \(aqyes\(aq
 .ft P
@@ -138379,6 +138405,19 @@ quotes to be used as strings. More info on this (and other) PyYAML
 idiosyncrasies can be found \fBhere\fP\&.
 .UNINDENT
 .UNINDENT
+.sp
+Variables as values are not evaluated. So $PATH in the following example is a
+literal '$PATH':
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+script-bar:
+  cmd.wait:
+    - env: "PATH=/some/path:$PATH"
+.UNINDENT
+.UNINDENT
 .TP
 .B umask
 The umask (in octal) to use when running the command.
@@ -138460,7 +138499,7 @@ Example:
 .nf
 .ft C
 salt://scripts/foo.sh:
-  cmd.script:
+  cmd.wait_script:
     \- env:
       \- BATCH: \(aqyes\(aq
 .ft P
@@ -138478,6 +138517,19 @@ quotes to be used as strings. More info on this (and other) PyYAML
 idiosyncrasies can be found \fBhere\fP\&.
 .UNINDENT
 .UNINDENT
+.sp
+Variables as values are not evaluated. So $PATH in the following example is a
+literal '$PATH':
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ salt://scripts/bar.sh:
+  cmd.wait_script:
+    - env: "PATH=/some/path:$PATH"
+.UNINDENT
+.UNINDENT
 .TP
 .B umask
 The umask (in octal) to use when running the command.
diff --git a/salt/states/cmd.py b/salt/states/cmd.py
index 5b1ce6a526..da3448c1e0 100644
--- a/salt/states/cmd.py
+++ b/salt/states/cmd.py
@@ -428,8 +428,8 @@ def wait(name,
 
         .. code-block:: yaml
 
-            salt://scripts/foo.sh:
-              cmd.script:
+            script-foo:
+              cmd.wait:
                 - env:
                   - BATCH: 'yes'
 
@@ -442,6 +442,15 @@ def wait(name,
             idiosyncrasies can be found :doc:`here
             </topics/troubleshooting/yaml_idiosyncrasies>`.
 
+        Variables as values are not evaluated. So $PATH in the following
+        example is a literal '$PATH':
+
+        .. code-block:: yaml
+
+            script-bar:
+              cmd.wait:
+                - env: "PATH=/some/path:$PATH"
+
     umask
          The umask (in octal) to use when running the command.
 
@@ -537,7 +546,7 @@ def wait_script(name,
         .. code-block:: yaml
 
             salt://scripts/foo.sh:
-              cmd.script:
+              cmd.wait_script:
                 - env:
                   - BATCH: 'yes'
 
@@ -550,6 +559,15 @@ def wait_script(name,
             idiosyncrasies can be found :doc:`here
             </topics/troubleshooting/yaml_idiosyncrasies>`.
 
+        Variables as values are not evaluated. So $PATH in the following
+        example is a literal '$PATH':
+
+        .. code-block:: yaml
+
+            salt://scripts/bar.sh:
+              cmd.wait_script:
+                - env: "PATH=/some/path:$PATH"
+
     umask
          The umask (in octal) to use when running the command.
 
@@ -626,8 +644,8 @@ def run(name,
 
         .. code-block:: yaml
 
-            salt://scripts/foo.sh:
-              cmd.script:
+            script-foo:
+              cmd.run:
                 - env:
                   - BATCH: 'yes'
 
@@ -640,6 +658,15 @@ def run(name,
             idiosyncrasies can be found :doc:`here
             </topics/troubleshooting/yaml_idiosyncrasies>`.
 
+        Variables as values are not evaluated. So $PATH in the following
+        example is a literal '$PATH':
+
+        .. code-block:: yaml
+
+            script-bar:
+              cmd.run:
+                - env: "PATH=/some/path:$PATH"
+
     stateful
         The command being executed is expected to return data about executing
         a state
@@ -845,6 +872,15 @@ def script(name,
             idiosyncrasies can be found :doc:`here
             </topics/troubleshooting/yaml_idiosyncrasies>`.
 
+        Variables as values are not evaluated. So $PATH in the following
+        example is a literal '$PATH':
+
+        .. code-block:: yaml
+
+            salt://scripts/bar.sh:
+              cmd.script:
+                - env: "PATH=/some/path:$PATH"
+
     umask
          The umask (in octal) to use when running the command.