Improve command line interface

Author: xolox

README.rst

@@ -72,8 +72,7 @@ Command line program to perform common operations (in the context of packaging/d
    Alternatively the location of a remote repository can be given. The
    location should be prefixed by the type of the repository (with a ""+"" in
    between) unless the location ends in "".git"" in which case the prefix is
-   optional.
-   "
+   optional."
    "``--rev``, ``--revision=REVISION``","Select a revision to operate on. Accepts any string that's supported by the
    VCS system that manages the repository, which means you can provide branch
    names, tag names, exact revision ids, etc. This option is used in
@@ -82,55 +81,46 @@ Command line program to perform common operations (in the context of packaging/d
 
    If this option is not provided a default revision is selected: ""last:1"" for
    Bazaar repositories, ""master"" for git repositories and ""default"" (not
-   ""tip""!) for Mercurial repositories.
-   "
+   ""tip""!) for Mercurial repositories."
    ``--release=RELEASE_ID``,"Select a release to operate on. This option works in the same way as the
    ``--revision`` option. Please refer to the vcs-repo-mgr documentation for
    details on ""releases"".
 
    Although release identifiers are based on branch or tag names they
    may not correspond literally, this is why the release identifier you
    specify here is translated to a global revision id before being passed to
-   the VCS system.
-   "
+   the VCS system."
    "``-n``, ``--find-revision-number``","Print the local revision number (an integer) of the revision given with the
    ``--revision`` option. Revision numbers are useful as a build number or when a
    simple, incrementing version number is required. Revision numbers should
    not be used to unambiguously refer to a revision (use revision ids for that
    instead). This option is used in combination with the ``--repository`` and
-   ``--revision`` options.
-   "
+   ``--revision`` options."
    "``-i``, ``--find-revision-id``","Print the global revision id (a string) of the revision given with the
    ``--revision`` option. Global revision ids are useful to unambiguously refer to
    a revision. This option is used in combination with the ``--repository`` and
-   ``--revision`` options.
-   "
+   ``--revision`` options."
    ``--list-releases``,"Print the identifiers of the releases in the repository given with the
    ``--repository`` option. The release identifiers are printed on standard
-   output (one per line), ordered using natural order comparison.
-   "
+   output (one per line), ordered using natural order comparison."
    ``--select-release=RELEASE_ID``,"Print the identifier of the newest release that is not newer than
    ``RELEASE_ID`` in the repository given with the ``--repository`` option.
-   The release identifier is printed on standard output.
-   "
+   The release identifier is printed on standard output."
    "``-s``, ``--sum-revisions``","Print the summed revision numbers of multiple repository/revision pairs.
    The repository/revision pairs are taken from the positional arguments to
    vcs-repo-mgr.
 
    This is useful when you're building a package based on revisions from
    multiple VCS repositories. By taking changes in all repositories into
    account when generating version numbers you can make sure that your version
-   number is bumped with every single change.
-   "
+   number is bumped with every single change."
    ``--vcs-control-field``,"Print a line containing a Debian control file field and value. The field
    name will be one of ""Vcs-Bzr"", ""Vcs-Hg"" or ""Vcs-Git"". The value will be the
    repository's remote location and the selected revision (separated by a ""#""
-   character).
-   "
+   character)."
    "``-u``, ``--update``","Create/update the local clone of a remote repository by pulling the latest
    changes from the remote repository. This option is used in combination with
-   the ``--repository`` option.
-   "
+   the ``--repository`` option."
    "``-m``, ``--merge-up``","Merge a change into one or more release branches and the default branch.
 
    By default merging starts from the current branch. You can explicitly
