Bug Fixing Checklist

PLEASE,
PLEASE,
PLEASE brew doctor BEFORE CREATING A TICKET!

Thank you!

1) Check for Common Issues

• brew update — then try again.
• brew doctor — the doctor diagnoses common issues.
• Try using the old environment, e.g. brew install --env=std graphviz.
• If you’re installing something Java orientated, maybe you need the [Java Developer Update][Apple Connect]?
• Check Xcode and/or the “Command Line Tools for Xcode” (CLT) are the latest versions [^1]
• If things fail with permissions errors you should check the permissions in /usr/local. If you’re unsure what to do, you can:

sudo chown -R $(whoami) /usr/local /usr/local/.git

But really you should know what you’re doing.

• Read the Common Issues

[^1]: brew --config will list these versions. If you have Xcode installed, check the App Store for upgrades and in Preferences for CLT upgrades. If you only have the CLT installed, then check [Apple Connect][].

Listen to Dr. Brew

• Completely remove Macports and Fink. Yes, for serious. Build scripts may do funky things if these exist in parallel with Homebrew. You can just rename their root folders. That’s enough.
• Update your Xcode and Command Line Tools for Xcode! Make sure that Xcode is up-to-date in the App Store. Check the CLT package is up-to-date (either via Xcode, Preferences or at [Apple Connect][]).
• If brew doctor warns about unbrewed dylibs, these seriously cause build trouble. Yes, we know it’s hard to know what to do with this warning. But it’s hard to advise!

2) Ticket the Bug

• Create a new gist (storage for a larger set of text) to contain the following items.
• Add the output from:

HOMEBREW_MAKE_JOBS=1 VERBOSE=1 brew install foo

• Add the output from:

brew doctor

• If the build failed during configure, paste the log: cat ~/Library/Logs/Homebrew/config.log | pbcopy
• File an issue with a link to your gist. Be sure to post the http: link (copy from the browser bar :P), not the git: link.

An easy way to copy the output from commands is to clear your terminal (⌘K) and then run the command. Then select-all (⌘A) and copy (⌘C).

It can be helpful if you try to post the error message (and the link to your gist) in the ticket. Please don’t post more than a few lines of output in the ticket! If unsure, just link to your gist.

If you post output in the ticket itself, put it in a triple-backtick-block, like so:

```sh
Build output goes here!

We all suck at writing bug reports. [Let’s get better together](http://allanmcrae.com/2011/05/how-to-file-a-bug-report/).

[Apple Connect]:http://connect.apple.com