From fa1fd70a37c4ab843cb3d61c4301e44828c7b5ec Mon Sep 17 00:00:00 2001
From: Max Nordlund <max.nordlund@gmail.com>
Date: Fri, 8 Apr 2016 16:28:43 +0200
Subject: [PATCH] Add all the top level comments

---
 Library/Homebrew/cmd/audit.rb      | 15 ++++++++++
 Library/Homebrew/cmd/cat.rb        |  3 ++
 Library/Homebrew/cmd/cleanup.rb    | 13 ++++++++
 Library/Homebrew/cmd/command.rb    |  3 ++
 Library/Homebrew/cmd/commands.rb   |  6 ++++
 Library/Homebrew/cmd/config.rb     |  5 ++++
 Library/Homebrew/cmd/create.rb     | 17 +++++++++++
 Library/Homebrew/cmd/deps.rb       | 23 ++++++++++++++
 Library/Homebrew/cmd/desc.rb       | 10 +++++++
 Library/Homebrew/cmd/diy.rb        | 10 +++++++
 Library/Homebrew/cmd/doctor.rb     |  4 +++
 Library/Homebrew/cmd/edit.rb       |  6 ++++
 Library/Homebrew/cmd/fetch.rb      | 20 +++++++++++++
 Library/Homebrew/cmd/home.rb       |  6 ++++
 Library/Homebrew/cmd/info.rb       | 18 +++++++++++
 Library/Homebrew/cmd/install.rb    | 48 ++++++++++++++++++++++++++++++
 Library/Homebrew/cmd/irb.rb        |  5 ++++
 Library/Homebrew/cmd/leaves.rb     |  3 ++
 Library/Homebrew/cmd/link.rb       | 14 +++++++++
 Library/Homebrew/cmd/linkapps.rb   |  9 ++++++
 Library/Homebrew/cmd/list.rb       | 19 ++++++++++++
 Library/Homebrew/cmd/log.rb        |  4 +++
 Library/Homebrew/cmd/migrate.rb    |  7 +++++
 Library/Homebrew/cmd/missing.rb    |  5 ++++
 Library/Homebrew/cmd/options.rb    | 10 +++++++
 Library/Homebrew/cmd/outdated.rb   | 14 +++++++++
 Library/Homebrew/cmd/pin.rb        |  4 +++
 Library/Homebrew/cmd/prune.rb      |  9 ++++++
 Library/Homebrew/cmd/reinstall.rb  |  3 ++
 Library/Homebrew/cmd/search.rb     | 12 ++++++++
 Library/Homebrew/cmd/sh.rb         |  7 +++++
 Library/Homebrew/cmd/switch.rb     |  3 ++
 Library/Homebrew/cmd/tap-info.rb   | 12 ++++++++
 Library/Homebrew/cmd/tap-pin.rb    |  4 +++
 Library/Homebrew/cmd/tap-unpin.rb  |  3 ++
 Library/Homebrew/cmd/tap.rb        | 33 ++++++++++++++++++++
 Library/Homebrew/cmd/test.rb       | 14 +++++++++
 Library/Homebrew/cmd/uninstall.rb  |  6 ++++
 Library/Homebrew/cmd/unlink.rb     |  8 +++++
 Library/Homebrew/cmd/unlinkapps.rb | 11 +++++++
 Library/Homebrew/cmd/unpack.rb     | 11 +++++++
 Library/Homebrew/cmd/unpin.rb      |  4 +++
 Library/Homebrew/cmd/untap.rb      |  3 ++
 Library/Homebrew/cmd/update.sh     |  6 ++++
 Library/Homebrew/cmd/upgrade.rb    | 10 +++++++
 Library/Homebrew/cmd/uses.rb       | 17 +++++++++++
 46 files changed, 477 insertions(+)

diff --git a/Library/Homebrew/cmd/audit.rb b/Library/Homebrew/cmd/audit.rb
index acc22f98a1..3fe4619085 100644
--- a/Library/Homebrew/cmd/audit.rb
+++ b/Library/Homebrew/cmd/audit.rb
@@ -1,3 +1,18 @@
+#:  * `audit` [`--strict`] [`--online`] [<formulae>]:
+#:    Check <formulae> for Homebrew coding style violations. This should be
+#:    run before submitting a new formula.
+#:
+#:    If no <formulae> are provided, all of them are checked.
+#:
+#:    If `--strict` is passed, additional checks are run. This should be used
+#:    when creating for new formulae.
+#:
+#:    If `--online` is passed, additional slower checks that require a network
+#:    connection are run. This should be used when creating for new formulae.
+#:
+#:    `audit` exits with a non-zero status if any errors are found. This is useful,
+#:    for instance, for implementing pre-commit hooks.
+
 require "formula"
 require "formula_versions"
 require "utils"
diff --git a/Library/Homebrew/cmd/cat.rb b/Library/Homebrew/cmd/cat.rb
index b42e54a57a..a2fbd2f00e 100644
--- a/Library/Homebrew/cmd/cat.rb
+++ b/Library/Homebrew/cmd/cat.rb
@@ -1,3 +1,6 @@
+#:  * `cat` <formula>:
+#:    Display the source to <formula>.
+
 module Homebrew
   def cat
     # do not "fix" this to support multiple arguments, the output would be
