Changes is now determined by simply comparing before,after and cleaned (purge and/or force). Doc is updated.

hg

@@ -4,7 +4,8 @@
 # (c) 2013, Yeukhon Wong <yeukhon@acm.org>
 #
 # This module was originally inspired by Brad Olson's ansible-module-mercurial
-# <https://github.com/bradobro/ansible-module-mercurial>.
+# <https://github.com/bradobro/ansible-module-mercurial>. This module tends
+# to follow the git module implementation.
 #
 # This file is part of Ansible
 #
@@ -47,25 +48,33 @@ options:
         default: null
     revision:
         description:
-            - Equivalent C(-r) option in hg command, which can either be a changeset number or a branch
+            - Equivalent C(-r) option in hg command which could be the changeset, revision number,
-              name.
+              branch name or even tag. 
         required: false
         default: "default"
     force:
         description:
-    	    - Discards uncommited changes. Runs C(hg update -c).
+            - Discards uncommited changes. Runs C(hg update -C).
         required: false
         default: "yes"
-        choices: [ "yes", "no" ]
+        choices: [ yes, no ]
-
+    purge:
-
+        description:
-
+            - Delets untracked files. Runs C(hg purge). Note this requires C(purge) extension to
+              be enabled if C(purge=yes). This module will modify hgrc file on behalf of the user
+              and undo the changes before exiting the task.
+        required: false
+        default: "no"
+        choices: [ yes, no ]
 notes:
     - 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. One solution is to add
       C(StrictHostKeyChecking no) in C(.ssh/config) which will accept and authorize the connection
       on behalf of the user. However, if you run as a different user such as setting sudo to True),
       for example, root will not look at the user .ssh/config setting.
