brew(1) -- The missing package manager for OS X =============================================== ## SYNOPSIS `brew` [--verbose|-v] command [options] [formula] ... `brew` [--version|-v] ## DESCRIPTION Homebrew is the easiest and most flexible way to install the UNIX tools Apple didn't include with OS X. ## OPTIONS * `-v`, `--verbose` command [options] [formula] ...: Prints extra, command-specific debugging information. Note that `brew -v` by itself is the same as `brew --version`. ## ESSENTIAL COMMANDS For the full command list, see the COMMANDS section. * `install` : Install . * `remove` : Uninstall . * `update`: Fetch the newest version of Homebrew from GitHub using `git`(1). * `list`: List all installed formulae. * `search`, `-S` |//: Perform a substring search of formula names for . If is surrounded with slashes, then it is interpreted as a regular expression. If no search term is given, all available formula are displayed. ## COMMANDS * `audit [--strict]` []: Check for Homebrew coding style violations. This should be run before submitting a new formula. If no are provided, all of them are checked. If `--strict` is passed, perform additional stricter checks that may not need to be fixed before submitting. `audit` exits with a non-zero status if any errors are found. This is useful, for instance, for implementing pre-commit hooks. * `cat` : Display the source to . * `cleanup [--force]` []: 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. If `--force` is passed, remove out-of-date keg-only brews as well. * `create [--no-fetch]` : Generate a formula for the downloadable file at 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. If `--no-fetch` is passed, Homebrew will not download to the cache and will thus not add the MD5 to the formula for you. * `deps [--1] [-n]` : Show 's dependencies. If `--1` is passed, only show dependencies one level down, instead of recursing. If `-n` is passed, shows dependencies in topological order. * `doctor`: Check your system for potential problems. * `edit`: Open all of Homebrew for editing in TextMate. * `edit` : Open in $EDITOR. * `fetch [--force] [-v] [--HEAD] [--deps]` : Download the source packages for the given . For tarballs, also print MD5 and SHA1 checksums. If `--HEAD` is passed, download the HEAD versions of instead. `-v` may also be passed to make the VCS checkout verbose, useful for seeing if an existing HEAD cache has been updated. If `--force` is passed, remove a previously cached version and re-fetch. If `--deps` is passed, also download dependencies for any listed . * `home`: Open Homebrew's own homepage in a browser. * `home` : Open 's homepage in a browser. * `info` : Display information about . * `info --github` : Open a browser to the GitHub History page for formula . To view formula history locally: `brew log -p `. * `info` : Print the name and version that will be detected for . * `install [--force] [--debug] [--ignore-dependencies] [--use-clang] [--use-gcc] [--use-llvm] [--build-from-source] [--HEAD]` : Install . is usually the name of the formula to install, but may also be the URL for an arbitrary formula. If `--force` is passed, will install even if it is already installed. This can be used to re-install a formula without removing it first. If `--debug` is passed and brewing fails, open a shell inside the temporary folder used for compiling. If `--ignore-dependencies` is passed, skip installing any dependencies of any kind. If they are not already present, the formula will probably fail to install. If `--use-clang` is passed, attempt to compile using clang. If `--use-gcc` is passed, attempt to compile using GCC. This is useful for systems whose default compiler is LLVM-GCC. If `--use-llvm` is passed, attempt to compile using the LLVM front-end to GCC. *NOTE*: Not all formulae will build with LLVM. If `--build-from-source` is passed, compile from source even if a bottle is provided for . If `--HEAD` is passed, and defines it, install the HEAD version, aka master, trunk, unstable, dev. To install a newer version of HEAD use `brew rm && brew install --HEAD ` or `brew install --force --HEAD `. * `install --interactive [--git]` : Download and patch , then open a shell. This allows the user to run `./configure --help` and otherwise determine how to turn the software package into a Homebrew formula. If `--git` is passed, Homebrew will create a Git repository, useful for creating patches to the software. * `ln`, `link` : Symlink all of 's installed files into the Homebrew prefix. This is done automatically when you install formula, but can be useful for DIY installations. * `list`: List all installed formulae. * `list` : List the installed files for . * `log [git-log-options]` ...: Show the git log for the given formulae. Options that `git-log`(1) recognizes can be passed before the formula list. * `man`: Regenerate this man page using [`ronn`][ronn]. See `man brew-man` for details. * `missing` []: Check the given for missing dependencies. If no are given, check all installed brews. * `options [--compact] [--all]` : Display install options specific to . If `--compact` is passed, show all options on a single line separated by spaces. If `--all` is passed, show options for all formulae. * `outdated [--quiet]`: Show formulae that have an updated version available. If `--quiet` is passed, list only the names of outdated brews. Otherwise, the versions are printed as well. * `prune`: Remove dead symlinks from the Homebrew prefix. This is generally not needed, but can be useful when doing DIY installations. * `rm`, `remove`, `uninstall [--force]` : Uninstall . If `--force` is passed, and there are multiple versions of installed, delete all installed versions. * `search`, `-S` |//: Perform a substring search of formula names for . If is surrounded with slashes, then it is interpreted as a regular expression. If no search term is given, all available formula are displayed. * `search --macports`|`--fink` : Search for on the MacPorts or Fink package search page. * `server`: Start a local web app that lets you browse available formulae, similar to `gem server`. Requires [`sinatra`][sinatra]. * `test` : A few formulae provide a test method. `brew test ` 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. Example: `brew install jruby && brew test jruby` * `unlink` : Unsymlink from the Homebrew prefix. This can be useful for temporarily disabling a formula: `brew unlink foo && commands && brew link foo`. * `update`: Fetch the newest version of Homebrew from GitHub using `git`(1). * `upgrade` []: Upgrade outdated brews. If are given, upgrade only the specified brews. * `uses [--installed]` : Show the formulas that specify as a dependency. The list is not recursive; only one level of dependencies is resolved. If `--installed` is passed, only lists installed formulae. * `versions` : List previous versions of , along with a command to checkout each version. * `which` []: List versions of installed brews. If are given, only list versions for the specified brews. * `--cache`: Display Homebrew's download cache. *Default:* `~/Library/Cache/Homebrew` * `--cache` : Display the file or folder used to cache . * `--cellar`: Display Homebrew's Cellar path. *Default:* `/usr/local/Cellar` * `--cellar` : Display the location in the cellar where would be installed, without any sort of versioned folder as the last path. * `--config`: 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. * `--prefix`: Display Homebrew's install path. *Default:* `/usr/local` * `--prefix` : Display the location in the cellar where is or would be installed. * `--repository`: Display where Homebrew's `.git` folder is located. For standard installs, the `prefix` and `repository` are the same folder. * `-v`, `--version`: Print the version number of brew to standard error and exit. ## EXTERNAL COMMANDS Homebrew allows external commands to be defined by putting a +x file named `brew-` or `brew-.rb` on the PATH. This will cause Homebrew to recognize `brew cmdname`. Some sample commands ship with Homebrew and are enabled by default. $ ls `brew --repository`/Library/Contributions/examples ## ENVIRONMENT * HOMEBREW\_BUILD\_FROM\_SOURCE: If set, instructs Homebrew to compile from source even when a formula provides a bottle. * HOMEBREW\_CACHE: If set, instructs Homebrew to use the give folder as the download cache. Otherwise, `~/Library/Caches/Homebrew` is used. This can be used to keep downloads out of your home folder, if you have it mounted on an SSD for instance. * HOMEBREW\_DEBUG: If set, instructs Homebrew to always assume `--debug` when running commands. * HOMEBREW\_DEBUG\_INSTALL: When `brew install -d` or `brew install -i` drops into a shell, `HOMEBREW_DEBUG_INSTALL` will be set to the name of the formula being brewed. * HOMEBREW\_DEBUG\_PREFIX: When `brew install -d` or `brew install -i` drops into a shell, `HOMEBREW_DEBUG_PREFIX` will be set to the target prefix in the Cellar of the formula being brewed. * HOMEBREW\_EDITOR: If set, Homebrew will use this editor when editing a single formula, or several formulae in the same folder. *NOTE*: `brew edit` 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. * HOMEBREW\_KEEP\_INFO: If set, Homebrew will not remove files from `share/info`, allowing them to be linked from the Cellar. * HOMEBREW\_MAKE\_JOBS: If set, instructs Homebrew to use the value of `HOMEBREW_MAKE_JOBS` as the number of parallel jobs to run when building with `make`(1). *Default:* the number of available CPU cores. * HOMEBREW\_SVN: When exporting from Subversion, Homebrew will use `HOMEBREW_SVN` if set, a Homebrew-built Subversion if installed, or the system-provided binary. Set this to force Homebrew to use a particular svn binary. * HOMEBREW\_TEMP: If set, instructs Homebrew to use `HOMEBREW_TEMP` 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. This issue typically occurs when using FileVault or custom SSD configurations. * HOMEBREW\_USE\_CLANG: If set, instructs Homebrew to compile using clang. * HOMEBREW\_USE\_GCC: If set, instructs Homebrew to compile using gcc. * HOMEBREW\_USE\_LLVM: If set, instructs Homebrew to compile using LLVM. *NOTE*: Not all formulae build correctly with LLVM. * HOMEBREW\_VERBOSE: If set, instructs Homebrew to always assume `--verbose` when running commands. ## 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. For the majority of cases setting `http_proxy` is enough. You can set this in your shell profile, or you can use it before a brew command: http_proxy=http://: brew install foo If your proxy requires authentication: http_proxy=http://:@: brew install foo ## SEE ALSO Homebrew Wiki: `git`(1), `git-log`(1) ## AUTHORS Max Howell, a splendid chap. ## BUGS See Issues on GitHub: [ronn]: http://rtomayko.github.com/ronn/ "Ronn" [sinatra]: http://www.sinatrarb.com/ "Sinatra"