diff --git a/Library/Homebrew/cmd/cleanup.rb b/Library/Homebrew/cmd/cleanup.rb
index 7d891787a7..a9d3fbcde5 100644
--- a/Library/Homebrew/cmd/cleanup.rb
+++ b/Library/Homebrew/cmd/cleanup.rb
@@ -1,3 +1,16 @@
+#:  * `cleanup` [`--prune=`<days>] [`--dry-run`] [`-s`] [<formulae>]:
+#:    For all installed or specific formulae, remove any older versions from the
+#:    cellar. In addition, old downloads from the Homebrew download-cache are deleted.
+#:
+#:    If `--prune=`<days> is specified, remove all cache files older than <days>.
+#:
+#:    If `--dry-run` or `-n` is passed, show what would be removed, but do not
+#:    actually remove anything.
+#:
+#:    If `-s` is passed, scrubs the cache, removing downloads for even the latest
+#:    versions of formulae. Note downloads for any installed formulae will still not be
+#:    deleted. If you want to delete those too: `rm -rf $(brew --cache)`
+
 require "cleanup"
 require "utils"
 
diff --git a/Library/Homebrew/cmd/command.rb b/Library/Homebrew/cmd/command.rb
index ad7f99288e..8c8a8c6990 100644
--- a/Library/Homebrew/cmd/command.rb
+++ b/Library/Homebrew/cmd/command.rb
@@ -1,3 +1,6 @@
+#:  * `command` <cmd>:
+#:    Display the path to the file which is used when invoking `brew` <cmd>.
+
 module Homebrew
   def command
     abort "This command requires a command argument" if ARGV.empty?
diff --git a/Library/Homebrew/cmd/commands.rb b/Library/Homebrew/cmd/commands.rb
index 88290a43d2..52705c58a9 100644
--- a/Library/Homebrew/cmd/commands.rb
+++ b/Library/Homebrew/cmd/commands.rb
@@ -1,3 +1,9 @@
+#:  * `commands` [`--quiet` [`--include-aliases`]]:
+#:    Show a list of built-in and external commands.
+#:
+#:    If `--quiet` is passed, list only the names of commands without the header.
+#:    With `--include-aliases`, the aliases of internal commands will be included.
+
 module Homebrew
   def commands
     if ARGV.include? "--quiet"
diff --git a/Library/Homebrew/cmd/config.rb b/Library/Homebrew/cmd/config.rb
index 7f8416ce75..8d3c1e0f04 100644
--- a/Library/Homebrew/cmd/config.rb
+++ b/Library/Homebrew/cmd/config.rb
@@ -1,3 +1,8 @@
+#:  * `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.
+
 require "hardware"
 require "software_spec"
 require "rexml/document"
diff --git a/Library/Homebrew/cmd/create.rb b/Library/Homebrew/cmd/create.rb
index a468189c41..791ff23d9f 100644
--- a/Library/Homebrew/cmd/create.rb
+++ b/Library/Homebrew/cmd/create.rb
@@ -1,3 +1,20 @@
+#:  * `create` <URL> [`--autotools`|`--cmake`] [`--no-fetch`] [`--set-name` <name>] [`--set-version` <version>]:
+#:    Generate a formula for the downloadable file at <URL> and open it in the editor.
+#:    Homebrew will attempt to automatically derive the formula name
+#:    and version, but if it fails, you'll have to make your own template. The `wget`
+#:    formula serves as a simple example. For the complete API have a look at
+#:
+#:    <http://www.rubydoc.info/github/Homebrew/brew/master/Formula>
+#:
+#:    If `--autotools` is passed, create a basic template for an Autotools-style build.
+#:    If `--cmake` is passed, create a basic template for a CMake-style build.
+#:
+#:    If `--no-fetch` is passed, Homebrew will not download <URL> to the cache and
+#:    will thus not add the SHA256 to the formula for you.
+#:
+#:    The options `--set-name` and `--set-version` each take an argument and allow
+#:    you to explicitly set the name and version of the package you are creating.
+
 require "formula"
 require "blacklist"
 require "digest"
diff --git a/Library/Homebrew/cmd/deps.rb b/Library/Homebrew/cmd/deps.rb
index 70b396bfd3..0d6b937c54 100644
--- a/Library/Homebrew/cmd/deps.rb
+++ b/Library/Homebrew/cmd/deps.rb
@@ -1,3 +1,26 @@
+#:  * `deps` [`--1`] [`-n`] [`--union`] [`--tree`] [`--all`] [`--installed`] [`--skip-build`] [`--skip-optional`] <formulae>:
+#:    Show dependencies for <formulae>. When given multiple formula arguments,
+#:    show the intersection of dependencies for <formulae>, except when passed
+#:    `--tree`, `--all`, or `--installed`.
+#:
+#:    If `--1` is passed, only show dependencies one level down, instead of
+#:    recursing.
+#:
+#:    If `-n` is passed, show dependencies in topological order.
+#:
+#:    If `--union` is passed, show the union of dependencies for <formulae>,
+#:    instead of the intersection.
+#:
+#:    If `--tree` is passed, show dependencies as a tree.
+#:
+#:    If `--all` is passed, show dependencies for all formulae.
+#:
+#:    If `--installed` is passed, show dependencies for all installed formulae.
+#:
+#:    By default, `deps` shows dependencies for <formulae>. To skip the `:build`
+#:    type dependencies, pass `--skip-build`. Similarly, pass `--skip-optional`
+#:    to skip `:optional` dependencies.
+
 # encoding: UTF-8
 require "formula"
 require "ostruct"
