Docs for command warnings feature.

CHANGELOG.md

@@ -13,6 +13,7 @@ New core features:
 * 'ansible vault view filename.yml' opens filename.yml decrypted in a pager.
 * no_log parameter now surpressess data from callbacks/output as well as syslog
 * ansible-galaxy install -f requirements.yml allows advanced options and installs from non-galaxy SCM sources and tarballs.
+* command_warnings feature will warn about when usage of the shell/command module can be simplified to use core modules - this can be disabled in ansible.cfg
 
 New Modules:
 

docsite/rst/intro_configuration.rst

@@ -127,6 +127,30 @@ different locations::
 
 Most users will not need to use this feature.  See :doc:`developing_plugins` for more details
 
+.. _command_warnings:
+
+command_warnings
+================
+
+.. versionadded:: 1.8
+
+By default since Ansible 1.8, Ansible will warn when usage of the shell and
+command module appear to be simplified by using a default Ansible module
+instead.  This can include reminders to use the 'git' module instead of
+shell commands to execute 'git'.  Using modules when possible over arbitrary
+shell commands can lead to more reliable and consistent playbook runs, and
+also easier to maintain playbooks.
+
+    command_warnings=False
+
+These warnings can be silenced by adjusting the following
+setting or adding warn=yes or warn=no to the end of the command line
+parameter string, like so::
+
+
+    - name: usage of git that could be replaced with the git module
+      shell: git update foo warn=yes
+
 .. _connection_plugins:
 
 connection_plugins

library/commands/command

@@ -68,8 +68,10 @@ options:
     default: null
     version_added: "0.9"
   warn:
+    version_added: "1.8"
+    default: yes
     description:
-      - turn off warnings about running a command that is provided by an Ansible module.
+      - "turn off warnings about running a command that is provided by an Ansible module, suggesting you should use that module instead. 'Command warnings' can also be turned off globally in ansible.cfg"
     required: false
     default: True
     version_added: "1.5"