Fix minor regression in git_upstream_diff.

89734301 introduced a new useful feature
to `git upstream-diff`, but unfortunately also regressed the behavior
of the tool when used with additional arguments for `git diff`.

This adds some additional documentation to demonstrate the intended
original feature (and fixes some of the bit-rot in the documentation
pipeline).

R=agable@chromium.org, mattm@chromium.org

Change-Id: I3ae48db3232c1ac84a7edbfe2225a17cda391a1e
Reviewed-on: https://chromium-review.googlesource.com/1107491
Commit-Queue: Robbie Iannucci <iannucci@chromium.org>
Reviewed-by: Aaron Gable <agable@chromium.org>

git_upstream_diff.py

@@ -21,10 +21,15 @@ def main(args):
                       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')
+  parser.add_argument('--branch', default=current_branch,
+                      help='Show changes from a different branch. Passing '
+                           '"HEAD" is the same as omitting this option (it '
+                           'diffs against the current branch)')
   opts, extra_args = parser.parse_known_args(args)
 
+  if opts.branch == 'HEAD':
+    opts.branch = current_branch
+
   if not opts.branch or opts.branch == 'HEAD':
     print 'fatal: Cannot perform git-upstream-diff while not on a branch'
     return 1

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] [branch] [&lt;extra args for git-diff&gt;*]</pre>
+<pre class="content"><em>git upstream-diff</em> [--wordwise] [--branch branch] [&lt;extra args for git-diff&gt;*]</pre>
 <div class="attribution">
 </div></div>
 </div>
@@ -763,7 +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 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="paragraph"><p>Shows a diff between a branch and its upstream. If the --branch option is
+omitted or "HEAD", the tool shows the diff for the current branch. Any
+additional arguments are passed through to the underlying git-diff command. This
+is <em>roughly</em> the same as:</p></div>
 <div class="listingblock">
 <div class="content">
 <pre><code>git diff --patience -C -C branch@{upstream}  <b>&lt;1&gt;</b> <b>&lt;2&gt;</b></code></pre>
@@ -789,6 +792,20 @@ you&#8217;ll still see an accurate diff compared to just diffing against
 <div class="paragraph"><p>The <code>--wordwise</code> option also allows <code>git-diff</code> to do word-by-word comparison
 in a semi-intelligent way. However, sometimes it can produce surprising results,
 so it is disabled by default.</p></div>
+<div class="paragraph"><p>Since any additional options are passed through to git-diff unchanged, you can
+use this as a general replacement for <code>git diff</code> for things like:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>$ # See what changed in a file on the current branch
+$ git upstream-diff some/file.py
+...
+
+$ # Omit deleted files from the diff
+$ git upstream-diff --diff-filter d
+...
+
+$ # etc.</code></pre>
+</div></div>
 </div>
 </div>
 <div class="sect1">
@@ -895,7 +912,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-11-03 14:35:37 PDT
+Last updated 2018-06-20 00:12:01 PDT
 </div>
 </div>
 </body>

man/man1/git-upstream-diff.1

 '\" t
 .\"     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: 11/03/2017
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      Date: 06/20/2018
 .\"    Manual: Chromium depot_tools Manual
-.\"    Source: depot_tools 9c2758a5
+.\"    Source: depot_tools 79d42dfb
 .\"  Language: English
 .\"
-.TH "GIT\-UPSTREAM\-DIFF" "1" "11/03/2017" "depot_tools 9c2758a5" "Chromium depot_tools Manual"
+.TH "GIT\-UPSTREAM\-DIFF" "1" "06/20/2018" "depot_tools 79d42dfb" "Chromium depot_tools Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -32,12 +32,12 @@ git-upstream-diff \- Print a diff of the current branch, compared to its upstrea
 .SH "SYNOPSIS"
 .sp
 .nf
-\fIgit upstream\-diff\fR [\-\-wordwise] [branch] [<extra args for git\-diff>*]
+\fIgit upstream\-diff\fR [\-\-wordwise] [\-\-branch branch] [<extra args for git\-diff>*]
 .fi
 .sp
 .SH "DESCRIPTION"
 .sp
-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:
+Shows a diff between a branch and its upstream\&. If the \-\-branch option is omitted or "HEAD", the tool shows the diff for the current branch\&. Any additional arguments are passed through to the underlying git\-diff command\&. This is \fIroughly\fR the same as:
 .sp
 .if n \{\
 .RS 4
@@ -60,6 +60,27 @@ uses the patience\-diff algorithm, which tends to produce nicer diffs in many ca
 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\&.
+.sp
+Since any additional options are passed through to git\-diff unchanged, you can use this as a general replacement for git diff for things like:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ # See what changed in a file on the current branch
+$ git upstream\-diff some/file\&.py
+\&.\&.\&.
+
+$ # Omit deleted files from the diff
+$ git upstream\-diff \-\-diff\-filter d
+\&.\&.\&.
+
+$ # etc\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
 .SH "OPTIONS"
 .PP
 \-\-wordwise

man/src/git-upstream-diff.txt

@@ -9,12 +9,15 @@ include::_git-upstream-diff_desc.helper.txt[]
 SYNOPSIS
 --------
 [verse]
-'git upstream-diff' [--wordwise] [branch] [<extra args for git-diff>*]
+'git upstream-diff' [--wordwise] [--branch branch] [<extra args for git-diff>*]
 
 DESCRIPTION
 -----------
 
-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:
+Shows a diff between a branch and its upstream. If the --branch option is
+omitted or "HEAD", the tool shows the diff for the current branch. Any
+additional arguments are passed through to the underlying git-diff command. This
+is 'roughly' the same as:
 
 ----
 git diff --patience -C -C branch@{upstream}  <1> <2>
@@ -33,6 +36,21 @@ 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.
 
+Since any additional options are passed through to git-diff unchanged, you can
+use this as a general replacement for `git diff` for things like:
+
+----
+$ # See what changed in a file on the current branch
+$ git upstream-diff some/file.py
+...
+
+$ # Omit deleted files from the diff
+$ git upstream-diff --diff-filter d
+...
+
+$ # etc.
+----
+
 
 OPTIONS
 -------
@@ -40,7 +58,7 @@ OPTIONS
 --wordwise::
   Print a colorized word-wise diff instead of a line-wise diff.
 
-[branch]
+--branch branch::
   Show a diff between the specified branch and its upstream, instead of using
   the current branch.
 

man/src/make_docs.sh

@@ -120,6 +120,12 @@ a
 .
 -1
 j
+/XMLTO_EXTRA
+a
+ --skip-validation
+.
+-1
+j
 /^\$(MAN_HTML):
 a
  asciidoc-override.css