Enhance scaladoc-diff tool for Ubuntu.

Tested on Ubuntu 14.04.3 LTS.

SUMMARY

   1. Use `set -e` to ensure ant failure bails script.
   2. Make best effort to display scaladoc build diff.
   3. Quiet output from git checkout.
   4. Prefer plumbing over porcelain when getting hashes.
   5. Use short hashes to enhance output readability.
   6. Use branch name when available.
   7. Ensure scaladoc copies are clean.
   8. Remove redundant use of scaladoc-compare.
   9. Improve message formatting.
  10. Use $(...) instead of backticks for more legible code.
  11. Pause after reporting missing old file.
  12. Report missing new files.

DETAILS

1. Use `set -e` to ensure an ant failure bails the script. Turn off before
diff because diff returns an error code when the compared files differ,
which is expected to be seen.

2. Make best effort to display scaladoc build diff preferring graphical
clients.

opendiff is a Mac OS X command that opens a graphical diff display, meld
is a graphical client for Ubuntu and other distros. On Ubuntu fallback to
gvimdiff which will display graphically if possible otherwise in the
console. Ultimately default to diff.

Command detection taken from,

  http://stackoverflow.com/questions/592620/check-if-a-program-exists-from-a-bash-script

3. Quiet output from git checkout to avoid detached head warning.

The user does not need to see the detached head warning when running this.

4. Prefer plumbing over porcelain to avoid 'not found' error when getting
SHA1s.

