# HG changeset patch
# User osimons
# Date 1248456627 0
# Node ID d8eb5f72337190a27f381e87d523649ac856731e
# Parent  f916b88926f55a49baae77f7f04a766cb36fad4c
0.6dev: Adding documentation + minimal test for new `hg:pull` command, see #303.

diff --git a/bitten/build/tests/__init__.py b/bitten/build/tests/__init__.py
--- a/bitten/build/tests/__init__.py
+++ b/bitten/build/tests/__init__.py
@@ -10,7 +10,7 @@
 
 import unittest
 
-from bitten.build.tests import api, config, ctools, \
+from bitten.build.tests import api, config, ctools, hgtools, \
                                monotools, phptools, pythontools, \
                                xmltools
 
@@ -19,6 +19,7 @@
     suite.addTest(api.suite())
     suite.addTest(config.suite())
     suite.addTest(ctools.suite())
+    suite.addTest(hgtools.suite())
     suite.addTest(monotools.suite())
     suite.addTest(phptools.suite())
     suite.addTest(pythontools.suite())
diff --git a/bitten/build/tests/hgtools.py b/bitten/build/tests/hgtools.py
new file mode 100644
--- /dev/null
+++ b/bitten/build/tests/hgtools.py
@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2005-2007 Christopher Lenz <cmlenz@gmx.de>
+# Copyright (C) 2007 Edgewall Software
+# All rights reserved.
+#
+# This software is licensed as described in the file COPYING, which
+# you should have received as part of this distribution. The terms
+# are also available at http://bitten.edgewall.org/wiki/License.
+
+import os
+import shutil
+import tempfile
+import unittest
+import inspect
+
+from bitten.build import hgtools
+from bitten.recipe import Context
+
+
+class HgPullTestCase(unittest.TestCase):
+
+    def setUp(self):
+        self.basedir = os.path.realpath(tempfile.mkdtemp())
+        self.ctxt = Context(self.basedir)
+
+    def tearDown(self):
+        shutil.rmtree(self.basedir)
+
+    def test_command_signature(self):
+        self.assertEquals(inspect.getargspec(hgtools.pull),
+            (['ctxt', 'revision', 'dir_'], None, None, (None, '.')))
+
+def suite():
+    suite = unittest.TestSuite()
+    suite.addTest(unittest.makeSuite(HgPullTestCase, 'test'))
+    return suite
+
+if __name__ == '__main__':
+    unittest.main(defaultTest='suite')
diff --git a/doc/commands.txt b/doc/commands.txt
--- a/doc/commands.txt
+++ b/doc/commands.txt
@@ -938,3 +938,49 @@
 
 This applies the stylesheet in ``util/convert.xsl`` to the source file
 ``src.xml``, and writes the resulting XML document to ``dest.xml``.
+
+
+Mercurial Tools
+===============
+
+A collection of recipe commands for working with Mercurial_ (hg) repositories.
+
+.. _mercurial: http://mercurial.selenic.com/
+
+
+:Namespace: ``http://bitten.cmlenz.net/tools/hg``
+:Common prefix: ``hg``
+
+
+-------------
+``<hg:pull>``
+-------------
+
+Pull changesets and updates a local Mercurial repository.
+
+As the command depends on a pre-existing repository, bitten-slave must be
+started with ``--build-dir=`` option for locating and working with the
+repository.
+
+Parameters
+----------
+
++----------------+-----------------------------------------------------------+
+| Name           | Description                                               |
++================+===========================================================+
+| ``revision``   | The revision to update to (optional, defaults to tip).    |
++----------------+-----------------------------------------------------------+
+| ``dir``        | Local subdirectory with repository (optional,             |
+|                | defaults to '.').                                         |
++----------------+-----------------------------------------------------------+
+
+Paths are interpreted relative to the project source directory.
+
+Examples
+--------
+
+.. code-block:: xml
+
+  <hg:pull revision="${revision}" dir="src" />
+
+This updates the repository in ``src`` to the revision of the current build.