Fix minor regression in git_upstream_diff.

89734301bc 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