brew/share/man/man1/brew.1

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "BREW" "1" "September 2011" "Homebrew" "brew"
.
.SH "NAME"
\fBbrew\fR \- The missing package manager for OS X
.
.SH "SYNOPSIS"
\fBbrew\fR [\-\-verbose|\-v] command [options] [formula] \.\.\.
.
.br
\fBbrew\fR [\-\-version|\-v]
.
.SH "DESCRIPTION"
Homebrew is the easiest and most flexible way to install the UNIX tools Apple didn\'t include with OS X\.
.
.SH "OPTIONS"
.
.TP
\fB\-v\fR, \fB\-\-verbose\fR command [options] [formula] \.\.\.
Prints extra, command\-specific debugging information\. Note that \fBbrew \-v\fR by itself is the same as \fBbrew \-\-version\fR\.
.
.SH "ESSENTIAL COMMANDS"
For the full command list, see the COMMANDS section\.
.
.TP
\fBinstall\fR \fIformula\fR
Install \fIformula\fR\.
.
.TP
\fBremove\fR \fIformula\fR
Uninstall \fIformula\fR\.
.
.TP
\fBupdate\fR
Fetch the newest version of Homebrew from GitHub using \fBgit\fR(1)\.
.
.TP
\fBlist\fR
List all installed formulae\.
.
.TP
\fBsearch\fR, \fB\-S\fR \fItext\fR|/\fItext\fR/
Perform a substring search of formula names for \fItext\fR\. If \fItext\fR is surrounded with slashes, then it is interpreted as a regular expression\. If no search term is given, all available formula are displayed\.
.
.SH "COMMANDS"
.
.TP
\fBaudit [\-\-strict]\fR [\fIformulae\fR]
Check \fIformulae\fR for Homebrew coding style violations\. This should be run before submitting a new formula\.
.
.IP
If no \fIformulae\fR are provided, all of them are checked\.
.
.IP
If \fB\-\-strict\fR is passed, perform additional stricter checks that may not need to be fixed before submitting\.
.
.IP
\fBaudit\fR exits with a non\-zero status if any errors are found\. This is useful, for instance, for implementing pre\-commit hooks\.
.
.TP
\fBcat\fR \fIformula\fR
Display the source to \fIformula\fR\.
.
.TP
\fBcleanup [\-\-force]\fR [\fIformula\fR]
For all installed or specific formulae, remove any older versions from the cellar\. By default, does not remove out\-of\-date keg\-only brews, as other software may link directly to specific versions\.
.
.IP
If \fB\-\-force\fR is passed, remove out\-of\-date keg\-only brews as well\.
.
.TP
\fBcreate [\-\-no\-fetch]\fR \fIURL\fR
Generate a formula for the downloadable file at \fIURL\fR and opens it in $EDITOR\. Homebrew will attempt to automatically derive the formula name and version, if it fails, you\'ll have to make your own template\. I suggest copying wget\'s\.
.
.IP
If \fB\-\-no\-fetch\fR is passed, Homebrew will not download \fIURL\fR to the cache and will thus not add the MD5 to the formula for you\.
.
.TP
\fBdeps [\-\-1] [\-n]\fR \fIformula\fR
Show \fIformula\fR\'s dependencies\.
.
.IP
If \fB\-\-1\fR is passed, only show dependencies one level down, instead of recursing\.
.
.IP
If \fB\-n\fR is passed, shows dependencies in topological order\.
.
.TP
\fBdoctor\fR
Check your system for potential problems\.
.
.TP
\fBedit\fR
Open all of Homebrew for editing in TextMate\.
.
.TP
\fBedit\fR \fIformula\fR
Open \fIformula\fR in $EDITOR\.
.
.TP
\fBfetch [\-\-force] [\-v] [\-\-HEAD] [\-\-deps]\fR \fIformulae\fR
Download the source packages for the given \fIformulae\fR\. For tarballs, also print MD5 and SHA1 checksums\.
.
.IP
If \fB\-\-HEAD\fR is passed, download the HEAD versions of \fIformulae\fR instead\. \fB\-v\fR may also be passed to make the VCS checkout verbose, useful for seeing if an existing HEAD cache has been updated\.
.
.IP
If \fB\-\-force\fR is passed, remove a previously cached version and re\-fetch\.
.
.IP
If \fB\-\-deps\fR is passed, also download dependencies for any listed \fIformulae\fR\.
.
.TP
\fBhome\fR
Open Homebrew\'s own homepage in a browser\.
.
.TP
\fBhome\fR \fIformula\fR
Open \fIformula\fR\'s homepage in a browser\.
.
.TP
\fBinfo\fR \fIformula\fR
Display information about \fIformula\fR\.
.
.TP
\fBinfo \-\-github\fR \fIformula\fR
Open a browser to the GitHub History page for formula \fIformula\fR\.
.
.IP
To view formula history locally: \fBbrew log \-p <formula>\fR\.
.
.TP
\fBinfo\fR \fIURL\fR
Print the name and version that will be detected for \fIURL\fR\.
.
.TP
\fBinstall [\-\-force] [\-\-debug] [\-\-ignore\-dependencies] [\-\-use\-clang] [\-\-use\-gcc] [\-\-use\-llvm] [\-\-build\-from\-source] [\-\-HEAD]\fR \fIformula\fR
Install \fIformula\fR\.
.
.IP
\fIformula\fR is usually the name of the formula to install, but may also be the URL for an arbitrary formula\.
.
.IP
If \fB\-\-force\fR is passed, will install \fIformula\fR even if it is already installed\. This can be used to re\-install a formula without removing it first\.
.
.IP
If \fB\-\-debug\fR is passed and brewing fails, open a shell inside the temporary folder used for compiling\.
.
.IP
If \fB\-\-ignore\-dependencies\fR is passed, skip installing any dependencies of any kind\. If they are not already present, the formula will probably fail to install\.
.
.IP
If \fB\-\-use\-clang\fR is passed, attempt to compile using clang\.
.
.IP
If \fB\-\-use\-gcc\fR is passed, attempt to compile using GCC\. This is useful for systems whose default compiler is LLVM\-GCC\.
.
.IP
If \fB\-\-use\-llvm\fR is passed, attempt to compile using the LLVM front\-end to GCC\. \fINOTE\fR: Not all formulae will build with LLVM\.
.
.IP
If \fB\-\-build\-from\-source\fR is passed, compile from source even if a bottle is provided for \fIformula\fR\.
.
.IP
If \fB\-\-HEAD\fR is passed, and \fIformula\fR defines it, install the HEAD version, aka master, trunk, unstable, dev\.
.
.IP
To install a newer version of HEAD use \fBbrew rm <foo> && brew install \-\-HEAD <foo>\fR or \fBbrew install \-\-force \-\-HEAD <foo>\fR\.
.
.TP
\fBinstall \-\-interactive [\-\-git]\fR \fIformula\fR
Download and patch \fIformula\fR, then open a shell\. This allows the user to run \fB\./configure \-\-help\fR and otherwise determine how to turn the software package into a Homebrew formula\.
.
.IP
If \fB\-\-git\fR is passed, Homebrew will create a Git repository, useful for creating patches to the software\.
.
.TP
\fBln\fR, \fBlink\fR \fIformula\fR
Symlink all of \fIformula\fR\'s installed files into the Homebrew prefix\. This is done automatically when you install formula, but can be useful for DIY installations\.
.
.TP
\fBlist\fR
List all installed formulae\.
.
.TP
\fBlist\fR \fIformula\fR
List the installed files for \fIformula\fR\.
.
.TP
\fBlog [git\-log\-options]\fR \fIformula\fR \.\.\.
Show the git log for the given formulae\. Options that \fBgit\-log\fR(1) recognizes can be passed before the formula list\.
.
.TP
\fBman\fR
Regenerate this man page using \fBronn\fR \fIhttp://rtomayko\.github\.com/ronn/\fR\. See \fBman brew\-man\fR for details\.
.
.TP
\fBmissing\fR [\fIformulae\fR]
Check the given \fIformulae\fR for missing dependencies\.
.
.IP
If no \fIformulae\fR are given, check all installed brews\.
.
.TP
\fBoptions [\-\-compact] [\-\-all]\fR \fIformula\fR
Display install options specific to \fIformula\fR\.
.
.IP
If \fB\-\-compact\fR is passed, show all options on a single line separated by spaces\.
.
.IP
If \fB\-\-all\fR is passed, show options for all formulae\.
.
.TP
\fBoutdated [\-\-quiet]\fR
Show formulae that have an updated version available\.
.
.IP
If \fB\-\-quiet\fR is passed, list only the names of outdated brews\. Otherwise, the versions are printed as well\.
.
.TP
\fBprune\fR
Remove dead symlinks from the Homebrew prefix\. This is generally not needed, but can be useful when doing DIY installations\.
.
.TP
\fBrm\fR, \fBremove\fR, \fBuninstall [\-\-force]\fR \fIformula\fR
Uninstall \fIformula\fR\.
.
.IP
If \fB\-\-force\fR is passed, and there are multiple versions of \fIformula\fR installed, delete all installed versions\.
.
.TP
\fBsearch\fR, \fB\-S\fR \fItext\fR|/\fItext\fR/
Perform a substring search of formula names for \fItext\fR\. If \fItext\fR is surrounded with slashes, then it is interpreted as a regular expression\. If no search term is given, all available formula are displayed\.
.
.TP
\fBsearch \-\-macports\fR|\fB\-\-fink\fR \fItext\fR
Search for \fItext\fR on the MacPorts or Fink package search page\.
.
.TP
\fBserver\fR
Start a local web app that lets you browse available formulae, similar to \fBgem server\fR\. Requires \fBsinatra\fR \fIhttp://www\.sinatrarb\.com/\fR\.
.
.TP
\fBtest\fR \fIformula\fR
A few formulae provide a test method\. \fBbrew test <formula>\fR runs this test method\. There is no standard output or return code, but it should generally indicate to the user if something is wrong with the installed formula\.
.
.IP
Example: \fBbrew install jruby && brew test jruby\fR
.
.TP
\fBunlink\fR \fIformula\fR
Unsymlink \fIformula\fR from the Homebrew prefix\. This can be useful for temporarily disabling a formula: \fBbrew unlink foo && commands && brew link foo\fR\.
.
.TP
\fBupdate\fR
Fetch the newest version of Homebrew from GitHub using \fBgit\fR(1)\.
.
.TP
\fBupgrade\fR [\fIformulae\fR]
Upgrade outdated brews\.
.
.IP
If \fIformulae\fR are given, upgrade only the specified brews\.
.
.TP
\fBuses [\-\-installed]\fR \fIformula\fR
Show the formulas that specify \fIformula\fR as a dependency\. The list is not recursive; only one level of dependencies is resolved\.
.
.IP
If \fB\-\-installed\fR is passed, only lists installed formulae\.
.
.TP
\fBversions\fR \fIformulae\fR
List previous versions of \fIformulae\fR, along with a command to checkout each version\.
.
.TP
\fBwhich\fR [\fIformulae\fR]
List versions of installed brews\.
.
.IP
If \fIformulae\fR are given, only list versions for the specified brews\.
.
.TP
\fB\-\-cache\fR
Display Homebrew\'s download cache\. \fIDefault:\fR \fB~/Library/Cache/Homebrew\fR
.
.TP
\fB\-\-cache\fR \fIformula\fR
Display the file or folder used to cache \fIformula\fR\.
.
.TP
\fB\-\-cellar\fR
Display Homebrew\'s Cellar path\. \fIDefault:\fR \fB/usr/local/Cellar\fR
.
.TP
\fB\-\-cellar\fR \fIformula\fR
Display the location in the cellar where \fIformula\fR would be installed, without any sort of versioned folder as the last path\.
.
.TP
\fB\-\-config\fR
Show Homebrew and system configuration useful for debugging\. If you file a bug report, you will likely be asked for this information if you do not provide it\.
.
.TP
\fB\-\-prefix\fR
Display Homebrew\'s install path\. \fIDefault:\fR \fB/usr/local\fR
.
.TP
\fB\-\-prefix\fR \fIformula\fR
Display the location in the cellar where \fIformula\fR is or would be installed\.
.
.TP
\fB\-\-repository\fR
Display where Homebrew\'s \fB\.git\fR folder is located\. For standard installs, the \fBprefix\fR and \fBrepository\fR are the same folder\.
.
.TP
\fB\-v\fR, \fB\-\-version\fR
Print the version number of brew to standard error and exit\.
.
.SH "EXTERNAL COMMANDS"
Homebrew allows external commands to be defined by putting a +x file named \fBbrew\-<cmdname>\fR or \fBbrew\-<cmdname>\.rb\fR on the PATH\. This will cause Homebrew to recognize \fBbrew cmdname\fR\.
.
.P
Some sample commands ship with Homebrew and are enabled by default\.
.
.IP "" 4
.
.nf