diff --git a/Library/Homebrew/cmd/desc.rb b/Library/Homebrew/cmd/desc.rb
index df228d643e..e7e7528fc5 100644
--- a/Library/Homebrew/cmd/desc.rb
+++ b/Library/Homebrew/cmd/desc.rb
@@ -1,3 +1,13 @@
+#:  * `desc` <formula>:
+#:    Display <formula>'s name and one-line description.
+#:
+#:  * `desc` [`-s`|`-n`|`-d`] <pattern>:
+#:    Search both name and description (`-s`), just the names (`-n`), or just  the
+#:    descriptions (`-d`) for `<pattern>`. `<pattern>` is by default interpreted
+#:    as a literal string; if flanked by slashes, it is instead interpreted as a
+#:    regular expression. Formula descriptions are cached; the cache is created on
+#:    the first search, making that search slower than subsequent ones.
+
 require "descriptions"
 require "cmd/search"
 
diff --git a/Library/Homebrew/cmd/diy.rb b/Library/Homebrew/cmd/diy.rb
index edcc6ee168..8262352f82 100644
--- a/Library/Homebrew/cmd/diy.rb
+++ b/Library/Homebrew/cmd/diy.rb
@@ -1,3 +1,13 @@
+#:  * `diy` [`--name=`<name>] [`--version=`<version>]:
+#:    Automatically determine the installation prefix for non-Homebrew software.
+#:
+#:    Using the output from this command, you can install your own software into
+#:    the Cellar and then link it into Homebrew's prefix with `brew link`.
+#:
+#:    The options `--name=`<name> and `--version=`<version> each take an argument
+#:    and allow you to explicitly set the name and version of the package you are
+#:    installing.
+
 require "formula"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/doctor.rb b/Library/Homebrew/cmd/doctor.rb
index 8f8e1331f1..01f2f82644 100644
--- a/Library/Homebrew/cmd/doctor.rb
+++ b/Library/Homebrew/cmd/doctor.rb
@@ -1,3 +1,7 @@
+#:  * `doctor`:
+#:    Check your system for potential problems. Doctor exits with a non-zero status
+#:    if any problems are found.
+
 require "diagnostic"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/edit.rb b/Library/Homebrew/cmd/edit.rb
index c683de0dc8..ef325b8b63 100644
--- a/Library/Homebrew/cmd/edit.rb
+++ b/Library/Homebrew/cmd/edit.rb
@@ -1,3 +1,9 @@
+#:  * `edit`:
+#:    Open all of Homebrew for editing.
+#:
+#:  * `edit` <formula>:
+#:    Open <formula> in the editor.
+
 require "formula"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/fetch.rb b/Library/Homebrew/cmd/fetch.rb
index fabe268e53..8a1a092ccd 100644
--- a/Library/Homebrew/cmd/fetch.rb
+++ b/Library/Homebrew/cmd/fetch.rb
@@ -1,3 +1,23 @@
+#:  * `fetch` [`--force`] [`-v`] [`--devel`|`--HEAD`] [`--deps`] [`--build-from-source`|`--force-bottle`] <formulae>:
+#:    Download the source packages for the given <formulae>.
+#:    For tarballs, also print SHA-1 and SHA-256 checksums.
+#:
+#:    If `--HEAD` or `--devel` is passed, fetch that version instead of the
+#:    stable version.
+#:
+#:    If `-v` is passed, do a verbose VCS checkout, if the URL represents a CVS.
+#:    This is useful for seeing if an existing VCS 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 <formulae>.
+#:
+#:    If `--build-from-source` is passed, download the source rather than a
+#:    bottle.
+#:
+#:    If `--force-bottle` is passed, download a bottle if it exists for the current
+#:    version of OS X, even if it would not be used during installation.
+
 require "formula"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/home.rb b/Library/Homebrew/cmd/home.rb
index 43a6299ae0..0c3009545c 100644
--- a/Library/Homebrew/cmd/home.rb
+++ b/Library/Homebrew/cmd/home.rb
@@ -1,3 +1,9 @@
+#:  * `home`:
+#:    Open Homebrew's own homepage in a browser.
+#:
+#:  * `home` <formula>:
+#:    Open <formula>'s homepage in a browser.
+
 module Homebrew
   def home
     if ARGV.named.empty?
