Updates to Ansible command options

* Moved the --list-hosts option that is common to both `ansible` and
  `ansible-playbook` into utils/__init__.py (corrects a FIXME)
* Wrote new help text for the --list-hosts option that makes sense
  for both of the commands that it applies to
* Changed the usage argument in `ansible-playbook` so that it is
  setup in the base_parser method the same way that it is in
  the `ansible` executable
* Updated the help text for several options to correct typos,
  clarify meaning, improve readability, or fix grammatical errors.
  In the case of `ansible-pull`, I changed the help text so that
  it adheres to the same standards as the other executables.

bin/ansible

@@ -60,8 +60,6 @@ class Cli(object):
         parser.add_option('-m', '--module-name', dest='module_name',
             help="module name to execute (default=%s)" % C.DEFAULT_MODULE_NAME,
             default=C.DEFAULT_MODULE_NAME)
-        parser.add_option('--list-hosts', dest='listhosts', action='store_true',
-            help="dump out a list of hosts matching input pattern, does not execute any modules!")
 
         options, args = parser.parse_args()
         self.callbacks.options = options

bin/ansible-playbook

@@ -52,10 +52,9 @@ def main(args):
     ''' run ansible-playbook operations '''
 
     # create parser for CLI options
-    usage = "%prog playbook.yml"
     parser = utils.base_parser(
         constants=C, 
-        usage=usage, 
+        usage = "%prog playbook.yml",
         connect_opts=True, 
         runas_opts=True, 
         subset_opts=True, 
@@ -66,17 +65,14 @@ def main(args):
         help="set additional key=value variables from the CLI")
     parser.add_option('-t', '--tags', dest='tags', default='all',
         help="only run plays and tasks tagged with these values")
-    # FIXME: list hosts is a common option and can be moved to utils/__init__.py
-    parser.add_option('--list-hosts', dest='listhosts', action='store_true',
-        help="dump out a list of hosts, each play will run against, does not run playbook!")
     parser.add_option('--syntax-check', dest='syntax', action='store_true',
-        help="do a playbook syntax check on the playbook, do not execute the playbook")
+        help="perform a syntax check on the playbook, but do not execute it")
     parser.add_option('--list-tasks', dest='listtasks', action='store_true',
-        help="do list all tasks that would be executed")
+        help="list all tasks that would be executed")
     parser.add_option('--step', dest='step', action='store_true',
         help="one-step-at-a-time: confirm each task before running")
     parser.add_option('--start-at-task', dest='start_at', 
-        help="start the playbook with a task matching this name")
+        help="start the playbook at the task matching this name")
 
     options, args = parser.parse_args(args)
 

bin/ansible-pull

@@ -94,16 +94,16 @@ def main(args):
     usage = "%prog [options] [playbook.yml]"
     parser = OptionParser(usage=usage)
     parser.add_option('--purge', default=False, action='store_true',
-                      help='Purge git checkout after playbook run')
+                      help='purge git checkout after playbook run')
     parser.add_option('-d', '--directory', dest='dest', default=None,
-                      help='Directory to clone git repository to')
+                      help='directory to clone the git repository to')
     parser.add_option('-U', '--url', dest='url', default=None,
-                      help='URL of git repository')
+                      help='URL of the git repository')
     parser.add_option('-C', '--checkout', dest='checkout',
                       default="HEAD",
-                      help='Branch/Tag/Commit to checkout.  Defaults to HEAD.')
+                      help='branch/tag/commit to checkout; defaults to HEAD')
     parser.add_option('-i', '--inventory-file', dest='inventory',
-                      help="specify inventory host file")
+                      help="location of the inventory host file")
     options, args = parser.parse_args(args)
 
     if not options.dest:

lib/ansible/utils/__init__.py

@@ -469,6 +469,8 @@ def base_parser(constants=C, usage="", output_opts=False, runas_opts=False,
         help='use this file to authenticate the connection')
     parser.add_option('-K', '--ask-sudo-pass', default=False, dest='ask_sudo_pass', action='store_true',
         help='ask for sudo password')
+    parser.add_option('--list-hosts', dest='listhosts', action='store_true',
+        help='outputs a list of matching hosts; does not execute anything else')
     parser.add_option('-M', '--module-path', dest='module_path',
         help="specify path(s) to module library (default=%s)" % constants.DEFAULT_MODULE_PATH,
         default=None)
@@ -510,12 +512,12 @@ def base_parser(constants=C, usage="", output_opts=False, runas_opts=False,
 
     if check_opts:
         parser.add_option("-C", "--check", default=False, dest='check', action='store_true',
-            help="don't make any changes, instead try to predict some of the changes that may occur"
+            help="don't make any changes; instead, try to predict some of the changes that may occur"
         )
 
     if diff_opts:
         parser.add_option("-D", "--diff", default=False, dest='diff', action='store_true',
-            help="when changing (small) files and templates, show the differences in those files, works great with --check"
+            help="when changing (small) files and templates, show the differences in those files; works great with --check"
         )