$ ls `brew \-\-repository`/Library/Contributions/examples
.
.fi
.
.IP "" 0
.
.SH "ENVIRONMENT"
.
.TP
HOMEBREW_BUILD_FROM_SOURCE
If set, instructs Homebrew to compile from source even when a formula provides a bottle\.
.
.TP
HOMEBREW_CACHE
If set, instructs Homebrew to use the give folder as the download cache\. Otherwise, \fB~/Library/Caches/Homebrew\fR is used\.
.
.IP
This can be used to keep downloads out of your home folder, if you have it mounted on an SSD for instance\.
.
.TP
HOMEBREW_DEBUG
If set, instructs Homebrew to always assume \fB\-\-debug\fR when running commands\.
.
.TP
HOMEBREW_DEBUG_INSTALL
When \fBbrew install \-d\fR or \fBbrew install \-i\fR drops into a shell, \fBHOMEBREW_DEBUG_INSTALL\fR will be set to the name of the formula being brewed\.
.
.TP
HOMEBREW_DEBUG_PREFIX
When \fBbrew install \-d\fR or \fBbrew install \-i\fR drops into a shell, \fBHOMEBREW_DEBUG_PREFIX\fR will be set to the target prefix in the Cellar of the formula being brewed\.
.
.TP
HOMEBREW_EDITOR
If set, Homebrew will use this editor when editing a single formula, or several formulae in the same folder\.
.
.IP
\fINOTE\fR: \fBbrew edit\fR will open all of Homebrew as discontinuous files and folders\. TextMate can handle this correctly in project mode, but many editors will do strange things in this case\.
.
.TP
HOMEBREW_KEEP_INFO
If set, Homebrew will not remove files from \fBshare/info\fR, allowing them to be linked from the Cellar\.
.
.TP
HOMEBREW_MAKE_JOBS
If set, instructs Homebrew to use the value of \fBHOMEBREW_MAKE_JOBS\fR as the number of parallel jobs to run when building with \fBmake\fR(1)\.
.
.IP
\fIDefault:\fR the number of available CPU cores\.
.
.TP
HOMEBREW_SVN
When exporting from Subversion, Homebrew will use \fBHOMEBREW_SVN\fR if set, a Homebrew\-built Subversion if installed, or the system\-provided binary\.
.
.IP
Set this to force Homebrew to use a particular svn binary\.
.
.TP
HOMEBREW_TEMP
If set, instructs Homebrew to use \fBHOMEBREW_TEMP\fR as the temporary folder for building packages\. This may be needed if your system temp folder and Homebrew Prefix are on different volumes, as OS X has trouble moving symlinks across volumes when the target does not yet exist\.
.
.IP
This issue typically occurs when using FileVault or custom SSD configurations\.
.
.TP
HOMEBREW_USE_CLANG
If set, instructs Homebrew to compile using clang\.
.
.TP
HOMEBREW_USE_GCC
If set, instructs Homebrew to compile using gcc\.
.
.TP
HOMEBREW_USE_LLVM
If set, instructs Homebrew to compile using LLVM\.
.
.IP
\fINOTE\fR: Not all formulae build correctly with LLVM\.
.
.TP
HOMEBREW_VERBOSE
If set, instructs Homebrew to always assume \fB\-\-verbose\fR when running commands\.
.
.SH "USING HOMEBREW BEHIND A PROXY"
Homebrew uses several commands for downloading files (e\.g\. curl, git, svn)\. Many of these tools can download via a proxy\. It\'s common for these tools to read proxy parameters from environment variables\.
.
.P
For the majority of cases setting \fBhttp_proxy\fR is enough\. You can set this in your shell profile, or you can use it before a brew command:
.
.IP "" 4
.
.nf

http_proxy=http://<host>:<port> brew install foo
.
.fi
.
.IP "" 0
.
.P
If your proxy requires authentication:
.
.IP "" 4
.
.nf

http_proxy=http://<user>:<password>@<host>:<port> brew install foo
.
.fi
.
.IP "" 0
.
.SH "SEE ALSO"
Homebrew Wiki: \fIhttp://wiki\.github\.com/mxcl/homebrew/\fR
.
.P
\fBgit\fR(1), \fBgit\-log\fR(1)
.
.SH "AUTHORS"
Max Howell, a splendid chap\.
.
.SH "BUGS"
See Issues on GitHub: \fIhttp://github\.com/mxcl/homebrew/issues\fR