diff --git a/Library/Homebrew/cmd/info.rb b/Library/Homebrew/cmd/info.rb
index fb31c0a946..ad68dc8f4d 100644
--- a/Library/Homebrew/cmd/info.rb
+++ b/Library/Homebrew/cmd/info.rb
@@ -1,3 +1,21 @@
+#:  * `info` <formula>:
+#:    Display information about <formula>.
+#:
+#:  * `info` `--github` <formula>:
+#:    Open a browser to the GitHub History page for formula <formula>.
+#:
+#:    To view formula history locally: `brew log -p <formula>`.
+#:
+#:  * `info` `--json=`<version> (`--all`|`--installed`|<formulae>):
+#:    Print a JSON representation of <formulae>. Currently the only accepted value
+#:    for <version> is `v1`.
+#:
+#:    Pass `--all` to get information on all formulae, or `--installed` to get
+#:    information on all installed formulae.
+#:
+#:    See the docs for examples of using the JSON:
+#:    <https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md>
+
 require "blacklist"
 require "caveats"
 require "options"
diff --git a/Library/Homebrew/cmd/install.rb b/Library/Homebrew/cmd/install.rb
index 6745e92b00..30203a6f04 100644
--- a/Library/Homebrew/cmd/install.rb
+++ b/Library/Homebrew/cmd/install.rb
@@ -1,3 +1,51 @@
+#:  * `install` [`--debug`] [`--env=`<std>|<super>] [`--ignore-dependencies`] [`--only-dependencies`] [`--cc=`<compiler>] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] <formula>:
+#:    Install <formula>.
+#:
+#:    <formula> is usually the name of the formula to install, but it can be specified
+#:    several different ways. See [SPECIFYING FORMULAE][].
+#:
+#:    If `--debug` is passed and brewing fails, open an interactive debugging
+#:    session with access to IRB or a shell inside the temporary build directory.
+#:
+#:    If `--env=std` is passed, use the standard build environment instead of superenv.
+#:
+#:    If `--env=super` is passed, use superenv even if the formula specifies the
+#:    standard build environment.
+#:
+#:    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 `--only-dependencies` is passed, install the dependencies with specified
+#:    options but do not install the specified formula.
+#:
+#:    If `--cc=`<compiler> is passed, attempt to compile using <compiler>.
+#:    <compiler> should be the name of the compiler's executable, for instance
+#:    `gcc-4.2` for Apple's GCC 4.2, or `gcc-4.9` for a Homebrew-provided GCC
+#:    4.9.
+#:
+#:    If `--build-from-source` is passed, compile from source even if a bottle
+#:    is provided for <formula>.
+#:
+#:    If `--force-bottle` is passed, install from a bottle if it exists
+#:    for the current version of OS X, even if custom options are given.
+#:
+#:    If `--devel` is passed, and <formula> defines it, install the development version.
+#:
+#:    If `--HEAD` is passed, and <formula> defines it, install the HEAD version,
+#:    aka master, trunk, unstable.
+#:
+#:    To install a newer version of HEAD use
+#:    `brew rm <foo> && brew install --HEAD <foo>`.
+#:
+#:  * `install` `--interactive` [`--git`] <formula>:
+#:    Download and patch <formula>, 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.
+
 require "blacklist"
 require "diagnostic"
 require "cmd/search"
diff --git a/Library/Homebrew/cmd/irb.rb b/Library/Homebrew/cmd/irb.rb
index 1a272a6849..1db0855bbf 100644
--- a/Library/Homebrew/cmd/irb.rb
+++ b/Library/Homebrew/cmd/irb.rb
@@ -1,3 +1,8 @@
+#:  * `irb` [`--examples`]:
+#:    Enter the interactive Homebrew Ruby shell.
+#:
+#:    If `--examples` is passed, several examples will be shown.
+
 require "formula"
 require "keg"
 require "irb"
diff --git a/Library/Homebrew/cmd/leaves.rb b/Library/Homebrew/cmd/leaves.rb
index 48be4b70cb..06f81d92d7 100644
--- a/Library/Homebrew/cmd/leaves.rb
+++ b/Library/Homebrew/cmd/leaves.rb
@@ -1,3 +1,6 @@
+#:  * `leaves`:
+#:    Show installed formulae that are not dependencies of another installed formula.
+
 require "formula"
 require "tab"
 require "set"
diff --git a/Library/Homebrew/cmd/link.rb b/Library/Homebrew/cmd/link.rb
index fe9fa49d04..f4ef16e8ad 100644
--- a/Library/Homebrew/cmd/link.rb
+++ b/Library/Homebrew/cmd/link.rb
@@ -1,3 +1,17 @@
+#:  * `ln`, `link` [`--overwrite`] [`--dry-run`] [`--force`] <formula>:
+#:    Symlink all of <formula>'s installed files into the Homebrew prefix. This
+#:    is done automatically when you install formulae but can be useful for DIY
+#:    installations.
+#:
+#:    If `--overwrite` is passed, Homebrew will delete files which already exist in
+#:    the prefix while linking.
+#:
+#:    If `--dry-run` or `-n` is passed, Homebrew will list all files which would
+#:    be linked or which would be deleted by `brew link --overwrite`, but will not
+#:    actually link or delete any files.
+#:
+#:    If `--force` is passed, Homebrew will allow keg-only formulae to be linked.
+
 require "ostruct"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/linkapps.rb b/Library/Homebrew/cmd/linkapps.rb
