Don't require/recommend ownership of /usr/local.

Apple reset this on every OS X major (and some minor) updates and it
always proves a painful and unnecessary step. Instead just check the
directories we actually care about are writable.

This may mean if these directories do not already exist (although they
are now created by the installed) that `brew link` will fail and require
manual intervention but this seems to be superior for both new and the
majority of existing users.

Library/Homebrew/cmd/update.sh

@@ -341,12 +341,13 @@ EOS
   fi
 
   # check permissions
-  if [[ "$HOMEBREW_PREFIX" = "/usr/local" && ! -w /usr/local ]]
+  if [[ -e "$HOMEBREW_CELLAR" && ! -w "$HOMEBREW_CELLAR" ]]
   then
     odie <<EOS
-/usr/local is not writable. You should change the ownership
+$HOMEBREW_CELLAR is not writable. You should change the
-and permissions of /usr/local back to your user account:
+ownership and permissions of $HOMEBREW_CELLAR back to your
-  sudo chown -R \$(whoami) /usr/local
+user account:
+  sudo chown -R \$(whoami) $HOMEBREW_CELLAR
 EOS
   fi
 

Library/Homebrew/diagnostic.rb

@@ -324,21 +324,37 @@ module Homebrew
         EOS
       end
 
-      def check_access_usr_local
+      def check_access_homebrew_cellar
-        return unless HOMEBREW_PREFIX.to_s == "/usr/local"
+        return if HOMEBREW_CELLAR.writable_real?
-        return if HOMEBREW_PREFIX.writable_real?
 
         <<-EOS.undent
-          /usr/local is not writable.
+          #{HOMEBREW_CELLAR} is not writable.
-          Even if this directory was writable when you installed Homebrew, other
-          software may change permissions on this directory. For example, upgrading
-          to OS X El Capitan has been known to do this. Some versions of the
-          "InstantOn" component of Airfoil or running Cocktail cleanup/optimizations
-          are known to do this as well.
 
-          You should change the ownership and permissions of /usr/local back to
+          You should change the ownership and permissions of #{HOMEBREW_CELLAR}
-          your user account.
+          back to your user account.
-            sudo chown -R $(whoami) /usr/local
+            sudo chown -R $(whoami) #{HOMEBREW_CELLAR}
+        EOS
+      end
+
+      def check_access_top_level_directories
+        not_writable_dirs = []
+
+        (Keg::TOP_LEVEL_DIRECTORIES + ["opt"]).each do |dir|
+          path = HOMEBREW_PREFIX/dir
+          next unless path.exist?
+          next if path.writable_real?
+          not_writable_dirs << path
+        end
+
+        return if not_writable_dirs.empty?
+
+        <<-EOS.undent
+          The following directories are not writable:
+          #{not_writable_dirs.join("\n")}
+
+          You should change the ownership and permissions of these directories.
+          back to your user account.
+            sudo chown -R $(whoami) #{not_writable_dirs.join(" ")}
         EOS
       end
 

share/doc/homebrew/Troubleshooting.md

@@ -13,7 +13,7 @@ brew gist-logs <formula>
 * Read through the [Common Issues](Common-Issues.md).
 * If you’re installing something Java-related, maybe you need to install Java (`brew cask install java`)?
 * Check that **Command Line Tools for Xcode (CLT)** and/or **Xcode** are up to date.
-* If things fail with permissions errors, check the permissions in `/usr/local`. If you’re unsure what to do, you can `sudo chown -R $(whoami) /usr/local`.
+* If things fail with permissions errors, check the permissions of `/usr/local`'s subdirectories. If you’re unsure what to do, you can `cd /usr/local && sudo chown -R $(whoami) bin etc include lib sbin share var Frameworks`.
 
 ## Check to see if the issue has been reported
 * Check the [issue tracker](https://github.com/Homebrew/homebrew-core/issues) to see if someone else has already reported the same issue.