External Commands

Homebrew, like Git, supports external commands. This lets you create new commands that can be run like:

$ brew mycommand --option1 --option3 formula

without modifying Homebrew's internals.

COMMAND TYPES

External commands come in two flavors: Ruby commands and shell scripts.

In both cases, the command file should be chmod +x (executable) and live somewhere in $PATH.

Internally, Homebrew finds commands with which(1).

RUBY COMMANDS

An external command foo implemented as a Ruby command should be named brew-foo.rb. The command is executed by doing a require on the full pathname. As the command is required, it has full access to the Homebrew "environment", i.e. all global variables and modules that any internal command has access to.

The command may Kernel.exit with a status code if it needs to; if it doesn't explicitly exit then Homebrew will return 0.

SHELL SCRIPTS

A shell script for an command named foo should be named brew-foo. This file will be run via exec with some Homebrew variables set as environmental variables, and passed any additional command-line arguments.

Variable	Description
HOMEBREW_CACHE	Where Homebrew caches downloaded tarballs to, typically ~/Library/Caches/Homebrew.
HOMEBREW_CELLAR	The location of the Homebrew Cellar, where software is staged.
HOMEBREW_LIBRARY_PATH	The directory containing Homebrew’s own application code.
HOMEBREW_PREFIX	Where Homebrew installs software to, usually /usr/local.
HOMEBREW_REPOSITORY	If installed from a Git clone, the repo directory (i.e., where Homebrew’s .git directory lives).

Note that the script itself can use any suitable shebang (#!) line, so an external “shell script” can be written for sh, bash, Ruby, or anything else.

EXAMPLE COMMANDS

Some example external commands ship with Homebrew and are enabled by default. You can list them by doing

$ ls `brew --repository`/Library/Contributions/examples

Some commands in the example commands directory are documented in the brew(1) man page. For documentation on the missing, server, and which commands, see man brew.

bottle <formulae>

Build a binary package (bottle) from the keg(s) of <formulae>.

dirty

Like brew list --versions, but lists only formulae with multiple installed versions.

graph [brew-deps-options]

Generate a GraphViz DOT file from the Homebrew dependency graph. Options given here are passed on to brew deps.

grep [grep-options]

Grep through Homebrew formulae in HOMEBREW_REPOSITORY/Library/Formula. Options given here are passed on to grep(1).

leaves

List all installed formulae that are not dependencies of other installed formulae.

linkapps

Link any Mac OS X applications (###.app) found in the kegs of installed formulae into ~/Applications.

man [--verbose|-v] [--link|-l] [--server|-s]

[Re]generate man pages for Homebrew using ronn(1).

If --verbose is passed, run man brew after generating man pages.

If --link is passed, symlink generated man pages to HOMEBREW_PREFIX/share/man. This is useful when Homebrew is not installed directly into /usr/local.

If --server is passed, start the ronn(1) test server.

mirror-check <formula...>

Cycle through mirror lists for each formula, attempt a download and validate MD5 sums.

missing [<formulae>]

Check the given for missing dependencies.

If no are given, check all installed brews.

pull <URLish> [--install]

Get a patch from a GitHub commit or pull request and apply it to Homebrew. <URLish> may be the URL of a GitHub commit or pull request, or the issue number of a pull request.

If --install is passed, installs any formulae added or modified by the patch.

readall

Import all formulae one by one. This is useful for testing new functionality across all formulae, or to check all formulae for errors.

server

Start a local web app that lets you browse available formulae, similar to gem server. Requires sinatra.

switch <formula> <version>

Switch between installed versions of <formula>. If you have multiple versions of a formula installed, the standard brew link command will fail. switch tries to unlink all versions from HOMEBREW_PREFIX, then [re]links the requested version.

unpack [--patch] [--destdir=path/to/extract/in] <formulae>

Unpack the source code of <formulae> for inspection. Formulae archives will be extracted to subdirectories inside the current working directory or a directory specified by --destdir. If the --patch option is supplied, patches will also be downloaded and applied.

which [<formulae>]

List versions of installed brews.

If <formulae> are given, only list versions for the specified brews.

USER-SUBMITTED COMMANDS

These commands have been contributed by Homebrew users but are not included in the main Homebrew repository, nor are they installed by the installer script. You can install them manually, as outlined above.

NOTE: They are largely untested, and as always, be careful about running untested code on your machine.

brew-desc

Get short descriptions for Homebrew formulas or search formulas by description: https://github.com/telemachus/brew-desc

brew-gem and brew-pip

Install any gem pip package into a self-contained Homebrew cellar location

https://github.com/josh/brew-gem, https://github.com/josh/brew-pip

Note: These can also be installed with brew install brew-gem and brew install brew-pip

brew-growl

Get Growl notifications for Homebrew https://github.com/secondplanet/brew-growl

brew-more

Scrapes a formula's homepage to get more information: https://gist.github.com/475200

brew-refresh

Does brew update followed by brew outdated: https://gist.github.com/514247

brew-rebase

Does a rebase on "brew update" instead of a merge: https://gist.github.com/493669

brew-services

Simple support to start formulas using launchctl, has out of the box support for any formula which defines startup_plist (e.g. mysql, postgres, redis u.v.m.): https://gist.github.com/766293

brew-tap

Multi-repository support for Homebrew implemented as an external command. Aims to make it easy to access and install formulae that are not in the master repository without having to switch branches. Code is available in pull request #6086.

The best way to get started with brew-tap is:

1. Fork Homebrew-alt, as brew-tap uses the fork network of that repository to seed the list of available external repositories.
2. If you want to start from scratch, clean out the master branch of your Homebrew-alt fork by git reset --hard aa06758 followed by a git push -f origin master.
3. Commit your customized formulae to the Homebrew-alt fork---organize however you want. Currently, the only rules are that formula files must end in .rb and that any file ending in .rb must be a valid formula (no odd ruby scripts floating around).

Then, other people can use brew-tap to access your repository of customized formulae by doing the following:

1. Go to the Homebrew prefix using cd `brew --prefix` .
2. Check out a new branch into which brew tap will be merged using git checkout -b brew-tap so that the history of master stays clean.
3. Add brew-tap into this new branch by running brew pull https://github.com/mxcl/homebrew/pull/6086.
4. Add external repositories via brew tap add <GitHub username that forked Homebrew-alt>.
5. Install stuff from external repositories via brew tap install <formula> [options] or, for cases where Homebrew already has a formula, brew tap install <GitHub username that forked Homebrew-alt>/<formula> [options].
6. Keep the brew-tap branch up to date with changes to Homebrew master by git checkout brew-tap && git rebase master.

The above steps should simplify to just 4 and 5 once multi-repository support becomes a core Homebrew feature. Work is ongoing in pull request #7643. Also see the brew-tap manpage which can be viewed via man brew-tap.

brew-whatchanged

Show a summary of changes since the last time you brew updated: https://gist.github.com/1242881

SEE ALSO

Homebrew Wiki: http://wiki.github.com/mxcl/homebrew/

brew(1), which(1), grep(1), ronn(1)