git_utils.py: allow checkouts of local repositories at any commithash along master branch

py/utils/git_utils.py

 #!/usr/bin/env python
 # Copyright (c) 2014 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.
 
 """This module contains functions for using git."""
 
 import os
 import re
 import shell_utils
@@ skipping 134 matching lines @@
           self.commit_and_upload(use_commit_queue=self._commit_queue)
       finally:
         shell_utils.run([GIT, 'checkout', 'master'])
         if self._delete_when_finished:
           shell_utils.run([GIT, 'branch', '-D', self._branch_name])
 
 
 class NewGitCheckout(object):
   """Creates a new local checkout of a Git repository."""
 
-  def __init__(self, repository, refspec=None, subdir=None,
-               containing_dir=None):
-    """Check out a new local copy of the repository.
+  def __init__(self, repository, refspec=None, commit='HEAD',
+               subdir=None, containing_dir=None):
+    """Set parameters for this local copy of a Git repository.
 
     Because this is a new checkout, rather than a reference to an existing
     checkout on disk, it is safe to assume that the calling thread is the
     only thread manipulating the checkout.
 
-    You can use the 'with' statement to create this object in such a way that
-    it cleans up after itself:
+    You must use the 'with' statement to create this object:
 
     with NewGitCheckout(*args) as checkout:
       # use checkout instance
     # the checkout is automatically cleaned up here
 
     Args:
-      repository: name of the remote repository
-      refspec: an arbitrary remote ref (e.g., the name of a branch);
-          if None, allow the git command to pick a default
+      repository: URL of the remote repository (e.g.,
+          'https://skia.googlesource.com/common') or path to a local repository
+          (e.g., '/path/to/repo/.git') to check out a copy of
+      refspec: which refs (e.g., a branch name) to fetch from the repository;
+          if None, git-fetch will choose the default refs to fetch
+      commit: commit hash, branch, or tag within refspec, indicating what point
+          to update the local checkout to
       subdir: if specified, the caller only wants access to files within this
           subdir in the repository.
           For now, we check out the entire repository regardless of this param,
           and just hide the rest of the repository; but later on we may
           optimize performance by only checking out this part of the repo.
       containing_dir: if specified, the new checkout will be created somewhere
           within this directory; otherwise, a system-dependent default location
           will be used, as determined by tempfile.mkdtemp()
     """
-    # _git_root points to the tree holding the git checkout in its entirety;
-    # _file_root points to the files the caller wants to look at
-    self._git_root = tempfile.mkdtemp(dir=containing_dir)
-    if subdir:
-      self._file_root = os.path.join(self._git_root, subdir)
-    else:
-      self._file_root = self._git_root
+    self._repository = repository
+    self._refspec = refspec
+    self._commit = commit
+    self._subdir = subdir
+    self._containing_dir = containing_dir
+    self._git_root = None
+    self._file_root = None
 
-    pull_cmd = [GIT, 'pull', repository]
-    if refspec:
-      pull_cmd.append(refspec)
-    self._run_in_git_root(args=[GIT, 'init'])
-    self._run_in_git_root(args=pull_cmd)
 
   @property
   def root(self):
     """Returns the root directory containing the checked-out files.
 
     If you specified the subdir parameter in the constructor, this directory
     will point at just the subdir you requested.
     """
     return self._file_root
 
   def commithash(self):
     """Returns the commithash of the local checkout."""
     return self._run_in_git_root(
         args=[GIT, 'rev-parse', 'HEAD']).strip()
 
   def __enter__(self):
+    """Check out a new local copy of the repository.
+
+    Uses the parameters that were passed into the constructor.
+    """
+    # _git_root points to the tree holding the git checkout in its entirety;
+    # _file_root points to the files the caller wants to look at
+    self._git_root = tempfile.mkdtemp(dir=self._containing_dir)
+    if self._subdir:
+      self._file_root = os.path.join(self._git_root, self._subdir)
+    else:
+      self._file_root = self._git_root
+
+    local_branch_name = 'local'
+    self._run_in_git_root(args=[GIT, 'init'])
+    fetch_cmd = [GIT, 'fetch', self._repository]
+    if self._refspec:
+      fetch_cmd.append(self._refspec)
+    self._run_in_git_root(args=fetch_cmd)
+    self._run_in_git_root(args=[GIT, 'merge', 'FETCH_HEAD'])
+    self._run_in_git_root(args=[GIT, 'branch', local_branch_name, self._commit])
+    self._run_in_git_root(args=[GIT, 'checkout', local_branch_name])
+
     return self
 
   # pylint: disable=W0622
   def __exit__(self, type, value, traceback):
     shutil.rmtree(self._git_root)
 
   def _run_in_git_root(self, args):
     """Run an external command with cwd set to self._git_root.
 
     Returns the command's output as a byte string.
 
     Raises an Exception if the command fails.
     """
     return subprocess.check_output(args=args, cwd=self._git_root)