From 7ffa9cecaef12a17a5fc5053938a6dfbf7171c23 Mon Sep 17 00:00:00 2001
From: Michael DeHaan <michael@ansible.com>
Date: Fri, 22 Aug 2014 15:33:57 -0400
Subject: [PATCH] Docs for command warnings feature.

---
 CHANGELOG.md                        |  1 +
 docsite/rst/intro_configuration.rst | 24 ++++++++++++++++++++++++
 library/commands/command            |  4 +++-
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 244b18b80ae..764fccfc3a3 100644
--- a/CHANGELOG.md
+++ b/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:
 
diff --git a/docsite/rst/intro_configuration.rst b/docsite/rst/intro_configuration.rst
index 1500b80c5b3..b5f797fb5e3 100644
--- a/docsite/rst/intro_configuration.rst
+++ b/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
diff --git a/library/commands/command b/library/commands/command
index b94a5233895..8071adbc493 100644
--- a/library/commands/command
+++ b/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"