Calling get-scala-commit-sha errors out on Ubuntu 14.04.3 with
Bash 4.3.11 with these messages,

    tools/get-scala-commit-sha: 11: tools/get-scala-commit-sha: [[: not found
    tools/get-scala-commit-sha: 17: tools/get-scala-commit-sha: Bad substitution

5. Use short hashes to enhance output readability.

6. Use branch name when available.

If the branch name is not used when the working directory is restored
after checkout out the parent commit we will be in a detached HEAD
state. Make a best effort to avoid that.

7. Ensure scaladoc copies are clean.

Remove previous copy of scaladoc to ensure consistent behaviour on runs
past the first.

8. Remove use of scaladoc-compare because the equivalent functionality is
provided when iterating the new files.

9. Improve message formatting.

10. Use $(...) instead of backticks for more legible code.

11. Pause after reporting missing old file.

Without this pause it was easy to miss the message when we had this
sequence of differences,

 * differing files
 * missing file
 * differing files

12. Report missing new files.

Along with reporting new files with no corresponding old file report the
complementary scenario.

1 files changed, 73 insertions, 27 deletions

diff --git a/tools/scaladoc-diff b/tools/scaladoc-diff
index 64dc025ecd..df0d1f3335 100755
--- a/tools/scaladoc-diff
+++ b/tools/scaladoc-diff
@@ -4,68 +4,114 @@
 # of the parent commit. No arguments.
 #
 
+set -e
 
-oldsha=$(git log -1 --format="%H" HEAD^)
-oldsha=${oldsha#g}
-oldsha=${oldsha:0:10}
+# opendiff for Mac OS X, meld for Ubuntu then default to other commands.
+displaydiff() {
+  case "$(uname -s)" in
 
-sha=`sh tools/get-scala-commit-sha`
-echo "parent commit sha: $oldsha. current commit sha: $sha"
+    Darwin)
+      if hash opendiff 2>/dev/null; then
+        echo opendiff "$@"
+        opendiff "$@"
+      else
+        echo diff "$@"
+        diff -y "$@" | less -N
+      fi
+    ;;
+
+    *)
+      if hash meld 2>/dev/null; then
+        echo meld "$@"
+        meld "$@"
+      elif hash gvimdiff 2>/dev/null; then
+        echo gvimdiff "$@"
+        gvimdiff "$@"
+      else
+        echo diff "$@"
+        diff -y "$@" | less -N
+      fi
+    ;;
+  esac
+}
+
+oldsha=$(git rev-parse --short HEAD^)
+
+# Use branch name defaulting to SHA1 when not available for example when in
+# detached HEAD state.
+sha=$(git symbolic-ref -q --short HEAD || git rev-parse --short HEAD)
+
+echo "parent commit sha  : $oldsha"
+echo "current commit sha : $sha"
 
 # create scaladoc for parent commit if not done already
 if [ ! -f "build/scaladoc-output-$oldsha.txt" ]
 then
   echo "making scaladoc for parent commit ($oldsha)"
-  git checkout HEAD^
+  git checkout -q $oldsha
   ant docs.lib -Dscaladoc.raw.output='yes' > build/scaladoc-output-$oldsha.txt
-  cp -r build/scaladoc/ build/scaladoc-${oldsha}
-  git checkout $sha
+  rm -rf build/scaladoc-${oldsha}
+  mv build/scaladoc build/scaladoc-${oldsha}
+  git checkout -q $sha
 fi
 
 # create scaladoc for current commit
 echo "making scaladoc for current commit ($sha)"
 ant docs.lib -Dscaladoc.raw.output='yes' > build/scaladoc-output-$sha.txt
-cp -r build/scaladoc/ build/scaladoc-${sha}
-echo "opendiff build/scaladoc-output-$oldsha.txt build/scaladoc-output-$sha.txt"
-opendiff build/scaladoc-output-$oldsha.txt build/scaladoc-output-$sha.txt
+rm -rf build/scaladoc-${sha}
+mv build/scaladoc build/scaladoc-${sha}
 
-echo "Comparing files..."
+# Allow script to continue when diff results in -1
+set +e
 
-difffile=build/scaladoc-diff-${sha}-$oldsha.txt
-sh tools/scaladoc-compare build/scaladoc-${sha}/ build/scaladoc-$oldsha/ &> $difffile
-open $difffile &
+displaydiff build/scaladoc-output-$oldsha.txt build/scaladoc-output-$sha.txt
 
 # Adapted from tools/scaladoc-compare
-echo "Comparing versions with difftool: build/scaladoc-${sha}/ build/scaladoc-$oldsha/"
+echo "Comparing versions with diff: build/scaladoc-${sha}/ build/scaladoc-$oldsha/"
 NEW_PATH=build/scaladoc-${sha}/
 OLD_PATH=build/scaladoc-$oldsha/
 
-FILES=`find $NEW_PATH -name '*.html.raw'`
-if [ "$FILES" == "" ]
+
+NEWFILES=$(find $NEW_PATH -name '*.html.raw')
+if [ "$NEWFILES" == "" ]
 then
   echo "No .html.raw files found in $NEW_PATH!"
   exit 1
 fi
 
-for NEW_FILE in $FILES
+for NEW_FILE in $NEWFILES
 do
   OLD_FILE=${NEW_FILE/$NEW_PATH/$OLD_PATH}
   if [ -f $OLD_FILE ]
   then
-    DIFF=`diff -q -w $NEW_FILE $OLD_FILE 2>&1`
+    DIFF=$(diff -q -w $NEW_FILE $OLD_FILE 2>&1)
     if [ "$DIFF" != "" ]
     then
-      opendiff $OLD_FILE $NEW_FILE > /dev/null
+      displaydiff $OLD_FILE $NEW_FILE > /dev/null
+
       echo "next [y\N]? "
       read -n 1 -s input
-
-      if [ "$input" == "N" ]
-      then exit 0
-      fi
+      if [ "$input" == "N" ]; then exit 0; fi
     fi
   else
-    echo -e "$NEW_FILE: No corresponding file (expecting $OLD_FILE)\n\n"
+    echo
+    echo "New file:                 : $NEW_FILE"
+    echo "No corresponding old file : $OLD_FILE"
+
+    echo "next [y\N]? "
+    read -n 1 -s input
+    if [ "$input" == "N" ]; then exit 0; fi
   fi
 done
 
-echo "Done."
+OLDFILES=$(find $OLD_PATH -name '*.html.raw')
+for OLD_FILE in $OLDFILES
+do
+  NEW_FILE=${OLD_FILE/$OLD_PATH/$NEW_PATH}
+  if [ ! -f $NEW_FILE ]
+  then
+    echo
+    echo "Old file:                 : $OLD_FILE"
+    echo "No corresponding new file : $NEW_FILE"
+  fi
+done