Improve description layout. Improve coloring and add legend in help.

git_cl.py

 #!/usr/bin/env python
 # Copyright (c) 2012 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
 # Copyright (C) 2008 Evan Martin <martine@danga.com>
 
 """A git-command for integrating reviews on Rietveld."""
 
 import difflib
@@ skipping 1015 matching lines @@
       urlretrieve(src, dst)
       os.chmod(dst, stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR)
     except Exception:
       if os.path.exists(dst):
         os.remove(dst)
       DieWithError('\nFailed to download hooks from %s' % src)
 
 
 @usage('[repo root containing codereview.settings]')
 def CMDconfig(parser, args):
-  """edit configuration for this tree"""
+  """Edits configuration for this tree."""
 
   _, args = parser.parse_args(args)
   if len(args) == 0:
     GetCodereviewSettingsInteractively()
     DownloadHooks(True)
     return 0
 
   url = args[0]
   if not url.endswith('codereview.settings'):
     url = os.path.join(url, 'codereview.settings')
 
   # Load code review settings and download hooks (if available).
   LoadCodereviewSettingsFromFile(urllib2.urlopen(url))
   DownloadHooks(True)
   return 0
 
 
 def CMDbaseurl(parser, args):
-  """get or set base-url for this branch"""
+  """Gets or sets base-url for this branch."""
   branchref = RunGit(['symbolic-ref', 'HEAD']).strip()
   branch = ShortBranchName(branchref)
   _, args = parser.parse_args(args)
   if not args:
     print("Current base-url:")
     return RunGit(['config', 'branch.%s.base-url' % branch],
                   error_ok=False).strip()
   else:
     print("Setting base-url to %s" % args[0])
     return RunGit(['config', 'branch.%s.base-url' % branch, args[0]],
                   error_ok=False).strip()
 
 
 def CMDstatus(parser, args):
-  """show status of changelists"""
+  """Show status of changelists.
+
+  Colors are used to tell the state of the CL unless --fast is used:
+    - Green   LGTM'ed
+    - Blue    waiting for review
+    - Yellow  waiting for you to reply to review
+    - Red     not sent for review or broken
+    - Cyan    was committed, branch can be deleted
+
+  Also see 'git cl comments'.
+  """
   parser.add_option('--field',
                     help='print only specific field (desc|id|patch|url)')
   parser.add_option('-f', '--fast', action='store_true',
                     help='Do not retrieve review status')
   (options, args) = parser.parse_args(args)
 
   if options.field:
     cl = Changelist()
     if options.field.startswith('desc'):
       print cl.GetDescription()
@@ skipping 21 matching lines @@
   alignment = max(5, max(len(b) for b in branches))
   print 'Branches associated with reviews:'
   # Adhoc thread pool to request data concurrently.
   output = Queue.Queue()
 
   # Silence upload.py otherwise it becomes unweldly.
   upload.verbosity = 0
 
   if not options.fast:
     def fetch(b):
+      """Fetches information for an issue and returns (branch, issue, color)."""
       c = Changelist(branchref=b)
       i = c.GetIssueURL()
-      try:
-        props = c.GetIssueProperties()
-        r = c.GetApprovingReviewers() if i else None
-        if not props.get('messages'):
-          r = None
-      except urllib2.HTTPError:
-        # The issue probably doesn't exist anymore.
-        i += ' (broken)'
-        r = None
-      output.put((b, i, r))
+      props = {}
+      r = None
+      if i:
+        try:
+          props = c.GetIssueProperties()
+          r = c.GetApprovingReviewers() if i else None
+        except urllib2.HTTPError:
+          # The issue probably doesn't exist anymore.
+          i += ' (broken)'
+
+      msgs = props.get('messages') or []
+
+      if not i:
+        color = Fore.WHITE
+      elif props.get('closed'):
+        # Issue is closed.
+        color = Fore.CYAN
+      elif r:
+        # Was LGTM'ed.
+        color = Fore.GREEN
+      elif not msgs:
+        # No message was sent.
+        color = Fore.RED
+      elif msgs[-1]['sender'] != props.get('owner_email'):
+        color = Fore.YELLOW
+      else:
+        color = Fore.BLUE
+      output.put((b, i, color))
 
     threads = [threading.Thread(target=fetch, args=(b,)) for b in branches]
     for t in threads:
       t.daemon = True
       t.start()
   else:
     # Do not use GetApprovingReviewers(), since it requires an HTTP request.
     for b in branches:
       c = Changelist(branchref=b)
-      output.put((b, c.GetIssue(), None))
+      url = c.GetIssueURL()
+      output.put((b, url, Fore.BLUE if url else Fore.WHITE))
 
   tmp = {}
   alignment = max(5, max(len(ShortBranchName(b)) for b in branches))
   for branch in sorted(branches):
     while branch not in tmp:
-      b, i, r = output.get()
-      tmp[b] = (i, r)
-    issue, reviewers = tmp.pop(branch)
-    if not issue:
-      color = Fore.WHITE
-    elif reviewers:
-      # Was approved.
-      color = Fore.GREEN
-    elif reviewers is None:
-      # No message was sent.
-      color = Fore.RED
-    else:
-      color = Fore.BLUE
+      b, i, color = output.get()
+      tmp[b] = (i, color)
+    issue, color = tmp.pop(branch)
     print '  %*s: %s%s%s' % (
           alignment, ShortBranchName(branch), color, issue, Fore.RESET)
 
   cl = Changelist()
   print
   print 'Current branch:',
   if not cl.GetIssue():
     print 'no issue assigned.'
     return 0
   print cl.GetBranch()
   print 'Issue number: %s (%s)' % (cl.GetIssue(), cl.GetIssueURL())
   print 'Issue description:'
   print cl.GetDescription(pretty=True)
   return 0
 
 
 @usage('[issue_number]')
 def CMDissue(parser, args):
-  """Set or display the current code review issue number.
+  """Sets or displays the current code review issue number.
 
   Pass issue number 0 to clear the current issue.
-"""
+  """
   _, args = parser.parse_args(args)
 
   cl = Changelist()
   if len(args) > 0:
     try:
       issue = int(args[0])
     except ValueError:
       DieWithError('Pass a number to set the issue or none to list it.\n'
           'Maybe you want to run git cl status?')
     cl.SetIssue(issue)
   print 'Issue number: %s (%s)' % (cl.GetIssue(), cl.GetIssueURL())
   return 0
 
 
 def CMDcomments(parser, args):
-  """show review comments of the current changelist"""
+  """Shows review comments of the current changelist."""
   (_, args) = parser.parse_args(args)
   if args:
     parser.error('Unsupported argument: %s' % args)
 
   cl = Changelist()
   if cl.GetIssue():
     data = cl.GetIssueProperties()
     for message in sorted(data['messages'], key=lambda x: x['date']):
       if message['disapproval']:
         color = Fore.RED
       elif message['approval']:
         color = Fore.GREEN
       elif message['sender'] == data['owner_email']:
         color = Fore.MAGENTA
       else:
         color = Fore.BLUE
       print '\n%s%s  %s%s' % (
           color, message['date'].split('.', 1)[0], message['sender'],
           Fore.RESET)
       if message['text'].strip():
         print '\n'.join('  ' + l for l in message['text'].splitlines())
   return 0
 
 
 def CMDdescription(parser, args):
-  """brings up the editor for the current CL's description."""
+  """Brings up the editor for the current CL's description."""
   cl = Changelist()
   if not cl.GetIssue():
     DieWithError('This branch has no associated changelist.')
   description = ChangeDescription(cl.GetDescription())
   description.prompt()
   cl.UpdateDescription(description.description)
   return 0
 
 
 def CreateDescriptionFromLog(args):
   """Pulls out the commit log to use as a base for the CL description."""
   log_args = []
   if len(args) == 1 and not args[0].endswith('.'):
     log_args = [args[0] + '..']
   elif len(args) == 1 and args[0].endswith('...'):
     log_args = [args[0][:-1]]
   elif len(args) == 2:
     log_args = [args[0] + '..' + args[1]]
   else:
     log_args = args[:]  # Hope for the best!
   return RunGit(['log', '--pretty=format:%s\n\n%b'] + log_args)
 
 
 def CMDpresubmit(parser, args):
-  """run presubmit tests on the current changelist"""
+  """Runs presubmit tests on the current changelist."""
   parser.add_option('-u', '--upload', action='store_true',
                     help='Run upload hook instead of the push/dcommit hook')
   parser.add_option('-f', '--force', action='store_true',
                     help='Run checks even if tree is dirty')
   (options, args) = parser.parse_args(args)
 
   if not options.force and is_dirty_git_tree('presubmit'):
     print 'use --force to check even if tree is dirty.'
     return 1
 
@@ skipping 166 matching lines @@
   So that "--reviewers joe@c,john@c --reviewers joa@c" results in
   options.reviewers == sorted(['joe@c', 'john@c', 'joa@c']).
   """
   items = sum((i.split(',') for i in l), [])
   stripped_items = (i.strip() for i in items)
   return sorted(filter(None, stripped_items))
 
 
 @usage('[args to "git diff"]')
 def CMDupload(parser, args):
-  """upload the current changelist to codereview"""
+  """Uploads the current changelist to codereview."""
   parser.add_option('--bypass-hooks', action='store_true', dest='bypass_hooks',
                     help='bypass upload presubmit hook')
   parser.add_option('--bypass-watchlists', action='store_true',
                     dest='bypass_watchlists',
                     help='bypass watchlists auto CC-ing reviewers')
   parser.add_option('-f', action='store_true', dest='force',
                     help="force yes to questions (don't prompt)")
   parser.add_option('-m', dest='message', help='message for patchset')
   parser.add_option('-t', dest='title', help='title for patchset')
   parser.add_option('-r', '--reviewers',
@@ skipping 302 matching lines @@
   if retcode == 0:
     hook = POSTUPSTREAM_HOOK_PATTERN % cmd
     if os.path.isfile(hook):
       RunCommand([hook, base_branch], error_ok=True)
 
   return 0
 
 
 @usage('[upstream branch to apply against]')
 def CMDdcommit(parser, args):
-  """commit the current changelist via git-svn"""
+  """Commits the current changelist via git-svn."""
   if not settings.GetIsGitSvn():
     message = """This doesn't appear to be an SVN repository.
 If your project has a git mirror with an upstream SVN master, you probably need
 to run 'git svn init', see your project's git mirror documentation.
 If your project has a true writeable upstream repository, you probably want
 to run 'git cl push' instead.
 Choose wisely, if you get this wrong, your commit might appear to succeed but
 will instead be silently ignored."""
     print(message)
     ask_for_data('[Press enter to dcommit or ctrl-C to quit]')
   return SendUpstream(parser, args, 'dcommit')
 
 
 @usage('[upstream branch to apply against]')
 def CMDpush(parser, args):
-  """commit the current changelist via git"""
+  """Commits the current changelist via git."""
   if settings.GetIsGitSvn():
     print('This appears to be an SVN repository.')
     print('Are you sure you didn\'t mean \'git cl dcommit\'?')
     ask_for_data('[Press enter to push or ctrl-C to quit]')
   return SendUpstream(parser, args, 'push')
 
 
 @usage('<patch url or issue id>')
 def CMDpatch(parser, args):
-  """patch in a code review"""
+  """Patchs in a code review."""
   parser.add_option('-b', dest='newbranch',
                     help='create a new branch off trunk for the patch')
   parser.add_option('-f', action='store_true', dest='force',
                     help='with -b, clobber any existing branch')
   parser.add_option('--reject', action='store_true', dest='reject',
                     help='failed patches spew .rej files rather than '
                         'attempting a 3-way merge')
   parser.add_option('-n', '--no-commit', action='store_true', dest='nocommit',
                     help="don't commit after patch applies")
   (options, args) = parser.parse_args(args)
@@ skipping 69 matching lines @@
     cl = Changelist()
     cl.SetIssue(issue)
     cl.SetPatchset(patchset)
     print "Committed patch locally."
   else:
     print "Patch applied to index."
   return 0
 
 
 def CMDrebase(parser, args):
-  """rebase current branch on top of svn repo"""
+  """Rebases current branch on top of svn repo."""
   # Provide a wrapper for git svn rebase to help avoid accidental
   # git svn dcommit.
   # It's the only command that doesn't use parser at all since we just defer
   # execution to git-svn.
   env = os.environ.copy()
   # 'cat' is a magical git string that disables pagers on all platforms.
   env['GIT_PAGER'] = 'cat'
 
   return subprocess2.call(['git', 'svn', 'rebase'] + args, env=env)
 
@@ skipping 17 matching lines @@
   with the reason for the tree to be opened or closed."""
   url = settings.GetTreeStatusUrl()
   json_url = urlparse.urljoin(url, '/current?format=json')
   connection = urllib2.urlopen(json_url)
   status = json.loads(connection.read())
   connection.close()
   return status['message']
 
 
 def CMDtree(parser, args):
-  """show the status of the tree"""
+  """Shows the status of the tree."""
   _, args = parser.parse_args(args)
   status = GetTreeStatus()
   if 'unset' == status:
     print 'You must configure your tree status URL by running "git cl config".'
     return 2
 
   print "The tree is %s" % status
   print
   print GetTreeStatusReason()
   if status != 'open':
@@ skipping 95 matching lines @@
       builders_and_tests)
   print('Tried jobs on:')
   length = max(len(builder) for builder in builders_and_tests)
   for builder in sorted(builders_and_tests):
     print '  %*s: %s' % (length, builder, ','.join(builders_and_tests[builder]))
   return 0
 
 
 @usage('[new upstream branch]')
 def CMDupstream(parser, args):
-  """prints or sets the name of the upstream branch, if any"""
+  """Prints or sets the name of the upstream branch, if any."""
   _, args = parser.parse_args(args)
   if len(args) > 1:
     parser.error('Unrecognized args: %s' % ' '.join(args))
     return 0
 
   cl = Changelist()
   if args:
     # One arg means set upstream branch.
     RunGit(['branch', '--set-upstream', cl.GetBranch(), args[0]])
     cl = Changelist()
     print "Upstream branch set to " + cl.GetUpstreamBranch()
   else:
     print cl.GetUpstreamBranch()
   return 0
 
 
 def CMDset_commit(parser, args):
-  """set the commit bit"""
+  """Sets the commit bit to trigger the Commit Queue."""
   _, args = parser.parse_args(args)
   if args:
     parser.error('Unrecognized args: %s' % ' '.join(args))
   cl = Changelist()
   cl.SetFlag('commit', '1')
   return 0
 
 
 def CMDset_close(parser, args):
-  """close the issue"""
+  """Closes the issue."""
   _, args = parser.parse_args(args)
   if args:
     parser.error('Unrecognized args: %s' % ' '.join(args))
   cl = Changelist()
   # Ensure there actually is an issue to close.
   cl.GetDescription()
   cl.CloseIssue()
   return 0
 
 
 def CMDformat(parser, args):
-  """run clang-format on the diff"""
+  """Runs clang-format on the diff."""
   CLANG_EXTS = ['.cc', '.cpp', '.h']
   parser.add_option('--full', action='store_true', default=False)
   opts, args = parser.parse_args(args)
   if args:
     parser.error('Unrecognized args: %s' % ' '.join(args))
 
   # Generate diff for the current branch's changes.
   diff_cmd = ['diff', '--no-ext-diff', '--no-prefix']
   if opts.full:
     # Only list the names of modified files.
@@ skipping 76 matching lines @@
     return
 
   if hamming_commands[0][0] < 0.8:
     # Not similar enough. Don't be a fool and run a random command.
     return
 
   return commands[hamming_commands[0][1]]
 
 
 def CMDhelp(parser, args):
-  """print list of commands or help for a specific command"""
+  """Prints list of commands or help for a specific command."""
   _, args = parser.parse_args(args)
   if len(args) == 1:
     return main(args + ['--help'])
   parser.print_help()
   return 0
 
 
 def GenUsage(parser, command):
   """Modify an OptParse object with the function's documentation."""
   obj = Command(command)
   # Get back the real command name in case Command() guess the actual command
   # name.
   command = obj.__name__[3:]
   more = getattr(obj, 'usage_more', '')
   if command == 'help':
     command = '<command>'
   else:
-    # OptParser.description prefer nicely non-formatted strings.
-    parser.description = re.sub('[\r\n ]{2,}', ' ', obj.__doc__)
+    parser.description = obj.__doc__
   parser.set_usage('usage: %%prog %s [options] %s' % (command, more))
 
 
+class OptionParser(optparse.OptionParser):
+  """Creates the option parse and add --verbose support."""
+  def __init__(self, *args, **kwargs):
+    optparse.OptionParser.__init__(self, *args, **kwargs)
+    self.add_option(
+        '-v', '--verbose', action='count', default=0,
+        help='Use 2 times for more debugging info')
+
+  def parse_args(self, args=None, values=None):
+    options, args = optparse.OptionParser.parse_args(self, args, values)
+    levels = [logging.WARNING, logging.INFO, logging.DEBUG]
+    logging.basicConfig(level=levels[min(options.verbose, len(levels) - 1)])
+    return options, args
+
+  def format_description(self, _):
+    """Disables automatic reformatting."""
+    lines = self.description.rstrip().splitlines()
+    lines_fixed = [lines[0]] + [l[2:] if len(l) >= 2 else l for l in lines[1:]]
+    description = ''.join(l + '\n' for l in lines_fixed)
+    return description[0].upper() + description[1:]
+
+
 def main(argv):
   """Doesn't parse the arguments here, just find the right subcommand to
   execute."""
   if sys.hexversion < 0x02060000:
     print >> sys.stderr, (
         '\nYour python version %s is unsupported, please upgrade.\n' %
         sys.version.split(' ', 1)[0])
     return 2
 
   # Reload settings.
   global settings
   settings = Settings()
 
   # Do it late so all commands are listed.
   commands = Commands()
   length = max(len(c) for c in commands)
+
+  def gen_summary(x):
+    """Creates a oneline summary from the docstring."""
+    line = x.split('\n', 1)[0].rstrip('.')
+    return line[0].lower() + line[1:]
+
   docs = sorted(
-      (name, handler.__doc__.split('\n')[0].strip())
+      (name, gen_summary(handler.__doc__).strip())
       for name, handler in commands.iteritems())
   CMDhelp.usage_more = ('\n\nCommands are:\n' + '\n'.join(
       '  %-*s %s' % (length, name, doc) for name, doc in docs))
 
-  # Create the option parse and add --verbose support.
-  parser = optparse.OptionParser()
-  parser.add_option(
-      '-v', '--verbose', action='count', default=0,
-      help='Use 2 times for more debugging info')
-  old_parser_args = parser.parse_args
-  def Parse(args):
-    options, args = old_parser_args(args)
-    if options.verbose >= 2:
-      logging.basicConfig(level=logging.DEBUG)
-    elif options.verbose:
-      logging.basicConfig(level=logging.INFO)
-    else:
-      logging.basicConfig(level=logging.WARNING)
-    return options, args
-  parser.parse_args = Parse
-
+  parser = OptionParser()
   if argv:
     command = Command(argv[0])
     if command:
       # "fix" the usage and the description now that we know the subcommand.
       GenUsage(parser, argv[0])
       try:
         return command(parser, argv[1:])
       except urllib2.HTTPError, e:
         if e.code != 500:
           raise
         DieWithError(
             ('AppEngine is misbehaving and returned HTTP %d, again. Keep faith '
              'and retry or visit go/isgaeup.\n%s') % (e.code, str(e)))
 
   # Not a known command. Default to help.
   GenUsage(parser, 'help')
   return CMDhelp(parser, argv)
 
 
 if __name__ == '__main__':
   # These affect sys.stdout so do it outside of main() to simplify mocks in
   # unit testing.
   fix_encoding.fix_encoding()
   colorama.init()
   sys.exit(main(sys.argv[1:]))