index d975649327..6659ce2561 100644
--- a/Library/Homebrew/cmd/linkapps.rb
+++ b/Library/Homebrew/cmd/linkapps.rb
@@ -1,3 +1,12 @@
+#:  * `linkapps` [`--local`] [<formulae>]:
+#:    Find installed formulae that provide `.app`-style OS X apps and symlink them
+#:    into `/Applications`, allowing for easier access.
+#:
+#:    If no <formulae> are provided, all of them will have their apps symlinked.
+#:
+#:    If provided, `--local` will symlink them into the user's `~/Applications`
+#:    directory instead of the system directory.
+
 require "keg"
 require "formula"
 
diff --git a/Library/Homebrew/cmd/list.rb b/Library/Homebrew/cmd/list.rb
index 5ab05b1c88..471d2b917a 100644
--- a/Library/Homebrew/cmd/list.rb
+++ b/Library/Homebrew/cmd/list.rb
@@ -1,3 +1,22 @@
+#:  * `list`, `ls` [`--full-name`]:
+#:    List all installed formulae. If `--full-name` is passed, print formulae with
+#:    full-qualified names.
+#:
+#:  * `list`, `ls` `--unbrewed`:
+#:    List all files in the Homebrew prefix not installed by Homebrew.
+#:
+#:  * `list`, `ls` [`--versions` [`--multiple`]] [`--pinned`] [<formulae>]:
+#:    List the installed files for <formulae>. Combined with `--verbose`, recursively
+#:    list the contents of all subdirectories in each <formula>'s keg.
+#:
+#:    If `--versions` is passed, show the version number for installed formulae,
+#:    or only the specified formulae if <formulae> are given. With `--multiple`,
+#:    only show formulae with multiple versions installed.
+#:
+#:    If `--pinned` is passed, show the versions of pinned formulae, or only the
+#:    specified (pinned) formulae if <formulae> are given.
+#:    See also `pin`, `unpin`.
+
 require "metafiles"
 require "formula"
 
diff --git a/Library/Homebrew/cmd/log.rb b/Library/Homebrew/cmd/log.rb
index 7f9dac40fb..e2dd08d7c4 100644
--- a/Library/Homebrew/cmd/log.rb
+++ b/Library/Homebrew/cmd/log.rb
@@ -1,3 +1,7 @@
+#:  * `log` [`git-log-options`] <formula> ...:
+#:    Show the git log for the given formulae. Options that `git-log`(1)
+#:    recognizes can be passed before the formula list.
+
 require "formula"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/migrate.rb b/Library/Homebrew/cmd/migrate.rb
index b3562b14a1..27ca5261f9 100644
--- a/Library/Homebrew/cmd/migrate.rb
+++ b/Library/Homebrew/cmd/migrate.rb
@@ -1,3 +1,10 @@
+#:  * `migrate` [`--force`] <formulae>:
+#:    Migrate renamed packages to new name, where <formulae> are old names of
+#:    packages.
+#:
+#:    If `--force` is passed, then treat installed <formulae> and passed <formulae>
+#:    like if they are from same taps and migrate them anyway.
+
 require "migrator"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/missing.rb b/Library/Homebrew/cmd/missing.rb
index 3d70e5f353..41ad4f16d5 100644
--- a/Library/Homebrew/cmd/missing.rb
+++ b/Library/Homebrew/cmd/missing.rb
@@ -1,3 +1,8 @@
+#:  * `missing` [<formulae>]:
+#:    Check the given <formulae> for missing dependencies.
+#:
+#:    If no <formulae> are given, check all installed brews.
+
 require "formula"
 require "tab"
 require "diagnostic"
diff --git a/Library/Homebrew/cmd/options.rb b/Library/Homebrew/cmd/options.rb
index f9d3ad7937..690acd0169 100644
--- a/Library/Homebrew/cmd/options.rb
+++ b/Library/Homebrew/cmd/options.rb
@@ -1,3 +1,13 @@
+#:  * `options` [`--compact`] (`--all`|`--installed`|<formulae>):
+#:    Display install options specific to <formulae>.
+#:
+#:    If `--compact` is passed, show all options on a single line separated by
+#:    spaces.
+#:
+#:    If `--all` is passed, show options for all formulae.
+#:
+#:    If `--installed` is passed, show options for all installed formulae.
+
 require "formula"
 require "options"
 
diff --git a/Library/Homebrew/cmd/outdated.rb b/Library/Homebrew/cmd/outdated.rb
index dbcf94ae89..dfd61226aa 100644
--- a/Library/Homebrew/cmd/outdated.rb
+++ b/Library/Homebrew/cmd/outdated.rb
@@ -1,3 +1,17 @@
+#:  * `outdated` [`--quiet`|`--verbose`|`--json=v1`]:
+#:    Show formulae that have an updated version available.
+#:
+#:    By default, version information is displayed in interactive shells, and
+#:    suppressed otherwise.
+#:
+#:    If `--quiet` is passed, list only the names of outdated brews (takes
+#:    precedence over `--verbose`).
+#:
+#:    If `--verbose` is passed, display detailed version information.
+#:
+#:    If `--json=`<version> is passed, the output will be in JSON format. The only
+#:    valid version is `v1`.
+
 require "formula"
 require "keg"
 
