Add documentation for --inject_current

This change adds documentation and demos missing for the flag
--inject_current used in git new-branch.

Bug: 1167943
Change-Id: Id6305b876ade2c47eb7435a5edd055ae4fe2f323
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/tools/depot_tools/+/2648615
Reviewed-by: Josip Sokcevic <sokcevic@google.com>
Commit-Queue: Gavin Mak <gavinmak@google.com>

man/html/git-new-branch.html

@@ -758,7 +758,8 @@ git-new-branch(1) Manual Page
 <pre class="content"><em>git new-branch</em> &lt;branch_name&gt;
 <em>git new-branch</em> --upstream_current &lt;branch_name&gt;
 <em>git new-branch</em> --upstream &lt;REF&gt; &lt;branch_name&gt;
-<em>git new-branch</em> --lkgr &lt;branch_name&gt;</pre>
+<em>git new-branch</em> --lkgr &lt;branch_name&gt;
+<em>git new-branch</em> --inject_current&lt;branch_name&gt;</pre>
 <div class="attribution">
 </div></div>
 </div>
@@ -807,6 +808,22 @@ new-branch --upstream_current &lt;branch_name&gt;</code>.</p></div>
 </p>
 </dd>
 <dt class="hdlist1">
+--inject_current
+</dt>
+<dd>
+<p>
+  Set the tracking (upstream) branch of the newly-created branch to the
+  tracking (upstream) branch of the currently-checked-out branch and set the
+  tracking (upstream) branch of the currently-checked-out branch to the
+  newly-created branch.
+  <br>
+  <br>
+  Before: current &gt; upstream
+  <br>
+  After: current &gt; new &gt; upstream
+</p>
+</dd>
+<dt class="hdlist1">
 &lt;branch_name&gt;
 </dt>
 <dd>
@@ -875,12 +892,28 @@ Your branch is ahead of 'origin/master' by 4 commits.
 </span><span style="color: #19c518"></span><span style="color: #19c518">      nested_cl                     </span><span style="color: #ffffff">  </span><span style="color: #d338d3">        </span><span style="color: #ffffff">  </span><span style="color: #d338d3">         </span><span style="color: #ffffff">
 </span><span style="color: #19c518"></span><span style="color: #19c518">  fixit                             </span><span style="color: #ffffff">[ </span><span style="color: #d338d3">ahead 2 </span><span style="color: #ffffff">  </span><span style="color: #d338d3">         </span><span style="color: #ffffff">]
 </span><span style="color: #19c518"></span><span style="color: #19c518">    frozen_branch                   </span><span style="color: #ffffff">[ </span><span style="color: #d338d3">ahead 3 </span><span style="color: #ffffff">  </span><span style="color: #d338d3">         </span><span style="color: #ffffff">]
+</span><span style="color: #19c518"></span><span style="color: #19c518">  independent_cl                    </span><span style="color: #ffffff">[ </span><span style="color: #d338d3">ahead 1 </span><span style="color: #ffffff">  </span><span style="color: #d338d3">         </span><span style="color: #ffffff">]
+</span><span style="font-weight: bold; color: #ffffff">$ git checkout subfeature</span>
+Switched to branch 'subfeature'
+Your branch and 'cool_feature' have diverged,
+and have 2 and 1 different commits each, respectively.
+  (use "git pull" to merge the remote branch into yours)
+<span style="font-weight: bold; color: #ffffff">$ git new-branch --inject_current injected_cl</span>
+<span style="font-weight: bold; color: #ffffff">$ git map-branches -v</span>
+<span style="color: #e42e16"></span><span style="color: #e42e16">origin/master                       </span><span style="color: #ffffff">  </span><span style="color: #d338d3">        </span><span style="color: #ffffff">  </span><span style="color: #d338d3">         </span><span style="color: #ffffff">
+</span><span style="color: #33d6e5"></span><span style="font-weight: bold; color: #33d6e5">  cool_feature                      </span><span style="font-weight: bold; color: #ffffff">[ </span><span style="font-weight: bold; color: #d338d3">ahead 4 </span><span style="font-weight: bold; color: #ffffff">  </span><span style="font-weight: bold; color: #d338d3">         </span><span style="font-weight: bold; color: #ffffff">]</span> <b>&lt;1&gt;</b><span>
+</span><span style="font-weight: bold; color: #33d6e5"></span><span style="font-weight: bold; color: #33d6e5">    cl_depends_on_cool_feature      </span><span style="font-weight: bold; color: #ffffff">  </span><span style="font-weight: bold; color: #d338d3">        </span><span style="font-weight: bold; color: #ffffff">  </span><span style="font-weight: bold; color: #d338d3">         </span><span style="font-weight: bold; color: #ffffff">
+</span><span style="font-weight: bold; color: #33d6e5"></span><span style="font-weight: bold; color: #33d6e5">    injected_cl *                   </span><span style="font-weight: bold; color: #ffffff">  </span><span style="font-weight: bold; color: #d338d3">        </span><span style="font-weight: bold; color: #ffffff">  </span><span style="font-weight: bold; color: #d338d3">         </span><span style="font-weight: bold; color: #ffffff">
+</span><span style="font-weight: bold; color: #19c518"></span><span style="color: #19c518">      subfeature                    </span><span style="color: #ffffff">[ </span><span style="color: #d338d3">ahead 2 </span><span style="color: #ffffff">| </span><span style="color: #d338d3">behind 1 </span><span style="color: #ffffff">]
+</span><span style="color: #19c518"></span><span style="color: #19c518">        nested_cl                   </span><span style="color: #ffffff">  </span><span style="color: #d338d3">        </span><span style="color: #ffffff">  </span><span style="color: #d338d3">         </span><span style="color: #ffffff">
+</span><span style="color: #19c518"></span><span style="color: #19c518">  fixit                             </span><span style="color: #ffffff">[ </span><span style="color: #d338d3">ahead 2 </span><span style="color: #ffffff">  </span><span style="color: #d338d3">         </span><span style="color: #ffffff">]
+</span><span style="color: #19c518"></span><span style="color: #19c518">    frozen_branch                   </span><span style="color: #ffffff">[ </span><span style="color: #d338d3">ahead 3 </span><span style="color: #ffffff">  </span><span style="color: #d338d3">         </span><span style="color: #ffffff">]
 </span><span style="color: #19c518"></span><span style="color: #19c518">  independent_cl                    </span><span style="color: #ffffff">[ </span><span style="color: #d338d3">ahead 1 </span><span style="color: #ffffff">  </span><span style="color: #d338d3">         </span><span style="color: #ffffff">]</span>
 </code></pre></div></div><p><div class="paragraph"></p></div>
 <div class="olist arabic"><ol class="arabic">
 <li>
 <p>
