Make it possible to add new files to repositories

vcs_repo_mgr/__init__.py

@@ -104,7 +104,7 @@
 )
 
 # Semi-standard module versioning.
-__version__ = '0.27.2'
+__version__ = '0.28'
 
 USER_CONFIG_FILE = os.path.expanduser('~/.vcs-repo-mgr.ini')
 """The absolute pathname of the user-specific configuration file (a string)."""
@@ -872,6 +872,39 @@ def merge(self, revision=None):
             **self.get_author()
         ))
 
+    def add_files(self, *pathnames, **kw):
+        """
+        Stage new files in the working tree to be included in the next commit.
+
+        :param pathnames: Any positional arguments are expected to be pathnames
+                          relative to the root of the repository.
+        :param all: If the keyword argument `all` is :data:`True` then all
+                    new files are added to the repository (in this case no
+                    pathnames should be given).
+        :raises: :exc:`~exceptions.ValueError` when pathnames are given and the
+                 keyword argument `all` is also :data:`True`.
+
+        .. note:: Automatically creates the local repository on the first run.
+        """
+        self.create()
+        add_all = kw.get('all', False)
+        logger.info("Staging working tree changes to be committed in %s ..", self.local)
+        if pathnames and add_all:
+            raise ValueError("You can't add specific pathnames using all=True!")
+        if add_all:
+            execute(self.get_command(
+                method_name='add_files',
+                attribute_name='add_command_all',
+                local=self.local,
+            ))
+        else:
+            execute(self.get_command(
+                method_name='add_files',
+                attribute_name='add_command',
+                local=self.local,
+                filenames=pathnames,
+            ))
+
     def commit(self, message, author=None):
         """
         Commit changes to tracked files in the working tree.
@@ -1403,6 +1436,8 @@ class HgRepo(Repository):
         hg -R {local} commit --user={author_combined} --message={message} --close-branch
     ''')
     merge_command = 'hg -R {local} merge --rev={revision}'
+    add_command = 'hg --cwd {local} addremove {filenames}'
+    add_command_all = 'hg --cwd {local} addremove'
     # The `hg remove --after' command is used to match the semantics of `git
     # commit --all' however `hg remove --after' is _very_ verbose (it comments
     # on every existing file in the repository) and unfortunately it ignores
@@ -1563,6 +1598,8 @@ class GitRepo(Repository):
             -c user.email={author_email}
             merge --no-commit --no-ff {revision}
     ''')
+    add_command = 'cd {local} && git add -- {filenames}'
+    add_command_all = 'cd {local} && git add --all .'
     commit_command = compact('''
         cd {local} && git
             -c user.name={author_name}

vcs_repo_mgr/tests.py

@@ -1,9 +1,11 @@
-"""Automated tests for the `vcs-repo-mgr` package."""
-
+# Version control system repository manager.
+#
 # Author: Peter Odding <peter@peterodding.com>
-# Last Change: March 16, 2016
+# Last Change: March 18, 2016
 # URL: https://github.com/xolox/python-vcs-repo-mgr
 
+"""Automated tests for the `vcs-repo-mgr` package."""
+
 # Standard library modules.
 import hashlib
 import logging
@@ -362,14 +364,19 @@ def check_checkout_support(self, repository):
                 repository.checkout(revision=tag)
 
     def check_commit_support(self, repository):
-        """Make sure we can make new commits."""
-        logger.info("Testing commit() support ..")
+        """Make sure we can add files and make new commits."""
+        logger.info("Testing add_files() and commit() support ..")
         try:
             # Make sure we start with a clean working tree.
             repository.checkout(clean=True)
-            # Mutate a tracked file in the repository's working tree.
-            self.mutate_working_tree(repository)
-            # Make sure the working tree is no longer clean.
+            # Pick a random filename to add to the repository.
+            file_to_add = random_string()
+            # Create the new file.
+            with open(os.path.join(repository.local, file_to_add), 'w') as handle:
+                handle.write("Testing, 1, 2, 3 ..\n")
+            # Stage the addition of the new file.
+            repository.add_files(file_to_add)
+            # Make sure the working tree is dirty now.
             assert not repository.is_clean
             # Commit the change we made and ensure that commit() actually
             # creates a new revision in the relevant branch.