diff --git a/Library/Homebrew/cmd/pin.rb b/Library/Homebrew/cmd/pin.rb
index 0b6dfa30b6..a54ef6e7bf 100644
--- a/Library/Homebrew/cmd/pin.rb
+++ b/Library/Homebrew/cmd/pin.rb
@@ -1,3 +1,7 @@
+#:  * `pin` <formulae>:
+#:    Pin the specified <formulae>, preventing them from being upgraded when
+#:    issuing the `brew upgrade` command. See also `unpin`.
+
 require "formula"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/prune.rb b/Library/Homebrew/cmd/prune.rb
index ef416a3436..a36c960e7e 100644
--- a/Library/Homebrew/cmd/prune.rb
+++ b/Library/Homebrew/cmd/prune.rb
@@ -1,3 +1,12 @@
+#:  * `prune` [`--dry-run`]:
+#:    Remove dead symlinks from the Homebrew prefix. This is generally not
+#:    needed, but can be useful when doing DIY installations. Also remove broken
+#:    app symlinks from `/Applications` and `~/Applications` that were previously
+#:    created by `brew linkapps`.
+#:
+#:    If `--dry-run` or `-n` is passed, show what would be removed, but do not
+#:    actually remove anything.
+
 require "keg"
 require "cmd/tap"
 require "cmd/unlinkapps"
diff --git a/Library/Homebrew/cmd/reinstall.rb b/Library/Homebrew/cmd/reinstall.rb
index e25e242901..8cf81fb619 100644
--- a/Library/Homebrew/cmd/reinstall.rb
+++ b/Library/Homebrew/cmd/reinstall.rb
@@ -1,3 +1,6 @@
+#:  * `reinstall` <formula>:
+#:    Uninstall then install <formula>
+
 require "formula_installer"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/search.rb b/Library/Homebrew/cmd/search.rb
index 2fd558a5ca..c15331cd73 100644
--- a/Library/Homebrew/cmd/search.rb
+++ b/Library/Homebrew/cmd/search.rb
@@ -1,3 +1,15 @@
+#:  * `search`, `-S`:
+#:    Display all locally available formulae for brewing (including tapped ones).
+#:    No online search is performed if called without arguments.
+#:
+#:  * `search`, `-S` <text>|`/`<text>`/`:
+#:    Perform a substring search of formula names for <text>. If <text> is
+#:    surrounded with slashes, then it is interpreted as a regular expression.
+#:    The search for <text> is extended online to some popular taps.
+#:
+#:  * `search` (`--debian`|`--fedora`|`--fink`|`--macports`|`--opensuse`|`--ubuntu`) <text>:
+#:    Search for <text> in the given package manager's list.
+
 require "formula"
 require "blacklist"
 require "utils"
diff --git a/Library/Homebrew/cmd/sh.rb b/Library/Homebrew/cmd/sh.rb
index 5ada75ab25..3720124b7e 100644
--- a/Library/Homebrew/cmd/sh.rb
+++ b/Library/Homebrew/cmd/sh.rb
@@ -1,3 +1,10 @@
+#:  * `sh` [`--env=std`]:
+#:    Instantiate a Homebrew build environment. Uses our years-battle-hardened
+#:    Homebrew build logic to help your `./configure && make && make install`
+#:    or even your `gem install` succeed. Especially handy if you run Homebrew
+#:    in an Xcode-only configuration since it adds tools like `make` to your `PATH`
+#:    which otherwise build-systems would not find.
+
 require "extend/ENV"
 require "formula"
 
diff --git a/Library/Homebrew/cmd/switch.rb b/Library/Homebrew/cmd/switch.rb
index b4c3c43d9c..a44514880a 100644
--- a/Library/Homebrew/cmd/switch.rb
+++ b/Library/Homebrew/cmd/switch.rb
@@ -1,3 +1,6 @@
+#:  * `switch` <name> <version>:
+#:    Symlink all of the specific <version> of <name>'s install to Homebrew prefix.
+
 require "formula"
 require "keg"
 require "cmd/link"
diff --git a/Library/Homebrew/cmd/tap-info.rb b/Library/Homebrew/cmd/tap-info.rb
index 683a2848d3..178c344f94 100644
--- a/Library/Homebrew/cmd/tap-info.rb
+++ b/Library/Homebrew/cmd/tap-info.rb
@@ -1,3 +1,15 @@
+#:  * `tap-info` <tap>:
+#:    Display information about <tap>.
+#:
+#:  * `tap-info` `--json=`<version> (`--installed`|<taps>):
+#:    Print a JSON representation of <taps>. Currently the only accepted value
+#:    for <version> is `v1`.
+#:
+#:    Pass `--installed` to get information on installed taps.
+#:
+#:    See the docs for examples of using the JSON:
+#:    <https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md>
+
 require "tap"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/tap-pin.rb b/Library/Homebrew/cmd/tap-pin.rb
