Salt: cmd.shell should be documented

[notpeter]

Use of cmd.run currently generates a DeprecationWarning:

[WARNING ] /usr/lib/python2.7/dist-packages/salt/utils/templates.py:75: DeprecationWarning: Starting in 2015.5, cmd.run uses python_shell=False by default, which doesn't support shellisms (pipes, env variables, etc). cmd.run is currently aliased to cmd.shell to prevent breakage. Please switch to cmd.shell or set python_shell=True to avoid breakage in the future, when this aliasing is removed.

Which mentions cmd.shell. But the salt.states.cmd documentation has no mention of cmd.shell (because it's purely an alias defined in salt/utils/templates.py).

Similarly is python_shell=True is something one can set on a cmd state or it only exposed on the underlying salt.modules.cmdmod module?

If deprecation is being threatened, the preferred usage should probably be documented. Also, these changes should probably be backported to earlier documentation as well so that someone looking for examples cmd states in 2015.5 or 2015.8 has a chance of finding the non-deprecated syntax.

[jfindlay]

@notpeter, thanks for the report. When the default change to python_shell=False was made, the template layer was also modified such that cmd.run is aliased to cmd.shell until Nitrogen is released. Unless you're using shell features, you should be fine to continue to use cmd.run in jinja, mako, etc.

[notpeter]

Gotcha, so in my jinja templates I only need to switch my salt['cmd.run'] calls to salt['cmd.shell'] when those commands leverage pipes or use other shellisms and the cmd.shell state remains unchanged.

[twellspring]

Need the above clarified. Is there a cmd.shell state that is not documented or is there just a cmd.shell module and we will continue to use the cmd.run state?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

If this issue is closed prematurely, please leave a comment and we will gladly reopen the issue.