Fix semantics of git new-branch --upstream

Currently, the "--upstream A" option for new-branch behaves totally
different than "--upstream_current". While "--upstream A" checks out
branch A and then creates a new branch which tracks A,
"--upstream_current" creates a new branch for the current HEAD and sets
the upstream to the previously checked out branch.

As the documentation does not mention that any of the options changes
the currently-checked-out commit (HEAD), this CL changes the semantics
of "git new-branch --upstream A B" to be identical to "git checkout -b B
&& git branch --set-upstream-to A".

It also slightly extends the documentation to mention that in any case
the new branch is based on HEAD.

R=iannucci@chromium.org

Change-Id: Ic335d2caf27cb6afca1b8bc5a008424c0e880fca
Reviewed-on: https://chromium-review.googlesource.com/c/1350748Reviewed-by: Robbie Iannucci <iannucci@chromium.org>
Commit-Queue: Clemens Hammacher <clemensh@chromium.org>
Auto-Submit: Clemens Hammacher <clemensh@chromium.org>

git_new_branch.py

@@ -58,7 +58,8 @@ def main(args):
       else:
         # TODO(iannucci): Detect unclean workdir then stash+pop if we need to
         # teleport to a conflicting portion of history?
-        run('checkout', '--track', opts.upstream, '-b', opts.branch_name)
+        run('checkout', '-b', opts.branch_name)
+        run('branch', '--set-upstream-to', opts.upstream)
     get_or_create_merge_base(opts.branch_name)
   except subprocess2.CalledProcessError as cpe:
     sys.stdout.write(cpe.stdout)

man/html/git-new-branch.html

@@ -766,9 +766,9 @@ git-new-branch(1) Manual Page
 <div class="sect1">
 <h2 id="_description">DESCRIPTION</h2>
 <div class="sectionbody">
-<div class="paragraph"><p>Creates a new branch. By default the new branch will track the configured
-upstream for the repo (defaults to <em>origin/master</em>). If one of the other options
-is specified, it will track that other ref instead.</p></div>
+<div class="paragraph"><p>Creates a new branch for <strong>HEAD</strong>. By default the new branch will track the
+configured upstream for the repo (defaults to <em>origin/master</em>). If one of the
+other options is specified, it will track that other ref instead.</p></div>
 <div class="paragraph"><p>Conceptually, each branch in your repo represents one <em>Change List (CL)</em>. If you
 have many independent CLs (i.e. the changes in one do not interact with/depend
 on the changes in another), then you should create them as new branches tracking
@@ -917,7 +917,7 @@ from <a href="https://chromium.googlesource.com/chromium/tools/depot_tools.git">
 <div id="footnotes"><hr /></div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2016-12-15 15:36:52 PST
+Last updated 2018-11-26 13:37:45 CET
 </div>
 </div>
 </body>

man/man1/git-new-branch.1

 '\" t
 .\"     Title: git-new-branch
 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
-.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 12/15/2016
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      Date: 11/26/2018
 .\"    Manual: Chromium depot_tools Manual
 .\"    Source: depot_tools f72f1ad
 .\"  Language: English
@@ -40,7 +40,7 @@ git-new-branch \- Create a new branch with correct tracking information\&.
 .sp
 .SH "DESCRIPTION"
 .sp
-Creates a new branch\&. By default the new branch will track the configured upstream for the repo (defaults to \fIorigin/master\fR)\&. If one of the other options is specified, it will track that other ref instead\&.
+Creates a new branch for \fBHEAD\fR\&. By default the new branch will track the configured upstream for the repo (defaults to \fIorigin/master\fR)\&. If one of the other options is specified, it will track that other ref instead\&.
 .sp
 Conceptually, each branch in your repo represents one \fIChange List (CL)\fR\&. If you have many independent CLs (i\&.e\&. the changes in one do not interact with/depend on the changes in another), then you should create them as new branches tracking the default upstream (i\&.e\&. git new\-branch <branch_name>)\&. If you have features which depend on each other, you should create stacked branches using git new\-branch \-\-upstream_current <branch_name>\&.
 .SH "OPTIONS"

man/src/git-new-branch.txt

@@ -17,9 +17,9 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Creates a new branch. By default the new branch will track the configured
-upstream for the repo (defaults to 'origin/master'). If one of the other options
-is specified, it will track that other ref instead.
+Creates a new branch for *HEAD*. By default the new branch will track the
+configured upstream for the repo (defaults to 'origin/master'). If one of the
+other options is specified, it will track that other ref instead.
 
 Conceptually, each branch in your repo represents one 'Change List (CL)'. If you
 have many independent CLs (i.e. the changes in one do not interact with/depend

tests/git_rebase_update_test.py

@@ -69,7 +69,7 @@ class GitRebaseUpdateTest(git_test_utils.GitRepoReadWriteTestBase):
     super(GitRebaseUpdateTest, self).tearDown()
 
   def testRebaseUpdate(self):
-    self.repo.git('checkout', 'branch_K')
+    self.repo.git('checkout', 'origin/master')
 
     self.repo.run(self.nb.main, ['foobar'])
     self.assertEqual(self.repo.git('rev-parse', 'HEAD').stdout,