Update docs for git usage

gclient_scm.py

 # Copyright (c) 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.
 
 """Gclient-specific SCM-specific operations."""
 
 import logging
 import os
 import posixpath
 import re
 import subprocess
 
 import scm
 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 = "+++ "
 
   def __init__(self, relpath):
     # Note that we always use '/' as the path separator to be
     # consistent with svn's cygwin-style output on Windows
     self._relpath = relpath.replace("\\", "/")
     self._current_file = ""
     self._replacement_file = ""
@@ skipping 17 matching lines @@
         self.ReplaceAndPrint(line)
       else:
         print line
 
 
 ### SCM abstraction layer
 
 # 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,
   }
 
   orig_url = url
 
   if url:
     url, _ = gclient_utils.SplitUrlRevision(url)
     if url.startswith('git:') or url.startswith('ssh:') or url.endswith('.git'):
       scm_name = 'git'
 
   if not scm_name in scm_map:
     raise gclient_utils.Error('Unsupported scm %s' % scm_name)
   return scm_map[scm_name](orig_url, root_dir, relpath, scm_name)
 
 
 # SCMWrapper base class
 
 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
     self.url = url
     self._root_dir = root_dir
     if self._root_dir:
       self._root_dir = self._root_dir.replace('/', os.sep)
     self.relpath = relpath
     if self.relpath:
       self.relpath = self.relpath.replace('/', os.sep)
@@ skipping 27 matching lines @@
     self._Run(['prune'], redirect_stdout=False)
     self._Run(['fsck'], redirect_stdout=False)
     self._Run(['gc'], redirect_stdout=False)
 
   def diff(self, options, args, file_list):
     __pychecker__ = 'unusednames=args,file_list,options'
     merge_base = self._Run(['merge-base', 'HEAD', 'origin'])
     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))
     if not os.path.exists(export_path):
       os.makedirs(export_path)
     self._Run(['checkout-index', '-a', '--prefix=%s/' % export_path],
               redirect_stdout=False)
 
   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'])
     command = ['diff', merge_base]
     filterer = DiffFilterer(self.relpath)
     self.RunAndFilterOutput(command, path, False, False, filterer.Filter)
 
   def update(self, options, args, file_list):
     """Runs git to update or transparently checkout the working copy.
 
@@ skipping 159 matching lines @@
     self.Run(command, os.path.join(self._root_dir, self.relpath))
 
   def diff(self, options, args, file_list):
     # NOTE: This function does not currently modify file_list.
     __pychecker__ = 'unusednames=file_list,options'
     command = ['diff']
     command.extend(args)
     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))
     try:
       os.makedirs(export_path)
     except OSError:
       pass
     assert os.path.exists(export_path)
     command = ['export', '--force', '.']
     command.append(export_path)
     self.Run(command, os.path.join(self._root_dir, self.relpath))
 
   def pack(self, options, args, file_list):
     """Generates a patch file which can be applied to the root of the
     repository."""
     __pychecker__ = 'unusednames=file_list,options'
     path = os.path.join(self._root_dir, self.relpath)
     command = ['diff']
     command.extend(args)
 
     filterer = DiffFilterer(self.relpath)
     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.
 
     Raises:
       Error: if can't get URL for relative path.
     """
     # Only update if git is not controlling the directory.
     checkout_path = os.path.join(self._root_dir, self.relpath)
     git_path = os.path.join(self._root_dir, self.relpath, '.git')
     if os.path.exists(git_path):
@@ skipping 165 matching lines @@
     command = ['status']
     command.extend(args)
     if not os.path.isdir(path):
       # svn status won't work if the directory doesn't exist.
       print("\n________ couldn't run \'%s\' in \'%s\':\nThe directory "
             "does not exist."
             % (' '.join(command), path))
       # There's no file list to retrieve.
     else:
       self.RunAndGetFileList(options, command, path, file_list)