How to fix: brew update files overwritten by merge

Sometimes when you run:

brew update

You get an error:

brew update the following untracked working tree files would be overwritten by merge

According to the repo wiki for Homebrew this is caused by an old bug in update that has long since been fixed.

Basically you have changed (uncommitted) files in your Homebrew working directory that you need to deal with. You simply need to reset the working directory so your update command can pull the latest files. If you’re familiar with git – then this will all make sense, if not, just run these 3 commands and your Homebrew will be fixed!

cd /usr/local
git fetch origin
git reset --hard origin/master

How to install and use Homebrew

Updated for OS X 10.10 Yosemite! Should work on OS X 10.9 Mavericks too.

If you’re doing any Ruby on Rails or other open source development on your Mac, you’re going to need Homebrew.

What is Homebrew?

Homebrew is a package management system for your Mac. Homebrew makes it easy to install the software you generally need for Ruby on Rails development. Sometimes when you install RubyGems for your project, they will be dependent on software being installed on your Mac. One of the more obvious examples would be a MySQL gem and the actual MySQL Database Server. You install the MySQL Database Server using Homebrew! One of the less obvious examples would be the Nokogiri gem. This gem uses a software package named libxml2. You would install the libxml2 software package using Homebrew in order to install the Nokogiri RubyGem.

So how do you install Homebrew?

Installing Homebrew is dead simple. However, it does have a rather large dependency. You will need the command line tools addon of Xcode installed. Xcode is made by Apple and its used to write Mac and iOS applications. Xcode is free and all you need to do is search for it on the Mac App Store and click install. Its a rather large application, so it may take a while to download and install.

Once you’ve finished installing Xcode, you will need to install the command line tools.

Installing Command Line Tools on older versions of Xcode

You will need to open Xcode and choose Xcode -> Preferences. Choose the Downloads tab and install the Command Line Tools. If you don’t see any of this in Preferences, then read the next section…

Xcode Command Line Tools

This will take some time, but when its done your Mac will be ready to install Homebrew!

Install Command Line Tools on the latest version of Xcode

Open up a Terminal window. If you aren’t doing that by using Spotlight (which is how you should open ALL your Mac apps) then you do that by pressing CMD + SPACE, then searching ‘Terminal’. Hit Enter.

Inside the terminal window type:

xcode-select --install

If you see the message:

xcode-select: error: command line tools are already installed, use "Software Update" to install updates

Then you already have the command line tools installed, otherwise, a dialog box will popup prompting you to install the command line tools. Go ahead and install them.

When the installation is complete you should be able to run:

xcode-select -p

That should output:


Installing Homebrew

Now that you have the Command Line Tools for Xcode installed, its time to install Homebrew. Remember I said it was easy… well it is.

If you visit the Homebrew website, you will see the following command:

ruby -e "$(curl -fsSL"

This command will need to be run in the OS X Terminal App. This means copy and pasting it into the Terminal window and pressing ENTER.

When the command is complete you should be able to run the following command in the Terminal window:

brew --version

If this works, then Homebrew is installed!

Now let’s go over a few common tasks you will have with Homebrew.

brew doctor

You want to use this command after system changes (such as OS X or Xcode updates) or if you think you need to troubleshoot your Homebrew installation. The output will tell you what’s wrong and generally how to fix it.

brew update

This will update your Homebrew formula list. Note, this doesn’t update all your installed packages! What this does is update the versions and availability of packages you could install. You want to run this often to keep your Homebrew installation up to date with the latest available software.

brew upgrade

This will upgrade your installed packages.

brew search [insert search term here]

This command will search the possible packages so you can find the one you want

brew install [insert package name here]

This will install a software package onto your system.

brew list

This will list all the packages that are currently installed on your system.

brew info [insert package name here]

Sometimes after you install a package, you get a screenful of information or configuration steps. If you’re like me, you will probably blow right past that and keep working – then it will dawn on you that you probably should have read some of that stuff. This will let you go back and do that.

brew uninstall [insert package name here]

And finally, you may want to remove a package you previously installed. That’s what this is for.

So that’s a quick intro to Homebrew and how you can manage software dependencies for RubyGems on your Mac!