git recipe_module: git new-branch.

recipe_modules/git/api.py

 # Copyright 2013 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.
 
 import itertools
 import re
 
 from recipe_engine import recipe_api
 
 class GitApi(recipe_api.RecipeApi):
@@ skipping 391 matching lines @@
 
     Args:
       bundle_path (Path): The path of the output bundle.
       refs (list): The list of refs to include in the bundle. If None, all
           refs in the Git checkout will be bundled.
       kwargs: Forwarded to '__call__'.
     """
     if not rev_list_args:
       rev_list_args = ['--all']
     self('bundle', 'create', bundle_path, *rev_list_args, **kwargs)
+
+  def new_branch(self, branch, name=None, upstream=None, **kwargs):
+    """Runs git new-branch on a Git repository, to be used before git cl upload.
+
+    Args:
+      branch: new branch name, which must not yet exist.
+      name: step name.
+      upstream: to origin/master.

[qyearsley, 2016/09/26 16:33:14]

(1) "to origin/master" -> "upstream branch name, defaults to origin/master".
Question: is it correct to call "origin/master" a branch?

(2) To be consistent with other docstrings above you could note that three args
are expected to be strings, and that kwargs is passed on to __call__.

[tandrii(chromium), 2016/09/26 16:49:56]

I think so, as it's shown when you do $ git branch -a
That said, you can specify any refspec here, but let's not confuse users.
 
Done.

+    """
+    env = kwargs.pop('env', {})
+    env['PATH'] = self.m.path.pathsep.join([
+        str(self.package_repo_resource()), '%(PATH)s'])

[qyearsley, 2016/09/26 16:33:14]

I guess that this is required because git-new-branch is in depot_tools? But no
comment is necessary for this.

[tandrii(chromium), 2016/09/26 16:49:56]

yep

+    args = ['new-branch', branch]
+    if upstream:
+      args.extend(['--upstream', upstream])
+    if not name:
+      name = 'git new-branch %s' % branch
+    return self(*args, name=name, env=env, **kwargs)