index 32249cac22..74e9fae3f3 100644
--- a/Library/Homebrew/cmd/tap-pin.rb
+++ b/Library/Homebrew/cmd/tap-pin.rb
@@ -1,3 +1,7 @@
+#:  * `tap-pin` <tap>:
+#:    Pin <tap>, prioritizing its formulae over core when formula names are supplied
+#:    by the user. See also `tap-unpin`.
+
 require "tap"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/tap-unpin.rb b/Library/Homebrew/cmd/tap-unpin.rb
index dd4b69aaad..7ea2831f29 100644
--- a/Library/Homebrew/cmd/tap-unpin.rb
+++ b/Library/Homebrew/cmd/tap-unpin.rb
@@ -1,3 +1,6 @@
+#:  * `tap-unpin` <tap>:
+#:    Unpin <tap> so its formulae are no longer prioritized. See also `tap-pin`.
+
 require "tap"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/tap.rb b/Library/Homebrew/cmd/tap.rb
index 1bd378d69f..cd785482a6 100644
--- a/Library/Homebrew/cmd/tap.rb
+++ b/Library/Homebrew/cmd/tap.rb
@@ -1,3 +1,36 @@
+#:  * `tap`:
+#:    List all installed taps.
+#:
+#:  * `tap` [`--full`] <user>`/`<repo> [<URL>]:
+#:    Tap a formula repository.
+#:
+#:    With <URL> unspecified, taps a formula repository from GitHub using HTTPS.
+#:    Since so many taps are hosted on GitHub, this command is a shortcut for
+#:    `tap <user>/<repo> https://github.com/<user>/homebrew-<repo>`.
+#:
+#:    With <URL> specified, taps a formula repository from anywhere, using
+#:    any transport protocol that `git` handles. The one-argument form of `tap`
+#:    simplifies but also limits. This two-argument command makes no
+#:    assumptions, so taps can be cloned from places other than GitHub and
+#:    using protocols other than HTTPS, e.g., SSH, GIT, HTTP, FTP(S), RSYNC.
+#:
+#:    By default, the repository is cloned as a shallow copy (`--depth=1`), but
+#:    if `--full` is passed, a full clone will be used. To convert a shallow copy
+#:    to a full copy, you can retap passing `--full` without first untapping.
+#:
+#:    `tap` is re-runnable and exits successfully if there's nothing to do.
+#:    However, retapping with a different <URL> will cause an exception, so first
+#:    `untap` if you need to modify the <URL>.
+#:
+#:  * `tap` `--repair`:
+#:    Migrate tapped formulae from symlink-based to directory-based structure.
+#:
+#:  * `tap` `--list-official`:
+#:    List all official taps.
+#:
+#:  * `tap` `--list-pinned`:
+#:    List all pinned taps.
+
 require "tap"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/test.rb b/Library/Homebrew/cmd/test.rb
index b5a0afe8da..ffb9c169d8 100644
--- a/Library/Homebrew/cmd/test.rb
+++ b/Library/Homebrew/cmd/test.rb
@@ -1,3 +1,17 @@
+#:  * `test` [`--devel`|`--HEAD`] [`--debug`] <formula>:
+#:    A few formulae provide a test method. `brew test` <formula> 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.
+#:
+#:    To test the development or head version of a formula, use `--devel` or
+#:    `--HEAD`.
+#:
+#:    If `--debug` is passed and the test fails, an interactive debugger will be
+#:    launched with access to IRB or a shell inside the temporary test directory.
+#:
+#:    Example: `brew install jruby && brew test jruby`
+
 require "extend/ENV"
 require "formula_assertions"
 require "sandbox"
diff --git a/Library/Homebrew/cmd/uninstall.rb b/Library/Homebrew/cmd/uninstall.rb
index 23e68781e6..62092376db 100644
--- a/Library/Homebrew/cmd/uninstall.rb
+++ b/Library/Homebrew/cmd/uninstall.rb
@@ -1,3 +1,9 @@
+#:  * `uninstall`, `rm`, `remove` [`--force`] <formula>:
+#:    Uninstall <formula>.
+#:
+#:    If `--force` is passed, and there are multiple versions of <formula>
+#:    installed, delete all installed versions.
+
 require "keg"
 require "formula"
 require "migrator"
diff --git a/Library/Homebrew/cmd/unlink.rb b/Library/Homebrew/cmd/unlink.rb
index 8779b2099f..adf0917094 100644
--- a/Library/Homebrew/cmd/unlink.rb
+++ b/Library/Homebrew/cmd/unlink.rb
@@ -1,3 +1,11 @@
+#:  * `unlink` [`--dry-run`] <formula>:
+#:    Remove symlinks for <formula> from the Homebrew prefix. This can be useful
+#:    for temporarily disabling a formula:
+#:    `brew unlink foo && commands && brew link foo`.
+#:
+#:    If `--dry-run` or `-n` is passed, Homebrew will list all files which would
+#:    be unlinked, but will not actually unlink or delete any files.
+
 require "ostruct"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/unlinkapps.rb b/Library/Homebrew/cmd/unlinkapps.rb
index e6e3210856..ba21eed62e 100644
--- a/Library/Homebrew/cmd/unlinkapps.rb
+++ b/Library/Homebrew/cmd/unlinkapps.rb
@@ -1,3 +1,14 @@
+#:  * `unlinkapps` [`--local`] [`--dry-run`] [<formulae>]:
+#:    Remove symlinks created by `brew linkapps` from `/Applications`.
+#:
+#:    If no <formulae> are provided, all linked apps will be removed.
+#:
+#:    If provided, `--local` will remove symlinks from the user's `~/Applications`
+#:    directory instead of the system directory.
+#:
+#:    If `--dry-run` or `-n` is passed, Homebrew will list all symlinks which
+#:    would be removed, but will not actually delete any files.
+
 require "cmd/linkapps"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/unpack.rb b/Library/Homebrew/cmd/unpack.rb
index 68b81bd2f4..f0d7a555b6 100644
--- a/Library/Homebrew/cmd/unpack.rb
+++ b/Library/Homebrew/cmd/unpack.rb
@@ -1,3 +1,14 @@
+#:  * `unpack` [`--git`|`--patch`] [`--destdir=`<path>] <formulae>:
+#:    Unpack the source files for <formulae> into subdirectories of the current
+#:    working directory. If `--destdir=`<path> is given, the subdirectories will
+#:    be created in the directory named by `<path>` instead.
+#:
+#:    If `--patch` is passed, patches for <formulae> will be applied to the
+#:    unpacked source.
+#:
+#:    If `--git` is passed, a Git repository will be initalized in the unpacked
+#:    source. This is useful for creating patches for the software.
+
 require "stringio"
 require "formula"
 
diff --git a/Library/Homebrew/cmd/unpin.rb b/Library/Homebrew/cmd/unpin.rb
index 3b66da03af..4eb476bdf6 100644
--- a/Library/Homebrew/cmd/unpin.rb
+++ b/Library/Homebrew/cmd/unpin.rb
@@ -1,3 +1,7 @@
+#:  * `unpin` <formulae>:
+#:    Unpin <formulae>, allowing them to be upgraded by `brew upgrade`. See also
+#:    `pin`.
+
 require "formula"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/untap.rb b/Library/Homebrew/cmd/untap.rb
index 8f5d7de6ed..be91191b50 100644
--- a/Library/Homebrew/cmd/untap.rb
+++ b/Library/Homebrew/cmd/untap.rb
@@ -1,3 +1,6 @@
+#:  * `untap` <tap>:
+#:    Remove a tapped repository.
+
 require "tap"
 
 module Homebrew
diff --git a/Library/Homebrew/cmd/update.sh b/Library/Homebrew/cmd/update.sh
index 2c04664c39..a0c7cc7e7b 100644
--- a/Library/Homebrew/cmd/update.sh
+++ b/Library/Homebrew/cmd/update.sh
@@ -1,3 +1,9 @@
+#:  * `update` [`--rebase`]:
+#:    Fetch the newest version of Homebrew and all formulae from GitHub using
+#:     `git`(1).
+#:
+#:    If `--rebase` is specified then `git pull --rebase` is used.
+
 brew() {
   "$HOMEBREW_BREW_FILE" "$@"
 }
diff --git a/Library/Homebrew/cmd/upgrade.rb b/Library/Homebrew/cmd/upgrade.rb
index 62ef0bf811..2f8407feb2 100644
--- a/Library/Homebrew/cmd/upgrade.rb
+++ b/Library/Homebrew/cmd/upgrade.rb
@@ -1,3 +1,13 @@
+#:  * `upgrade` [<install-options>] [`--cleanup`] [<formulae>]:
+#:    Upgrade outdated, unpinned brews.
+#:
+#:    Options for the `install` command are also valid here.
+#:
+#:    If `--cleanup` is specified then remove previously installed <formula> version(s).
+#:
+#:    If <formulae> are given, upgrade only the specified brews (but do so even
+#:    if they are pinned; see `pin`, `unpin`).
+
 require "cmd/install"
 require "cleanup"
 
diff --git a/Library/Homebrew/cmd/uses.rb b/Library/Homebrew/cmd/uses.rb
index 28abcf28e3..9bb26a52af 100644
--- a/Library/Homebrew/cmd/uses.rb
+++ b/Library/Homebrew/cmd/uses.rb
@@ -1,3 +1,20 @@
+#:  * `uses` [`--installed`] [`--recursive`] [`--skip-build`] [`--skip-optional`] [`--devel`|`--HEAD`] <formulae>:
+#:    Show the formulae that specify <formulae> as a dependency. When given
+#:    multiple formula arguments, show the intersection of formulae that use
+#:    <formulae>.
+#:
+#:    Use `--recursive` to resolve more than one level of dependencies.
+#:
+#:    If `--installed` is passed, only list installed formulae.
+#:
+#:    By default, `uses` shows all formulae that specify <formulae> as a dependency.
+#:    To skip the `:build` type dependencies, pass `--skip-build`. Similarly, pass
+#:    `--skip-optional` to skip `:optional` dependencies.
+#:
+#:    By default, `uses` shows usages of `formula` by stable builds. To find
+#:    cases where `formula` is used by development or HEAD build, pass
+#:    `--devel` or `--HEAD`.
+
 require "formula"
 
 # `brew uses foo bar` returns formulae that use both foo and bar