git-upstream-diff: add optional branch argument

Bug: 374928
Change-Id: I8f633ce172fc644e251193eb3fa4b67d62fb9dfa
Reviewed-on: https://chromium-review.googlesource.com/747365
Commit-Queue: Matt Mueller <mattm@chromium.org>
Reviewed-by: Aaron Gable <agable@chromium.org>

git_upstream_diff.py

@@ -14,27 +14,34 @@ def main(args):
   default_args = git.get_config_list('depot-tools.upstream-diff.default-args')
   args = default_args + args
 
+  current_branch = git.current_branch()
+
   parser = argparse.ArgumentParser()
   parser.add_argument('--wordwise', action='store_true', default=False,
                       help=(
                         'Print a colorized wordwise diff '
                         'instead of line-wise diff'))
+  parser.add_argument('branch', nargs='?', default=current_branch,
+                      help='Show changes from a different branch')
   opts, extra_args = parser.parse_known_args(args)
 
-  cur = git.current_branch()
-  if not cur or cur == 'HEAD':
+  if not opts.branch or opts.branch == 'HEAD':
     print 'fatal: Cannot perform git-upstream-diff while not on a branch'
     return 1
 
-  par = git.upstream(cur)
+  par = git.upstream(opts.branch)
   if not par:
-    print 'fatal: No upstream configured for branch \'%s\'' % cur
+    print 'fatal: No upstream configured for branch \'%s\'' % opts.branch
     return 1
 
   cmd = [git.GIT_EXE, 'diff', '--patience', '-C', '-C']
   if opts.wordwise:
     cmd += ['--word-diff=color', r'--word-diff-regex=(\w+|[^[:space:]])']
-  cmd += [git.get_or_create_merge_base(cur, par)]
+  cmd += [git.get_or_create_merge_base(opts.branch, par)]
+  # Only specify the end commit if it is not the current branch, this lets the
+  # diff include uncommitted changes when diffing the current branch.
+  if opts.branch != current_branch:
+    cmd += [opts.branch]
 
   cmd += extra_args
 

man/html/git-upstream-diff.html

@@ -755,7 +755,7 @@ git-upstream-diff(1) Manual Page
 <h2 id="_synopsis">SYNOPSIS</h2>
 <div class="sectionbody">
 <div class="verseblock">
-<pre class="content"><em>git upstream-diff</em> [--wordwise] [&lt;extra args for git-diff&gt;*]</pre>
+<pre class="content"><em>git upstream-diff</em> [--wordwise] [branch] [&lt;extra args for git-diff&gt;*]</pre>
 <div class="attribution">
 </div></div>
 </div>
@@ -763,11 +763,10 @@ git-upstream-diff(1) Manual Page
 <div class="sect1">
 <h2 id="_description">DESCRIPTION</h2>
 <div class="sectionbody">
-<div class="paragraph"><p>Shows a diff between your current branch and it&#8217;s upstream. This is <em>roughly</em> the
-same as:</p></div>
+<div class="paragraph"><p>Shows a diff between a branch and its upstream. If the branch is omitted, the tool shows the diff for the current branch. This is <em>roughly</em> the same as:</p></div>
 <div class="listingblock">
 <div class="content">
-<pre><code>git diff --patience -C -C HEAD@{upstream}  <b>&lt;1&gt;</b> <b>&lt;2&gt;</b></code></pre>
+<pre><code>git diff --patience -C -C branch@{upstream}  <b>&lt;1&gt;</b> <b>&lt;2&gt;</b></code></pre>
 </div></div>
 <div class="colist arabic"><ol>
 <li>
@@ -782,7 +781,7 @@ same as:</p></div>
 </p>
 </li>
 </ol></div>
-<div class="paragraph"><p>The difference is that <code>HEAD@{upstream}</code> is actually the tagged merge base of
+<div class="paragraph"><p>The difference is that <code>branch@{upstream}</code> is actually the tagged merge base of
 your branch (See <a href="git-rebase-update.html">git-rebase-update(1)</a>). This means that if your upstream
 branch was rebased, but you haven&#8217;t yet rebased the current branch on top of it,
 you&#8217;ll still see an accurate diff compared to just diffing against
@@ -803,6 +802,11 @@ so it is disabled by default.</p></div>
 <p>
   Print a colorized word-wise diff instead of a line-wise diff.
 </p>
+<div class="literalblock">
+<div class="content">
+<pre><code>Show a diff between the specified branch and its upstream, instead of using
+the current branch.</code></pre>
+</div></div>
 </dd>
 <dt class="hdlist1">
 &lt;extra args for git-diff&gt;
@@ -891,7 +895,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 2017-02-27 13:47:35 PST
+Last updated 2017-11-03 14:35:37 PDT
 </div>
 </div>
 </body>

man/man1/git-upstream-diff.1

