Enable check_mode in command module (#40428)

* Enable check_mode in command module

This only works if supplying creates or removes since it needs
something to base the heuristic off. If none are supplied it will just
skip as usual.
Fixes #15828

* Add documentation for new check_mode behavior

changelogs/fragments/command_shell_check_mode.yaml

@@ -0,0 +1,6 @@
+---
+minor_changes:
+  - command module - Add support for check mode when passing creates or removes arguments.
+    (https://github.com/ansible/ansible/pull/40428)
+  - shell module - Add support for check mode when passing creates or removes arguments.
+    (https://github.com/ansible/ansible/pull/40428)

docs/docsite/rst/porting_guides/porting_guide_2.7.rst

@@ -100,7 +100,9 @@ The following modules will be removed in Ansible 2.10. Please update your playbo
 Noteworthy module changes
 -------------------------
 
-No notable changes.
+Check mode is now supported in the ``command`` and ``shell`` modules. However, only when ``creates`` or ``removes`` is
+specified. If either of these are specified, the module will check for existence of the file and report the correct
+changed status, if they are not included the module will skip like it had done previously.
 
 Plugins
 =======

lib/ansible/modules/commands/command.py

@@ -64,6 +64,8 @@ notes:
        use the C(command) module when possible.
     -  " C(creates), C(removes), and C(chdir) can be specified after the command.
        For instance, if you only want to run a command if a certain file does not exist, use this."
+    -  Check mode is supported when passing C(creates) or C(removes). If running in check mode and either of these are specified, the module will
+       check for the existence of the file and report the correct changed status. If these are not supplied, the task will be skipped.
     -  The C(executable) parameter is removed since version 2.4. If you have a need for this parameter, use the M(shell) module instead.
     -  For Windows targets, use the M(win_command) module instead.
 author:
@@ -185,7 +187,8 @@ def main():
             # The default for this really comes from the action plugin
             warn=dict(type='bool', default=True),
             stdin=dict(required=False),
-        )
+        ),
+        supports_check_mode=True,
     )
     shell = module.params['_uses_shell']
     chdir = module.params['chdir']
@@ -245,7 +248,13 @@ def main():
 
     startd = datetime.datetime.now()
 
-    rc, out, err = module.run_command(args, executable=executable, use_unsafe_shell=shell, encoding=None, data=stdin)
+    if not module.check_mode:
+        rc, out, err = module.run_command(args, executable=executable, use_unsafe_shell=shell, encoding=None, data=stdin)
+    elif creates or removes:
+        rc = 0
+        out = err = b'Command would have run if not in check mode'
+    else:
+        module.exit_json(msg="skipped, running in check mode", skipped=True)
 
     endd = datetime.datetime.now()
     delta = endd - startd

lib/ansible/modules/commands/shell.py

@@ -61,6 +61,10 @@ notes:
      playbooks will follow the trend of using M(command) unless the C(shell)
      module is explicitly required. When running ad-hoc commands, use your best
      judgement.
+  -  Check mode is supported when passing C(creates) or C(removes). If running
+     in check mode and either of these are specified, the module will check for
+     the existence of the file and report the correct changed status. If these
+     are not supplied, the task will be skipped.
   -  To sanitize any variables passed to the shell module, you should use
      "{{ var | quote }}" instead of just "{{ var }}" to make sure they don't include evil things like semicolons.
   - For Windows targets, use the M(win_shell) module instead.