-Note that both branches are cyan because they are currently the same
+Note that these branches are cyan because they are currently the same
 <em>commit</em> object. See <a href="git-map-branches.html">git-map-branches(1)</a> for more detail.
 </p>
 </li>
@@ -926,7 +959,7 @@ by checking out the <a href="https://chromium.googlesource.com/chromium/tools/de
 <div id="footnotes"><hr /></div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2020-08-10 17:51:13 CEST
+Last updated 2021-01-25 15:02:46 PST
 </div>
 </div>
 </body>

man/man1/git-new-branch.1

@@ -36,6 +36,7 @@ git-new-branch \- Create a new branch with correct tracking information\&.
 \fIgit new\-branch\fR \-\-upstream_current <branch_name>
 \fIgit new\-branch\fR \-\-upstream <REF> <branch_name>
 \fIgit new\-branch\fR \-\-lkgr <branch_name>
+\fIgit new\-branch\fR \-\-inject_current <branch_name>
 .fi
 .sp
 .SH "DESCRIPTION"
@@ -61,6 +62,17 @@ Alias for
 \-\-upstream lkgr\&.
 .RE
 .PP
+\-\-inject_current
+.RS 4
+Set the tracking (upstream) branch of the newly\-created branch to the tracking (upstream) branch of the currently\-checked\-out branch and set the tracking (upstream) branch of the currently\-checked\-out branch to the newly\-created branch\&.
+.RE
+.RS 4
+Before: current > upstream
+.RE
+.RS 4
+After: current > new > upstream
+.RE
+.PP
 <branch_name>
 .RS 4
 The name for the new branch\&.
@@ -122,6 +134,22 @@ origin/master
   fixit                             [ ahead 2            ]
     frozen_branch                   [ ahead 3            ]
   independent_cl                    [ ahead 1            ]
+\fB$ git checkout subfeature\fR
+Switched to branch \*(Aqsubfeature\*(Aq
+Your branch and \*(Aqcool_feature\*(Aq have diverged,
+and have 2 and 1 different commits each, respectively\&.
+  (use "git pull" to merge the remote branch into yours)
+\fB$ git new\-branch \-\-inject_current injected_cl\fR
+\fB$ git map\-branches \-v\fR
+origin/master
+\fB  cool_feature                      [ ahead 4            ]  \fR\fB\fB(1)\fR\fR\fB
+    cl_depends_on_cool_feature
+    injected_cl *
+\fR      subfeature                    [ ahead 2 | behind 1 ]
+        nested_cl
+  fixit                             [ ahead 2            ]
+    frozen_branch                   [ ahead 3            ]
+  independent_cl                    [ ahead 1            ]
 .fi
 .if n \{\
 .RE
@@ -137,7 +165,7 @@ origin/master
 .sp -1
 .IP "  1." 4.2
 .\}
-Note that both branches are cyan because they are currently the same
+Note that these branches are cyan because they are currently the same
 \fIcommit\fR
 object\&. See
 \fBgit-map-branches\fR(1)

man/src/git-new-branch.demo.1.sh

@@ -15,3 +15,6 @@ run git map-branches -v
 run git checkout cool_feature 2>&1
 run git new-branch --upstream_current cl_depends_on_cool_feature
 run git map-branches -v
+run git checkout subfeature
+run git new-branch --inject_current injected_cl
+run git map-branches -v

man/src/git-new-branch.txt

@@ -13,6 +13,7 @@ SYNOPSIS
 'git new-branch' --upstream_current <branch_name>
 'git new-branch' --upstream <REF> <branch_name>
 'git new-branch' --lkgr <branch_name>
+'git new-branch' --inject_current <branch_name>
 
 DESCRIPTION
 -----------
@@ -41,6 +42,15 @@ OPTIONS
 --lkgr::
   Alias for `--upstream lkgr`.
 
+--inject_current::
+  Set the tracking (upstream) branch of the newly-created branch to the
+  tracking (upstream) branch of the currently-checked-out branch and set the
+  tracking (upstream) branch of the currently-checked-out branch to the
+  newly-created branch.
+
+  Before: current > upstream
+  After: current > new > upstream
+
 <branch_name>::
   The name for the new branch.
 
@@ -59,7 +69,7 @@ EXAMPLE
 -------
 demo:1[]
 
-1. Note that both branches are cyan because they are currently the same
+1. Note that these branches are cyan because they are currently the same
 'commit' object. See linkgit:git-map-branches[1] for more detail.
 
 include::_aliases.txt[]