@@ -2,12 +2,12 @@
 .\"     Title: git-upstream-diff
 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 02/27/2017
+.\"      Date: 11/03/2017
 .\"    Manual: Chromium depot_tools Manual
-.\"    Source: depot_tools a6ba28f5
+.\"    Source: depot_tools 9c2758a5
 .\"  Language: English
 .\"
-.TH "GIT\-UPSTREAM\-DIFF" "1" "02/27/2017" "depot_tools a6ba28f5" "Chromium depot_tools Manual"
+.TH "GIT\-UPSTREAM\-DIFF" "1" "11/03/2017" "depot_tools 9c2758a5" "Chromium depot_tools Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -32,18 +32,18 @@ git-upstream-diff \- Print a diff of the current branch, compared to its upstrea
 .SH "SYNOPSIS"
 .sp
 .nf
-\fIgit upstream\-diff\fR [\-\-wordwise] [<extra args for git\-diff>*]
+\fIgit upstream\-diff\fR [\-\-wordwise] [branch] [<extra args for git\-diff>*]
 .fi
 .sp
 .SH "DESCRIPTION"
 .sp
-Shows a diff between your current branch and it\(cqs upstream\&. This is \fIroughly\fR the same as:
+Shows a diff between a branch and its upstream\&. If the branch is omitted, the tool shows the diff for the current branch\&. This is \fIroughly\fR the same as:
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
-git diff \-\-patience \-C \-C HEAD@{upstream}  \fB(1)\fR \fB(2)\fR
+git diff \-\-patience \-C \-C branch@{upstream}  \fB(1)\fR \fB(2)\fR
 .fi
 .if n \{\
 .RE
@@ -57,7 +57,7 @@ detects file copies/renames
 uses the patience\-diff algorithm, which tends to produce nicer diffs in many cases\&.
 .br
 .sp
-The difference is that HEAD@{upstream} is actually the tagged merge base of your branch (See \fBgit-rebase-update\fR(1))\&. This means that if your upstream branch was rebased, but you haven\(cqt yet rebased the current branch on top of it, you\(cqll still see an accurate diff compared to just diffing against @{upstream}\&.
+The difference is that branch@{upstream} is actually the tagged merge base of your branch (See \fBgit-rebase-update\fR(1))\&. This means that if your upstream branch was rebased, but you haven\(cqt yet rebased the current branch on top of it, you\(cqll still see an accurate diff compared to just diffing against @{upstream}\&.
 .sp
 The \-\-wordwise option also allows git\-diff to do word\-by\-word comparison in a semi\-intelligent way\&. However, sometimes it can produce surprising results, so it is disabled by default\&.
 .SH "OPTIONS"
@@ -65,6 +65,17 @@ The \-\-wordwise option also allows git\-diff to do word\-by\-word comparison in
 \-\-wordwise
 .RS 4
 Print a colorized word\-wise diff instead of a line\-wise diff\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+Show a diff between the specified branch and its upstream, instead of using
+the current branch\&.
+.fi
+.if n \{\
+.RE
+.\}
 .RE
 .PP
 <extra args for git\-diff>

man/src/git-upstream-diff.txt

@@ -9,22 +9,21 @@ include::_git-upstream-diff_desc.helper.txt[]
 SYNOPSIS
 --------
 [verse]
-'git upstream-diff' [--wordwise] [<extra args for git-diff>*]
+'git upstream-diff' [--wordwise] [branch] [<extra args for git-diff>*]
 
 DESCRIPTION
 -----------
 
-Shows a diff between your current branch and it's upstream. This is 'roughly' the
-same as:
+Shows a diff between a branch and its upstream. If the branch is omitted, the tool shows the diff for the current branch. This is 'roughly' the same as:
 
 ----
-git diff --patience -C -C HEAD@{upstream}  <1> <2>
+git diff --patience -C -C branch@{upstream}  <1> <2>
 ----
 <1> `-C -C` detects file copies/renames
 <2> `--patience` uses the patience-diff algorithm, which tends to produce nicer
   diffs in many cases.
 
-The difference is that `HEAD@{upstream}` is actually the tagged merge base of
+The difference is that `branch@{upstream}` is actually the tagged merge base of
 your branch (See linkgit:git-rebase-update[1]). This means that if your upstream
 branch was rebased, but you haven't yet rebased the current branch on top of it,
 you'll still see an accurate diff compared to just diffing against
@@ -41,6 +40,10 @@ OPTIONS
 --wordwise::
   Print a colorized word-wise diff instead of a line-wise diff.
 
+[branch]
+  Show a diff between the specified branch and its upstream, instead of using
+  the current branch.
+
 <extra args for git-diff>::
   Extra arguments are included in the invocation of linkgit:git-diff[1]. These
   can be anything that `git-diff` normally takes.