Fix minor regression in git_upstream_diff.

89734301bcf8c5e1f774a861b2e15e859b846c1d 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>
diff --git a/git_upstream_diff.py b/git_upstream_diff.py
index 6e07c6d..72d1304 100755
--- a/git_upstream_diff.py
+++ b/git_upstream_diff.py
@@ -21,10 +21,15 @@
                       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