brew/Library/Homebrew/manpages/brew.1.md.erb

<%
# To make changes to this man page:
#
# - For changes to a command under `COMMANDS` or `DEVELOPER COMMANDS` sections):
#   - Find the source file in `Library/Homebrew/[dev-]cmd/<command>.{rb,sh}`.
#   - For `.rb` files, edit the `<command>_args` method.
#   - For `.sh` files, edit the top comment, being sure to use the line prefix
#     `#:` for the comments to be recognized as documentation. If in doubt,
#     compare with already documented commands.
# - For global options: Edit `Library/Homebrew/cli/parser.rb`.
# - For environment variables: Edit `Library/Homebrew/env_config.rb`.
# - For other changes: Edit this file.
#
# When done, regenerate the man page and its HTML version by running
# `brew generate-man-completions`.
%>
brew(1) -- The Missing Package Manager for macOS (or Linux)
===========================================================

## SYNOPSIS

`brew` `--version`<br>
`brew` <command> \[`--verbose`\|`-v`\] \[<options>\] \[<formula>\] ...

## DESCRIPTION

Homebrew is the easiest and most flexible way to install the UNIX tools Apple
didn't include with macOS. It can also install software not packaged for your
Linux distribution without requiring `sudo`.

## TERMINOLOGY

**formula**

: Homebrew package definition that builds from upstream sources

**cask**

: Homebrew package definition that installs macOS native applications

**prefix**

: path in which Homebrew is installed, e.g. `/usr/local`

**keg**

: installation destination directory of a given **formula** version, e.g. `/usr/local/Cellar/foo/0.1`

**rack**

: directory containing one or more versioned **kegs**, e.g. `/usr/local/Cellar/foo`

**keg-only**

: a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix

**opt prefix**

: a symlink to the active version of a **keg**, e.g. `/usr/local/opt/foo`

**Cellar**

: directory containing one or more named **racks**, e.g. `/usr/local/Cellar`

**Caskroom**

: directory containing one or more named **casks**, e.g. `/usr/local/Caskroom`

**external command**

: `brew` subcommand defined outside of the Homebrew/brew GitHub repository

**tap**

: directory (and usually Git repository) of **formulae**, **casks** and/or **external commands**

**bottle**

: pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources

## ESSENTIAL COMMANDS

For the full command list, see the [COMMANDS](#commands) section.

With `--verbose` or `--debug`, many commands print extra debugging information.
Note that these options should only appear after a command.

Some command behaviour can be customised with environment variables; see the [ENVIRONMENT](#environment) section.

### `install` <formula>

Install <formula>.

<formula> is usually the name of the formula to install, but it has other
syntaxes which are listed in the [SPECIFYING FORMULAE](#specifying-formulae)
section.

### `uninstall` <formula>

Uninstall <formula>.

### `list`

List all installed formulae.

### `search` \[<text>\|`/`<text>`/`\]

Perform a substring search of cask tokens and formula names for <text>. If
<text> is flanked by slashes, it is interpreted as a regular expression. The
search for <text> is extended online to `homebrew/core` and `homebrew/cask`.
If no search term is provided, all locally available formulae are listed.

## COMMANDS

<%= commands %>

## DEVELOPER COMMANDS

<%= developer_commands %>

## GLOBAL CASK OPTIONS

<%= global_cask_options %>

## GLOBAL OPTIONS

<%= global_options %>

## OFFICIAL EXTERNAL COMMANDS

<%= official_external_commands %>

## CUSTOM EXTERNAL COMMANDS

Homebrew, like `git`(1), supports external commands. These are executable
scripts that reside somewhere in the `PATH`, named `brew-`<cmdname> or
`brew-`<cmdname>`.rb`, which can be invoked like `brew` <cmdname>. This
allows you to create your own commands without modifying Homebrew's internals.

Instructions for creating your own commands can be found in the docs:
<https://docs.brew.sh/External-Commands>

## SPECIFYING FORMULAE

Many Homebrew commands accept one or more <formula> arguments. These arguments
can take several different forms:

  * The name of a formula:
    e.g. `git`, `node`, `wget`.

  * The fully-qualified name of a tapped formula:
    Sometimes a formula from a tapped repository may conflict with one in
    `homebrew/core`.
    You can still access these formulae by using a special syntax, e.g.
    `homebrew/dupes/vim` or `homebrew/versions/node4`.

  * An arbitrary file:
    Homebrew can install formulae from a local path. It can point to either a
    formula file or a bottle.
    Prefix relative paths with `./` to prevent them from being interpreted as a
    formula or tap name.

## SPECIFYING CASKS

Many Homebrew Cask commands accept one or more <cask> arguments. These can be
specified the same way as the <formula> arguments described in
`SPECIFYING FORMULAE` above.

## ENVIRONMENT

Note that environment variables must have a value set to be detected. For
example, run `export HOMEBREW_NO_INSECURE_REDIRECT=1` rather than just
`export HOMEBREW_NO_INSECURE_REDIRECT`.

`HOMEBREW_*` environment variables can also be set in Homebrew's environment
files:

* `/etc/homebrew/brew.env` (system-wide)

* `${HOMEBREW_PREFIX}/etc/homebrew/brew.env` (prefix-specific)

* `$XDG_CONFIG_HOME/homebrew/brew.env` if `$XDG_CONFIG_HOME` is set or
  `~/.homebrew/brew.env` otherwise (user-specific)

User-specific environment files take precedence over prefix-specific files and
prefix-specific files take precedence over system-wide files (unless
`HOMEBREW_SYSTEM_ENV_TAKES_PRIORITY` is set, see below).

Note that these files do not support shell variable expansion e.g. `$HOME` or
command execution e.g. `$(cat file)`.

<%= environment_variables %>

## USING HOMEBREW BEHIND A PROXY

Set the `http_proxy`, `https_proxy`, `all_proxy`, `ftp_proxy` and/or `no_proxy`
environment variables documented above.

For example, to use an unauthenticated HTTP or SOCKS5 proxy:

    export http_proxy=http://$HOST:$PORT

    export all_proxy=socks5://$HOST:$PORT

And for an authenticated HTTP proxy:

    export http_proxy=http://$USER:$PASSWORD@$HOST:$PORT

## SEE ALSO

Homebrew Documentation: <https://docs.brew.sh>

Homebrew API: <https://rubydoc.brew.sh>

`git`(1), `git-log`(1)

## AUTHORS

<%= lead.concat("\n") %>

<%= plc.concat("\n") %>

<%= tsc.concat("\n") %>

<%= maintainers.concat("\n") %>

<%= alumni.concat("\n") %>

## BUGS

See our issues on GitHub:

**Homebrew/brew**

: <https://github.com/Homebrew/brew/issues>

**Homebrew/homebrew-core**

: <https://github.com/Homebrew/homebrew-core/issues>

**Homebrew/homebrew-cask**

: <https://github.com/Homebrew/homebrew-cask/issues>