Repository: ansible/ansible

Issue:
Wording of hg module documentation misleading
##### ISSUE TYPE

Documentation Report

##### COMPONENT NAME

hg module

##### ANSIBLE VERSION

ansible 2.0.0

##### CONFIGURATION

Not relevant for the ticket.

##### OS / ENVIRONMENT

Ubuntu 14.04 fully updated.

##### SUMMARY

The current documentation for the `hg` module in its synopsis states:

> Manages Mercurial (hg) repositories. Supports SSH, HTTP/S and local address.

I was led to use this module because I saw the following warning in my registered result:

```
"warnings": ["Consider using hg module rather than running hg"]
```

This seems to suggest that I should be able to **push** to a remote repository. However, the documentation only mentions cloning, not pushing or pulling.

##### STEPS TO REPRODUCE

Using the following playbook

```

---
- name: Update repos
  hosts: lxchost
  sudo: True
  connection: local
  gather_facts: False
  tasks:
    - name: Push
      hg: repo="/root/repo" dest="ssh://{{item}}/repo"
      with_items: "{{groups['enabled']}}"
```

and existing repositories on the hosts in group `enabled`, run the playbook.

##### EXPECTED RESULTS

I expected it to push the changes. After all the warning pointed me to the `hg` module as a response to my attempt to push to the hosts using the `command` module.

##### ACTUAL RESULTS

```
TASK: [Push] *******************************************
failed: [lxchost] => (item=machine1) => {"failed": true, "item": "machine1", "playbook": "playbooks/push.yml", "role": null, "task": "Push"}
msg: abort: repository .dotfiles already exists!
abort: could not create remote repo!

failed: [lxchost] => (item=machine2) => {"failed": true, "item": "machine2", "playbook": "playbooks/push.yml", "role": null, "task": "Push"}
msg: abort: repository .dotfiles already exists!
abort: could not create remote repo!
```

Ansible fails, telling me that the remote repo exists. Right, so how do I push changes rather than clone a fresh copy?

PS: accidentally [opened in the ansible repo](https://github.com/ansible/ansible/issues/11824) before.


Copied from original issue: ansible/ansible-modules-core#1851




Discussion:
From @ansibot on 2015-08-01T11:06:19Z

<!-- @assarbad: Thanks for filing this documentation report! -->

@yeukhon ping, this issue is waiting for your response.
[click here for bot help](https://github.com/jctanner/ansibullbot/blob/ISSUE_TRIAGE_CLASS/ISSUE_HELP.md)

<!--- boilerplate: issue_bug_new --->

From @yeukhon on 2015-08-01T11:06:19Z

This is a very old issue. I have to double check the current implementation, but when we first wrote the module, pushing to remote wasn't in our mind.

From @assarbad on 2015-08-01T11:06:19Z

@yeukhon wouldn't it make sense to silence the warning then? Or provide an option to do so? In my projects I tend to take heed of warnings and act accordingly. But here the warning tells me a module which evidently has no support for the action I'm attempting. And I think it's a rather common action to perform with Mercurial repos ;)

@ansibot Greetings! Thanks for taking the time to open this issue. In order for the community to handle your issue effectively, we need a bit more information. 

Here are the items we could not find in your description:
- component name

Please set the description of this issue with this template:
https://raw.githubusercontent.com/ansible/ansible/devel/.github/ISSUE_TEMPLATE.md

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: issue_missing_data --->
@ansibot  will finish this by/before Friday.
@ansibot  sorry for the delay, should have done this on Friday.

> when we first wrote the module, pushing to remote wasn't in our mind.

Correct. Ansible's ``hg`` module was rewrote to mimic the ``git`` module. I still don't think our ``git`` module can push to remote. I am opened to modify the ``hg`` module so it can support push. I see that benefit, since some users use Ansible in CI/CD workflow. I opened #31156 for this.

> @yeukhon wouldn't it make sense to silence the warning then?

This is not a warning written in the ``hg`` module code as I discovered. I am okay removing ``hg`` from the list.

> But here the warning tells me a module which evidently has no support for the action I'm attempting.

I will have to investigate how we handle ``action not available`` in the modern days of Ansible... will get back to this soon.



Never mind, for the last command, hg module is up to standard. @ansibot  please let me know if you disagree.

```
***********************************
PARSED OUTPUT
{
    "failed": true,
    "invocation": {
        "module_args": {
            "blah": "1",
            "dest": "/tmp/cs-review",
            "repo": "https://bitbucket.org/yeukhon/hello"
        }
    },
    "msg": "Unsupported parameters for (basic.py) module: blah Supported parameters include: clone,dest,executable,force,purge,repo,revision,update"
}

```

vs

```
PARSED OUTPUT
{
    "failed": true,
    "invocation": {
        "module_args": {
            "git": {
                "blah": "1",
                "dest": "/tmp/cs-review",
                "repo": "https://github.com/yeukhon/cs-review"
            }
        }
    },
    "msg": "Unsupported parameters for (basic.py) module: git Supported parameters include: accept_hostkey,archive,bare,clone,depth,dest,executable,force,key_file,recursive,reference,refspec,remote,repo,ssh_opts,track_submodules,umask,update,verify_commit,version"
}
```

Resolving patch:
diff --git a/lib/ansible/modules/commands/command.py b/lib/ansible/modules/commands/command.py
--- a/lib/ansible/modules/commands/command.py
+++ b/lib/ansible/modules/commands/command.py
@@ -124,7 +124,7 @@ def check_command(module, commandline):
     arguments = {'chown': 'owner', 'chmod': 'mode', 'chgrp': 'group',
                  'ln': 'state=link', 'mkdir': 'state=directory',
                  'rmdir': 'state=absent', 'rm': 'state=absent', 'touch': 'state=touch'}
-    commands = {'hg': 'hg', 'curl': 'get_url or uri', 'wget': 'get_url or uri',
+    commands = {'curl': 'get_url or uri', 'wget': 'get_url or uri',
                 'svn': 'subversion', 'service': 'service',
                 'mount': 'mount', 'rpm': 'yum, dnf or zypper', 'yum': 'yum', 'apt-get': 'apt',
                 'tar': 'unarchive', 'unzip': 'unarchive', 'sed': 'template or lineinfile',
diff --git a/lib/ansible/modules/source_control/hg.py b/lib/ansible/modules/source_control/hg.py
--- a/lib/ansible/modules/source_control/hg.py
+++ b/lib/ansible/modules/source_control/hg.py
@@ -78,6 +78,7 @@
             - Path to hg executable to use. If not supplied,
               the normal mechanism for resolving binary paths will be used.
 notes:
+    - "This module does not support push capability. See U(https://github.com/ansible/ansible/issues/31156)."
     - "If the task seems to be hanging, first verify remote host is in C(known_hosts).
       SSH will prompt user to authorize the first contact with a remote host.  To avoid this prompt,
       one solution is to add the remote host public key in C(/etc/ssh/ssh_known_hosts) before calling


Test patch: