Massive overhaul for gcl help

gcl.py

 #!/usr/bin/python
 # Copyright (c) 2006-2009 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.
 
-"""Wrapper script around Rietveld's upload.py that groups files into
-changelists."""
+"""\
+Wrapper script around Rietveld's upload.py that simplifies working with groups
+of files.
+"""
 
 import getpass
 import os
 import random
 import re
 import shutil
 import string
 import subprocess
 import sys
 import tempfile
 import time
 from third_party import upload
 import urllib2
 
 __pychecker__ = 'unusednames=breakpad'
 import breakpad
 __pychecker__ = ''
 
 # gcl now depends on gclient.
 from scm import SVN
 import gclient_utils
 
-__version__ = '1.1.4'
+__version__ = '1.2'
 
 
 CODEREVIEW_SETTINGS = {
   # Ideally, we want to set |CODE_REVIEW_SERVER| to a generic server like
   # codereview.appspot.com and remove |CC_LIST| and |VIEW_VC|. In practice, we
   # need these settings so developers making changes in directories such as
   # Chromium's src/third_party/WebKit will send change lists to the correct
   # server.
   #
   # To make gcl send reviews to a different server, check in a file named
@@ skipping 34 matching lines @@
     home_vars.append('USERPROFILE')
   for home_var in home_vars:
     home = os.getenv(home_var)
     if home != None:
       full_path = os.path.join(home, filename)
       if os.path.exists(full_path):
         return full_path
   return None
 
 
-def UnknownFiles(extra_args):
-  """Runs svn status and returns unknown files.
-
-  Any args in |extra_args| are passed to the tool to support giving alternate
-  code locations.
-  """
-  return [item[1] for item in SVN.CaptureStatus(extra_args)
-          if item[0][0] == '?']
+def UnknownFiles():
+  """Runs svn status and returns unknown files."""
+  return [item[1] for item in SVN.CaptureStatus([]) if item[0][0] == '?']
 
 
 def GetRepositoryRoot():
   """Returns the top level directory of the current repository.
 
   The directory is returned as an absolute path.
   """
   global REPOSITORY_ROOT
   if not REPOSITORY_ROOT:
     REPOSITORY_ROOT = SVN.GetCheckoutRoot(os.getcwd())
@@ skipping 502 matching lines @@
       continue
     note = ""
     change_info = ChangeInfo.Load(cl_name, GetRepositoryRoot(),
                                   fail_on_not_found=True, update_status=False)
     if len(change_info.GetFiles()) != len(files[cl_name]):
       note = " (Note: this changelist contains files outside this directory)"
     print "\n--- Changelist " + cl_name + note + ":"
     for filename in files[cl_name]:
       print "".join(filename)
   if show_unknown_files:
-    unknown_files = UnknownFiles([])
+    unknown_files = UnknownFiles()
   if (files.get('') or (show_unknown_files and len(unknown_files))):
     print "\n--- Not in any changelist:"
     for item in files.get('', []):
       print "".join(item)
     if show_unknown_files:
       for filename in unknown_files:
         print "?      %s" % filename
   return 0
 
 
-def CMDopened(args):
-  """Lists modified files in the current directory down."""
-  if args:
-    ErrorExit("Doesn't support arguments")
-  return ListFiles(False)
-
-
-def CMDstatus(args):
-  """Lists modified and unknown files in the current directory down."""
-  if args:
-    ErrorExit("Doesn't support arguments")
-  return ListFiles(True)
-
-
-def CMDhelp(args):
-  """Prints this help or help for the given command."""
-  if args and len(args) > 2:
-    if args[2] == 'try':
-      return TryChange(None, ['--help'], swallow_exception=False)
-    if args[2] == 'upload':
-      upload.RealMain(['upload.py', '--help'])
-      return 0
-
-  print (
-"""GCL is a wrapper for Subversion that simplifies working with groups of files.
-version """ + __version__ + """
-
-Basic commands:
------------------------------------------
-   gcl change change_name
-      Add/remove files to a changelist. Only scans the current directory and
-      subdirectories.
-
-   gcl upload change_name [-r reviewer1@gmail.com,reviewer2@gmail.com,...]
-                          [--send_mail] [--no_try] [--no_presubmit]
-                          [--no_watchlists]
-      Uploads the changelist to the server for review.
-      (You can create the file '.gcl_upload_no_try' in your home dir to
-      skip the automatic tries.)
-
-   gcl commit change_name [--no_presubmit]
-      Commits the changelist to the repository.
-
-   gcl lint change_name
-      Check all the files in the changelist for possible style violations.
-
-Advanced commands:
------------------------------------------
-   gcl delete change_name
-      Deletes a changelist.
-
-   gcl diff change_name
-      Diffs all files in the changelist.
-
-   gcl presubmit change_name
-      Runs presubmit checks without uploading the changelist.
-
-   gcl diff
-      Diffs all files in the current directory and subdirectories that aren't in
-      a changelist.
-
-   gcl description
-      Prints the description of the specified change to stdout.
-
-   gcl changes
-      Lists all the the changelists and the files in them.
-
-   gcl rename <old-name> <new-name>
-      Renames an existing change.
-
-   gcl nothave [optional directory]
-      Lists files unknown to Subversion.
-
-   gcl opened
-      Lists modified files in the current directory and subdirectories.
-
-   gcl settings
-      Print the code review settings for this directory.
-
-   gcl status
-      Lists modified and unknown files in the current directory and
-      subdirectories.
-
-   gcl try change_name
-      Sends the change to the tryserver so a trybot can do a test run on your
-      code. To send multiple changes as one path, use a comma-separated list
-      of changenames.
-      --> Use 'gcl help try' for more information!
-
-   gcl deleteempties
-      Deletes all changelists that have no files associated with them. Careful,
-      you can lose your descriptions.
-
-   gcl help [command]
-      Print this help menu, or help for the given command if it exists.
-""")
-  return 0
-
-
 def GetEditor():
   editor = os.environ.get("SVN_EDITOR")
   if not editor:
     editor = os.environ.get("EDITOR")
 
   if not editor:
     if sys.platform.startswith("win"):
       editor = "notepad"
     else:
       editor = "vi"
 
   return editor
 
 
 def GenerateDiff(files, root=None):
   return SVN.GenerateDiff(files, root=root)
 
 
 def OptionallyDoPresubmitChecks(change_info, committing, args):
   if FilterFlag(args, "--no_presubmit") or FilterFlag(args, "--force"):
     return True
   return DoPresubmitChecks(change_info, committing, True)
 
 
+def defer_attributes(a, b):
+  """Copy attributes from an object (like a function) to another."""
+  for x in dir(a):
+    if not getattr(b, x, None):
+      setattr(b, x, getattr(a, x))
+
+
 def need_change(function):
   """Converts args -> change_info."""
   def hook(args):
     if not len(args) == 1:
       ErrorExit("You need to pass a change list name")
     change_info = ChangeInfo.Load(args[0], GetRepositoryRoot(), True, True)
     return function(change_info)
+  defer_attributes(function, hook)
+  hook.need_change = True
+  hook.no_args = True
   return hook
 
 
-def CMDupload(args):
-  if not args:
-    ErrorExit("You need to pass a change list name")
-  change_info = ChangeInfo.Load(args.pop(0), GetRepositoryRoot(), True, True)
+def need_change_and_args(function):
+  """Converts args -> change_info."""
+  def hook(args):
+    change_info = ChangeInfo.Load(args.pop(0), GetRepositoryRoot(), True, True)
+    return function(change_info, args)
+  defer_attributes(function, hook)
+  hook.need_change = True
+  return hook
+
+
+def no_args(function):
+  """Make sure no args are passed."""
+  def hook(args):
+    if args:
+      ErrorExit("Doesn't support arguments")
+    return function()
+  defer_attributes(function, hook)
+  hook.no_args = True
+  return hook
+
+
+def attrs(**kwargs):
+  """Decorate a function with new attributes."""
+  def decorate(function):
+    for k in kwargs:
+      setattr(function, k, kwargs[k])
+    return function
+  return decorate
+
+
+@no_args
+def CMDopened():
+  """Lists modified files in the current directory down."""
+  return ListFiles(False)
+
+
+@no_args
+def CMDstatus():
+  """Lists modified and unknown files in the current directory down."""
+  return ListFiles(True)
+
+
+@need_change_and_args
+@attrs(usage='[--no_try] [--no_presubmit] [--clobber]\n'
+    '                          [--no_watchlists]')
+def CMDupload(change_info, args):
+  """Uploads the changelist to the server for review.
+
+  (You can create the file '.gcl_upload_no_try' in your home dir to
+  skip the automatic tries.)
+  """
   if not change_info.GetFiles():
     print "Nothing to upload, changelist is empty."
     return 0
   if not OptionallyDoPresubmitChecks(change_info, False, args):
     return 1
   # Might want to support GetInfoDir()/GetRepositoryRoot() like
   # CheckHomeForFile() so the skip of tries can be per tree basis instead
   # of user global.
-  no_try = FilterFlag(args, "--no_try") or \
-           FilterFlag(args, "--no-try") or \
-           not (CheckHomeForFile(".gcl_upload_no_try") is None)
-  no_watchlists = FilterFlag(args, "--no_watchlists") or \
-                  FilterFlag(args, "--no-watchlists")
+  no_try = (FilterFlag(args, "--no_try") or
+            FilterFlag(args, "--no-try") or
+            not (CheckHomeForFile(".gcl_upload_no_try") is None))
+  no_watchlists = (FilterFlag(args, "--no_watchlists") or
+                   FilterFlag(args, "--no-watchlists"))
 
   # Map --send-mail to --send_mail
   if FilterFlag(args, "--send-mail"):
     args.append("--send_mail")
 
   # Supports --clobber for the try server.
   clobber = FilterFlag(args, "--clobber")
 
   # Disable try when the server is overridden.
   server_1 = re.compile(r"^-s\b.*")
@@ skipping 84 matching lines @@
     if try_on_upload and try_on_upload.lower() == 'true':
       trychange_args = []
       if clobber:
         trychange_args.append('--clobber')
       return TryChange(change_info, trychange_args, swallow_exception=True)
   return 0
 
 
 @need_change
 def CMDpresubmit(change_info):
-  """Runs presubmit checks on the change."""
+  """Runs presubmit checks on the change.
+
+  The actual presubmit code is implemented in presubmit_support.py and looks
+  for PRESUBMIT.py files."""
   if not change_info.GetFiles():
     print "Nothing to presubmit check, changelist is empty."
     return 0
 
   print "*** Presubmit checks for UPLOAD would report: ***"
   result = DoPresubmitChecks(change_info, False, False)
 
   print "\n*** Presubmit checks for COMMIT would report: ***"
   result &= DoPresubmitChecks(change_info, True, False)
   return not result
@@ skipping 19 matching lines @@
     file_list = change_info.GetFileNames()
   else:
     trychange_args.extend(args)
     file_list = None
   return trychange.TryChange(trychange_args,
                              file_list=file_list,
                              swallow_exception=swallow_exception,
                              prog='gcl try')
 
 
-def CMDcommit(args):
-  if not args:
-    ErrorExit("You need to pass a change list name")
-  change_info = ChangeInfo.Load(args.pop(0), GetRepositoryRoot(), True, True)
+@need_change_and_args
+@attrs(usage='[--no_presubmit]')
+def CMDcommit(change_list, args):
+  """Commits the changelist to the repository."""
   if not change_info.GetFiles():
     print "Nothing to commit, changelist is empty."
     return 1
   if not OptionallyDoPresubmitChecks(change_info, True, args):
     return 1
 
   # We face a problem with svn here: Let's say change 'bleh' modifies
   # svn:ignore on dir1\. but another unrelated change 'pouet' modifies
   # dir1\foo.cc. When the user `gcl commit bleh`, foo.cc is *also committed*.
   # The only fix is to use --non-recursive but that has its issues too:
@@ skipping 37 matching lines @@
       viewvc_url = GetCodeReviewSetting("VIEW_VC")
       change_info.description = change_info.description + '\n'
       if viewvc_url:
         change_info.description += "\nCommitted: " + viewvc_url + revision
       change_info.CloseIssue()
   os.chdir(previous_cwd)
   return 0
 
 
 def CMDchange(args):
-  """Creates/edits a changelist."""
+  """Creates or edits a changelist.
+
+  Only scans the current directory and subdirectories."""
   if len(args) == 0:
     # Generate a random changelist name.
     changename = GenerateChangeName()
   elif args[0] == '--force':
     changename = GenerateChangeName()
   else:
     changename = args[0]
   change_info = ChangeInfo.Load(changename, GetRepositoryRoot(), False, True)
   silent = FilterFlag(args, "--silent")
 
@@ skipping 99 matching lines @@
     Warn("WARNING: " + MISSING_TEST_MSG)
 
   # Update the Rietveld issue.
   if change_info.issue and change_info.NeedsUpload():
     change_info.UpdateRietveldDescription()
     change_info.needs_upload = False
     change_info.Save()
   return 0
 
 
-@need_change
-def CMDlint(change_info):
-  """Runs cpplint.py on all the files in |change_info|"""
+@need_change_and_args
+def CMDlint(change_info, args):
+  """Runs cpplint.py on all the files in the change list.
+
+  Checks all the files in the changelist for possible style violations.
+  """
   try:
     import cpplint
   except ImportError:
     ErrorExit("You need to install cpplint.py to lint C++ files.")
   # Change the current working directory before calling lint so that it
   # shows the correct base.
   previous_cwd = os.getcwd()
   os.chdir(change_info.GetLocalRoot())
 
   # Process cpplints arguments if any.
@@ skipping 37 matching lines @@
                                                verbose=False,
                                                output_stream=sys.stdout,
                                                input_stream=sys.stdin,
                                                default_presubmit=root_presubmit,
                                                may_prompt=may_prompt)
   if not result and may_prompt:
     print "\nPresubmit errors, can't continue (use --no_presubmit to bypass)"
   return result
 
 