+examples:
+    - code: "hg: repo=https://bitbucket.org/user/repo1 dest=/home/user/repo1 revision=stable purge=yes"
+      description: Ensure the current working copy is inside the stable branch and deletes untracked files if any.
 
 requirements: [ ]
 '''
@@ -102,38 +111,8 @@ def _hg_command(module, args_list):
     (rc, out, err) = module.run_command(['hg'] + args_list)
     return (rc, out, err)
 
-def determine_changed(module, before, after, expecting):
+def _hg_list_untracked(module, dest):
-    """
+    return _hg_command(module, ['purge', '-R', dest, '--print'])
-    This compares the user supplied revision to the before
-    and after revision (actually, id).
-    
-    get_revision calls hg id -b -i -t which returns the string
-    "<changeset>[+] <branch_name> <tag>" and  we compare if
-    expected revision (which could be changeset, 
-    branch name) is part of the result string from hg id.
-    """
-
-    # some custom error messages
-    err1 = "no changes found. You supplied %s but repo is \
-currently at %s" %(expecting, after)
-
-    err2 = "Unknown error. The state before operation was %s,\
-after the operation was %s, but we were expecting \
-%s as part of the state." %(before, after, expecting)
-
-    # if before and after are equal, only two possible explainations
-    # case one: when current working copy is already what user want
-    # case two: when current working copy is ahead of what user want
-    # in case two, hg will exist successfully although that contradict
-    # user assumption. Therefore, alert the user by failing the task.
-    if before == after and expecting in after:
-        module.exit_json(changed=False, before=before, after=after)
-    elif before == after and not expecting in after: # this is case two
-        module.fail_json(msg=err2) 
-    elif before != after and expecting in after: # updated to expecting
-        module.exit_json(changed=True, before=before, after=after)
-    else:
-        module.fail_json(msg=err2)
 
 def get_revision(module, dest):
     """
@@ -152,27 +131,58 @@ def get_revision(module, dest):
         return out.strip('\n')
 
 def has_local_mods(module, dest):
-    out = get_revision(module, dest)
+    now = get_revision(module, dest)
-    if '+' in out:
+    if '+' in now:
         return True
     else:
         return False
 
-def hg_discard(module, dest, force):
+def hg_discard(module, dest):
-    if not force and has_local_mods(module, dest):
+    before = has_local_mods(module, dest)
-        module.fail_json(msg="Respository has uncommited changes.")
+    if not before:
-    return _hg_command(module, ['update', '-C', '-R', dest])
+        return False
 
+    (rc, out, err) = _hg_command(module, ['update', '-C', '-R', dest])
+    if rc != 0:
+        module.fail_json(msg=err)
+
+    after = has_local_mods(module, dest)
+    if before != after and not after:   # no more local modification
+        return True
+            
 def hg_purge(module, dest):
     hgrc = os.path.join(dest, '.hg/hgrc')
     purge_option = [('extensions', 'purge', '')]
-    _set_hgrc(hgrc, purge_option)   # hg purge requires purge extension
+    _set_hgrc(hgrc, purge_option)   # enable purge extension
     
-    (rc, out, err) = _hg_command(module, ['purge', '-R', dest])
+    # before purge, find out if there are any untracked files
-    if rc == 0:
+    (rc1, out1, err1) = _hg_list_untracked(module, dest)
-        _undo_hgrc(hgrc, purge_option)
+    if rc1 != 0:
-    else:
         module.fail_json(msg=err)
+    
+    # there are some untrackd files
+    if out1 != '':
+        (rc2, out2, err2) = _hg_command(module, ['purge', '-R', dest])
+        if rc2 == 0:
+            _undo_hgrc(hgrc, purge_option)
+        else:
+            module.fail_json(msg=err)
+        return True
+    else:
+        return False
+
+def hg_cleanup(module, dest, force, purge):
+    discarded = False
+    purged = False
+
+    if force:
+        discarded = hg_discard(module, dest)
+    if purge:
+        purged = hg_purge(module, dest)
+    if discarded or purged:
+        return True
+    else:
+        return False
 
 def hg_pull(module, dest, revision):
     return _hg_command(module, ['pull', '-r', revision, '-R', dest])
@@ -183,6 +193,11 @@ def hg_update(module, dest, revision):
 def hg_clone(module, repo, dest, revision):
     return _hg_command(module, ['clone', repo, dest, '-r', revision])
 
+def switch_version(module, dest, revision):
+    return _hg_command(module, ['update', '-r', revision, '-R', dest])
+
+# ===========================================
+
 def main():
     module = AnsibleModule(
         argument_spec = dict(
@@ -199,28 +214,24 @@ def main():
     force = module.boolean(module.params['force'])
     purge = module.boolean(module.params['purge'])
     hgrc = os.path.join(dest, '.hg/hgrc')
-    
+   
+    # initial states
+    before = ''
+    changed = False
+    cleaned = False
+
     # If there is no hgrc file, then assume repo is absent
     # and perform clone. Otherwise, perform pull and update.
     if not os.path.exists(hgrc):
-        before = ''
         (rc, out, err) = hg_clone(module, repo, dest, revision)
         if rc != 0:
             module.fail_json(msg=err)
-        after = get_revision(module, dest)
-        determine_changed(module, before, after, revision)
     else:
         # get the current state before doing pulling
         before = get_revision(module, dest)
 
-        # calls hg update -C and abort when uncommited changes
+        # can perform force and purge
-        # are present if force=no
+        cleaned = hg_cleanup(module, dest, force, purge)
-        (rc, out, err) = hg_discard(module, dest, force)
-        if rc != 0:
-            module.fail_json(msg=err)
-        
-        if purge:
-            hg_purge(module, dest)
 
         (rc, out, err) = hg_pull(module, dest, revision)
         if rc != 0:
@@ -230,8 +241,11 @@ def main():
         if rc != 0:
             module.fail_json(msg=err)
 
-        after = get_revision(module, dest)
+    switch_version(module, dest, revision)
-        determine_changed(module, before, after, revision)
+    after = get_revision(module, dest)
+    if before != after or cleaned:
+        changed = True
+    module.exit_json(before=before, after=after, changed=changed, cleaned=cleaned)
 
 # include magic from lib/ansible/module_common.py
 #<<INCLUDE_ANSIBLE_MODULE_COMMON>>