@@ -144,17 +134,14 @@ Command line program to perform common operations (in the context of packaging/d
 
    If the feature branch is located in a different repository you can prefix
    the location of the repository to the name of the feature branch with a ""#""
-   token in between, to delimit the location from the branch name.
-   "
+   token in between, to delimit the location from the branch name."
    "``-e``, ``--export=DIRECTORY``","Export the contents of a specific revision of a repository to a local
    directory. This option is used in combination with the ``--repository`` and
-   ``--revision`` options.
-   "
+   ``--revision`` options."
    "``-d``, ``--find-directory``","Print the absolute pathname of a local repository. This option is used in
-   combination with the ``--repository`` option.
-   "
-   "``-v``, ``--verbose``","Make more noise.
-   "
+   combination with the ``--repository`` option."
+   "``-v``, ``--verbose``",Increase logging verbosity (can be repeated).
+   "``-q``, ``--quiet``",Decrease logging verbosity (can be repeated).
    "``-h``, ``--help``","Show this message and exit.
    "
 

requirements.txt

@@ -1,4 +1,4 @@
-coloredlogs >= 0.5
+coloredlogs >= 6.1
 executor >= 1.2
 humanfriendly >= 1.44.4
 naturalsort >= 1.3

vcs_repo_mgr/cli.py

@@ -1,7 +1,7 @@
 # Command line interface for vcs-repo-mgr.
 #
 # Author: Peter Odding <peter@peterodding.com>
-# Last Change: March 18, 2016
+# Last Change: April 29, 2017
 # URL: https://github.com/xolox/python-vcs-repo-mgr
 
 """
@@ -129,7 +129,11 @@
 
   -v, --verbose
 
-    Make more noise.
+    Increase logging verbosity (can be repeated).
+
+  -q, --quiet
+
+    Decrease logging verbosity (can be repeated).
 
   -h, --help
 
@@ -145,6 +149,7 @@
 # External dependencies.
 import coloredlogs
 from executor import execute
+from humanfriendly.terminal import usage, warning
 
 # Modules included in our package.
 from vcs_repo_mgr import coerce_repository, sum_revision_numbers
@@ -157,9 +162,7 @@
 
 
 def main():
-    """
-    The command line interface of the ``vcs-tool`` command.
-    """
+    """The command line interface of the ``vcs-tool`` program."""
     # Initialize logging to the terminal.
     coloredlogs.install()
     # Command line option defaults.
@@ -168,11 +171,11 @@ def main():
     actions = []
     # Parse the command line arguments.
     try:
-        options, arguments = getopt.gnu_getopt(sys.argv[1:], 'r:dnisume:vh', [
+        options, arguments = getopt.gnu_getopt(sys.argv[1:], 'r:dnisume:vqh', [
             'repository=', 'rev=', 'revision=', 'release=', 'find-directory',
             'find-revision-number', 'find-revision-id', 'list-releases',
             'select-release=', 'sum-revisions', 'vcs-control-field', 'update',
-            'merge-up', 'export=', 'verbose', 'help'
+            'merge-up', 'export=', 'verbose', 'quiet', 'help',
         ])
         for option, value in options:
             if option in ('-r', '--repository'):
@@ -183,6 +186,12 @@ def main():
                 revision = value.strip()
                 assert revision, "Please specify a nonempty revision string!"
             elif option == '--release':
+                # TODO Right now --release and --merge-up cannot be combined
+                #      because the following statements result in a global
+                #      revision id which is immutable. If release objects had
+                #      something like an optional `mutable_revision_id' it
+                #      should be possible to support the combination of
+                #      --release and --merge-up.
                 assert repository, "Please specify a repository first!"
                 release_id = value.strip()
                 assert release_id in repository.releases, "The given release identifier is invalid!"
@@ -228,16 +237,16 @@ def main():
                 actions.append(functools.partial(repository.export, directory, revision))
             elif option in ('-v', '--verbose'):
                 coloredlogs.increase_verbosity()
+            elif option in ('-q', '--quiet'):
+                coloredlogs.decrease_verbosity()
             elif option in ('-h', '--help'):
-                usage()
+                usage(__doc__)
                 return
         if not actions:
-            usage()
+            usage(__doc__)
             return
     except Exception as e:
-        logger.error(e)
-        print('')
-        usage()
+        warning("Error: %s", e)
         sys.exit(1)
     # Execute the requested action(s).
     try:
@@ -281,8 +290,3 @@ def print_summed_revisions(arguments):
 def print_vcs_control_field(repository, revision):
     """Report the VCS control field for the given repository and revision to standard output."""
     print("%s: %s" % repository.generate_control_field(revision))
-
-
-def usage():
-    """Report the usage message to standard output."""
-    print(__doc__.strip())