Update docs for git usage

chromium-os BUG=1189

Review URL: http://codereview.chromium.org/551002

git-svn-id: svn://svn.chromium.org/chrome/trunk/tools/depot_tools@36129 0039d316-1c4b-4281-b951-d872f2087c98

gclient.py

@@ -17,9 +17,10 @@
 """A wrapper script to manage a set of client modules in different SCM.
 
 This script is intended to be used to help basic management of client
-program sources residing in one or more Subversion modules, along with
-other modules it depends on, also in Subversion, but possibly on
-multiple respositories, making a wrapper system apparently necessary.
+program sources residing in one or more Subversion modules and Git
+repositories, along with other modules it depends on, also in Subversion or Git,
+but possibly on multiple respositories, making a wrapper system apparently
+necessary.
 
 Files
   .gclient      : Current client configuration, written by 'config' command.
@@ -85,8 +86,8 @@ import gclient_utils
 
 # default help text
 DEFAULT_USAGE_TEXT = (
-"""usage: %prog <subcommand> [options] [--] [svn options/args...]
-a wrapper for managing a set of client modules in svn.
+"""usage: %prog <subcommand> [options] [--] [SCM options/args...]
+a wrapper for managing a set of svn client modules and/or git repositories.
 Version """ + __version__ + """
 
 subcommands:
@@ -102,7 +103,7 @@ subcommands:
    runhooks
    revinfo
 
-Options and extra arguments can be passed to invoked svn commands by
+Options and extra arguments can be passed to invoked SCM commands by
 appending them to the command line.  Note that if the first such
 appended option starts with a dash (-) then the options must be
 preceded by -- to distinguish them from gclient options.
@@ -125,7 +126,7 @@ in the repository) are *not* modified. Unless --nohooks is provided,
 the hooks are run.
 This a synonym for 'gclient %(alias)s'
 
-usage: gclient %(cmd)s [options] [--] [svn update options/args]
+usage: gclient %(cmd)s [options] [--] [SCM update options/args]
 
 Valid options:
   --force                 : force update even for unchanged modules
@@ -137,10 +138,10 @@ Valid options:
 
 Examples:
   gclient %(cmd)s
-      update files from SVN according to current configuration,
+      update files from SCM according to current configuration,
       *for modules which have changed since last update or sync*
   gclient %(cmd)s --force
-      update files from SVN according to current configuration, for
+      update files from SCM according to current configuration, for
       all modules (useful for recovering files deleted from local copy)
   gclient %(cmd)s --revision src@31000
       update src directory to r31000

gclient_scm.py

@@ -17,7 +17,7 @@ import gclient_utils
 class DiffFilterer(object):
   """Simple class which tracks which file is being diffed and
   replaces instances of its file name in the original and
-  working copy lines of the svn diff output."""
+  working copy lines of the svn/git diff output."""
   index_string = "Index: "
   original_prefix = "--- "
   working_prefix = "+++ "
@@ -55,7 +55,6 @@ class DiffFilterer(object):
 # Factory Method for SCM wrapper creation
 
 def CreateSCM(url=None, root_dir=None, relpath=None, scm_name='svn'):
-  # TODO(maruel): Deduce the SCM from the url.
   scm_map = {
     'svn' : SVNWrapper,
     'git' : GitWrapper,
@@ -78,9 +77,8 @@ def CreateSCM(url=None, root_dir=None, relpath=None, scm_name='svn'):
 class SCMWrapper(object):
   """Add necessary glue between all the supported SCM.
 
-  This is the abstraction layer to bind to different SCM. Since currently only
-  subversion is supported, a lot of subersionism remains. This can be sorted out
-  once another SCM is supported."""
+  This is the abstraction layer to bind to different SCM.
+  """
   def __init__(self, url=None, root_dir=None, relpath=None,
                scm_name='svn'):
     self.scm_name = scm_name
@@ -128,6 +126,11 @@ class GitWrapper(SCMWrapper, scm.GIT):
     self._Run(['diff', merge_base], redirect_stdout=False)
 
   def export(self, options, args, file_list):
+    """Export a clean directory tree into the given path.
+
+    Exports into the specified directory, creating the path if it does
+    already exist.
+    """
     __pychecker__ = 'unusednames=file_list,options'
     assert len(args) == 1
     export_path = os.path.abspath(os.path.join(args[0], self.relpath))
@@ -138,7 +141,11 @@ class GitWrapper(SCMWrapper, scm.GIT):
 
   def pack(self, options, args, file_list):
     """Generates a patch file which can be applied to the root of the
-    repository."""
+    repository.
+
+    The patch file is generated from a diff of the merge base of HEAD and
+    its upstream branch.
+    """
     __pychecker__ = 'unusednames=file_list,options'
     path = os.path.join(self._root_dir, self.relpath)
     merge_base = self._Run(['merge-base', 'HEAD', 'origin'])
@@ -324,6 +331,7 @@ class SVNWrapper(SCMWrapper, scm.SVN):
     self.Run(command, os.path.join(self._root_dir, self.relpath))
 
   def export(self, options, args, file_list):
+    """Export a clean directory tree into the given path."""
     __pychecker__ = 'unusednames=file_list,options'
     assert len(args) == 1
     export_path = os.path.abspath(os.path.join(args[0], self.relpath))
@@ -348,7 +356,7 @@ class SVNWrapper(SCMWrapper, scm.SVN):
     self.RunAndFilterOutput(command, path, False, False, filterer.Filter)
 
   def update(self, options, args, file_list):
-    """Runs SCM to update or transparently checkout the working copy.
+    """Runs svn to update or transparently checkout the working copy.
 
     All updated files will be appended to file_list.
 

scm.py

@@ -101,7 +101,7 @@ class GIT(object):
 
     Args:
       args: A sequence of command line parameters to be passed.
-      in_directory: The directory where svn is to be run.
+      in_directory: The directory where git is to be run.
       print_messages: Whether to print status messages to stdout about
         which commands are being run.
       print_stdout: Whether to forward program's output to stdout.