-def CMDchanges(args):
+@no_args
+def CMDchanges():
   """Lists all the changelists and their files."""
-  if args:
-    ErrorExit("Doesn't support arguments")
   for cl in GetCLs():
     change_info = ChangeInfo.Load(cl, GetRepositoryRoot(), True, True)
     print "\n--- Changelist " + change_info.name + ":"
     for filename in change_info.GetFiles():
       print "".join(filename)
   return 0
 
 
-def CMDdeleteempties(args):
+@no_args
+def CMDdeleteempties():
   """Delete all changelists that have no files."""
-  if args:
-    ErrorExit("Doesn't support arguments")
   print "\n--- Deleting:"
   for cl in GetCLs():
     change_info = ChangeInfo.Load(cl, GetRepositoryRoot(), True, True)
     if not len(change_info._files):
       print change_info.name
       change_info.Delete()
   return 0
 
 
-def CMDnothave(args):
+@no_args
+def CMDnothave():
   """Lists files unknown to Subversion."""
-  if args:
-    ErrorExit("Doesn't support arguments")
-  for filename in UnknownFiles(args):
+  for filename in UnknownFiles():
     print "?      " + "".join(filename)
   return 0
 
 
+@attrs(usage='<svn options>')
 def CMDdiff(args):
-  """Diffs all files in the changelist."""
+  """Diffs all files in the changelist or all files that aren't in a CL."""
   files = None
   if args:
-    change_info = ChangeInfo.Load(args[0], GetRepositoryRoot(), True, True)
-    args.pop(0)
+    change_info = ChangeInfo.Load(args.pop(0), GetRepositoryRoot(), True, True)
     files = change_info.GetFileNames()
   else:
     files = GetFilesNotInCL()
   return RunShellWithReturnCode(['svn', 'diff'] + files + args,
                                 print_output=True)[1]
 
 
-def CMDsettings(args):
-  """Prints code review settings."""
-  __pychecker__ = 'unusednames=args'
+@no_args
+def CMDsettings():
+  """Prints code review settings for this checkout."""
   # Force load settings
   GetCodeReviewSetting("UNKNOWN");
   del CODEREVIEW_SETTINGS['__just_initialized']
   print '\n'.join(("%s: %s" % (str(k), str(v))
                     for (k,v) in CODEREVIEW_SETTINGS.iteritems()))
   return 0
 
 
 @need_change
 def CMDdescription(change_info):
   """Prints the description of the specified change to stdout."""
   print change_info.description
   return 0
 
 
 @need_change
 def CMDdelete(change_info):
   """Deletes a changelist."""
   change_info.Delete()
   return 0
 
 
 def CMDtry(args):
-  """Sends the change to the tryserver so a trybot can do a test run on your
-  code.
+  """Sends the change to the tryserver to do a test run on your code.
 
   To send multiple changes as one path, use a comma-separated list of
   changenames. Use 'gcl help try' for more information!"""
   # When the change contains no file, send the "changename" positional
   # argument to trychange.py.
   # When the command is 'try' and --patchset is used, the patch to try
   # is on the Rietveld server.
   if not args:
     ErrorExit("You need to pass a change list name")
   if args[0].find(',') != -1:
     change_info = LoadChangelistInfoForMultiple(args[0], GetRepositoryRoot(),
                                                 True, True)
   else:
     change_info = ChangeInfo.Load(args[0], GetRepositoryRoot(),
                                   False, True)
   if change_info.GetFiles():
     args = args[1:]
   else:
     change_info = None
   return TryChange(change_info, args, swallow_exception=False)
 
 
+@attrs(usage='<old-name> <new-name>')
 def CMDrename(args):
   """Renames an existing change."""
   if len(args) != 2:
     ErrorExit("Usage: gcl rename <old-name> <new-name>.")
   src, dst = args
   src_file = GetChangelistInfoFile(src)
   if not os.path.isfile(src_file):
     ErrorExit("Change '%s' does not exist." % src)
   dst_file = GetChangelistInfoFile(dst)
   if os.path.isfile(dst_file):
     ErrorExit("Change '%s' already exists; pick a new name." % dst)
   os.rename(src_file, dst_file)
   print "Change '%s' renamed '%s'." % (src, dst)
   return 0
 
 
 def CMDpassthru(args):
-  # Everything else that is passed into gcl we redirect to svn, after adding
-  # the files.
-  # args is guaranteed to be len(args) >= 1
+  """Everything else that is passed into gcl we redirect to svn.
+
+  It assumes a change list name is passed and is converted with the files names.
+  """
   args = ["svn", args[0]]
   if len(args) > 1:
     root = GetRepositoryRoot()
     change_info = ChangeInfo.Load(args[1], root, True, True)
     args.extend([os.path.join(root, x) for x in change_info.GetFileNames()])
   return RunShellWithReturnCode(args, print_output=True)[1]
 
 
+def Command(name):
+  return getattr(sys.modules[__name__], 'CMD' + name, None)
+
+
+def GenUsage(command):
+  """Modify an OptParse object with the function's documentation."""
+  obj = Command(command)
+  display = command
+  more = getattr(obj, 'usage', '')
+  if command == 'help':
+    display = '<command>'
+  need_change = ''
+  if getattr(obj, 'need_change', None):
+    need_change = ' <change_list>'
+  options = ' [options]'
+  if getattr(obj, 'no_args', None):
+    options = ''
+  res = 'Usage: gcl %s%s%s %s\n\n' % (display, need_change, options, more)
+  res += re.sub('\n  ', '\n', obj.__doc__)
+  return res
+
+
+def CMDhelp(args):
+  """Prints this help or help for the given command."""
+  if args and 'CMD' + args[0] in dir(sys.modules[__name__]):
+    print GenUsage(args[0])
+
+    # These commands defer to external tools so give this info too.
+    if args[0] == 'try':
+      TryChange(None, ['--help'], swallow_exception=False)
+    if args[0] == 'upload':
+      upload.RealMain(['upload.py', '--help'])
+    return 0
+
+  print GenUsage('help')
+  print sys.modules[__name__].__doc__
+  print 'version ' + __version__ + '\n'
+
+  print('Commands are:\n' + '\n'.join([
+        '  %-12s %s' % (fn[3:], Command(fn[3:]).__doc__.split('\n')[0].strip())
+        for fn in dir(sys.modules[__name__]) if fn.startswith('CMD')]))
+  return 0
+
+
 def main(argv):
