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.