How should I set the PATH variable on my Mac so the Hombrew-installed tools are found?

I found this related post to be very helpful. Instead of changing the $PATH variable, it just has you simply edit your /etc/paths file.

Homebrew wants me to amend my PATH; no clue how

As soon as I followed the directions and put /usr/local/bin above /usr/bin, my issues were resolved.

1. On OS X, open Terminal
2. Type the command: sudo vi /etc/paths
3. Enter your password if you're asked for it
4. You will see a list of paths. Edit them so that /usr/local/bin path is entered above the /usr/bin path
5. *Save and quit
6. Restart Terminal

Here's what mine looks like after I did that:

/usr/local/bin
/usr/bin
/bin
/usr/sbin
/sbin

*To save and quit type a colon (:), then type wq (to write and quit at the same time), followed by Enter.

You can also open the /etc/paths file in a graphical text editor and edit it that way.

Credit to fengd over at Stack Overflow for his answer over there.

This answer is obsolete. The preferred Homebrew PATH ordering used to be as explained, but that is no longer true. However, the approach is more generally applicable, so for interest’s sake, I’m leaving it up.

---

You shouldn’t.

Homebrew intentionally keeps /usr/local/bin after /usr/bin in the path for maximum compatibility. Reversing the order of these directories in PATH by editing /etc/paths would mean that all programs anywhere on the system, no matter how they were started, will get the Homebrew version of a command. But some may specifically expect Apple’s version, or just not be able to use a newer version, etc.

How to preserve this principle and still get the Homebrew-installed version of git? As the saying goes, all problems can be solved with a layer of indirection (except having too many layers of indirection). — Or in this case, as it turns out, two layers.

Specifically, it’s been part of my Unix habits to have a ~/bin directory which I put at the start of my PATH. This is one of the first bits in my .bashrc:

[[ :$PATH: == *:$HOME/bin:* ]] || PATH=$HOME/bin:$PATH

This checks whether PATH contains ~/bin, and if not, prepends it. With that in place, then selectively making just the Homebrew-managed git take precedence over the system version (instead of every Homebrew-managed binary), and just for your shell sessions (instead of all programs started from anywhere, including GUI programs), is as simple as symlinking it:

ln -s /usr/local/bin/git ~/bin/git

You could symlink /usr/local/Cellar/git/1.8.2.1/bin/git directly, but then you would have to fix your symlink every time you did a brew upgrade git (directly or indirectly). By symlinking to Homebrew’s fixed-location symlink, you don’t have to worry about it.

So you add a directory to your $HOME so you can add it your PATH so you can symlink to a symlink, and that fixes your problem and puts a smile on Dr Seuss. Yo dawg I herd you like symlinks so we put a path in your PATH so you can symlink while you symlink.

You haven't done anything wrong, but it does seem pretty clear that if you had /usr/local/bin in your path before /usr/bin this specific problem would go away. The easiest fix is to do just that and put something like

export PATH=/usr/local/bin:$PATH

in your ~/.bash_profile so everything that Homebrew installs is found first. That's the way that I have it set up on my Mac, and it has worked for me for this long, however, YMMV.

It does appear that they believe it would work with /usr/local/bin being after /usr/bin, so while I might have mucked up my own $PATH, I can see where their documentation lacks:

Note that you should put /usr/local/bin after /usr/bin because some programs will expect to get the system version of, e.g., ruby, and break if they get the newer Homebrew version.

From Discrepancy between wiki & brew doctor #10738.  Note that this document goes on to say, "The FAQ (the above quote) refers to the PATH setting for GUI apps; the doctor (the advice to put /usr/local/bin ahead of /usr/bin in your PATH) refers to the PATH setting for CLI apps."