-  __pychecker__ = 'maxreturns=0'
   try:
-    # Create the directories where we store information about changelists if it
-    # doesn't exist.
-    if not os.path.exists(GetInfoDir()):
-      os.mkdir(GetInfoDir())
-    if not os.path.exists(GetChangesDir()):
-      os.mkdir(GetChangesDir())
-    if not os.path.exists(GetCacheDir()):
-      os.mkdir(GetCacheDir())
+    GetRepositoryRoot()
   except gclient_utils.Error:
-    # Will throw an exception if not run in a svn checkout.
-    pass
+    print('To use gcl, you need to be in a subversion checkout.')
+    return 1
+
+  # Create the directories where we store information about changelists if it
+  # doesn't exist.
+  if not os.path.exists(GetInfoDir()):
+    os.mkdir(GetInfoDir())
+  if not os.path.exists(GetChangesDir()):
+    os.mkdir(GetChangesDir())
+  if not os.path.exists(GetCacheDir()):
+    os.mkdir(GetCacheDir())
 
   if not argv:
     argv = ['help']
-  # Commands that don't require an argument.
-  command = argv[0]
-  if command == "opened":
-    return CMDopened(argv[1:])
-  if command == "status":
-    return CMDstatus(argv[1:])
-  if command == "nothave":
-    return CMDnothave(argv[1:])
-  if command == "changes":
-    return CMDchanges(argv[1:])
-  if command == "help":
-    return CMDhelp(argv[1:])
-  if command == "diff":
-    return CMDdiff(argv[1:])
-  if command == "settings":
-    return CMDsettings(argv[1:])
-  if command == "deleteempties":
-    return CMDdeleteempties(argv[1:])
-  if command == "rename":
-    return CMDrename(argv[1:])
-  elif command == "change":
-    return CMDchange(argv[1:])
-  elif command == "description":
-    return CMDdescription(argv[1:])
-  elif command == "lint":
-    return CMDlint(argv[1:])
-  elif command == "upload":
-    return CMDupload(argv[1:])
-  elif command == "presubmit":
-    return CMDpresubmit(argv[1:])
-  elif command in ("commit", "submit"):
-    return CMDcommit(argv[1:])
-  elif command == "delete":
-    return CMDdelete(argv[1:])
-  elif command == "try":
-    return CMDtry(argv[1:])
-  else:
-    return CMDpassthru(argv)
+  command = Command(argv[0])
+  if command:
+    return command(argv[1:])
+  # Unknown command, try to pass that to svn
+  return CMDpassthru(argv)
 
 
 if __name__ == "__main__":
   sys.exit(main(sys.argv[1:]))