Add --help to all developer commands.

Also, flag those that we never want to be in a manpage.

Library/Homebrew/cmd/bottle.rb

@@ -1,3 +1,10 @@
+#: @hide_from_man_page
+#:  * `bottle` [`--verbose`] [`--no-rebuild`] [`--keep-old`] [`--skip-relocation`] [`--root-url=<root_url>`]:
+#:  * `bottle` `--merge` [`--no-commit`] [`--keep-old`] [`--write`]:
+#:
+#:    Generate a bottle (binary package) from a formula installed with
+#:    `--build-bottle`.
+
 require "formula"
 require "utils/bottles"
 require "tab"

Library/Homebrew/cmd/man.rb

@@ -1,3 +1,7 @@
+#: @hide_from_man_page
+#:  * `man`:
+#:    Generate Homebrew's manpages.
+
 require "formula"
 require "erb"
 require "ostruct"

Library/Homebrew/cmd/postinstall.rb

@@ -1,3 +1,6 @@
+#:  * `postinstall` <formula>:
+#:    Rerun the post-install steps for <formula>.
+
 require "sandbox"
 
 module Homebrew

Library/Homebrew/cmd/pull.rb

@@ -1,26 +1,35 @@
-# Gets a patch from a GitHub commit or pull request and applies it to Homebrew.
-# Optionally, installs the formulae changed by the patch.
-#
-# Usage: brew pull [options...] <patch-source> [<patch-source> ...]
-#
-# Each <patch-source> may be one of:
-#   * The ID number of a PR (Pull Request) in the homebrew/core GitHub repo
-#   * The URL of a PR on GitHub, using either the web page or API URL
-#       formats. In this form, the PR may be on homebrew/brew, homebrew/core, or
-#       any tap.
-#   * The URL of a commit on GitHub
-#   * A "brew.sh/job/..." string specifying a testing job ID
-#
-# Options:
-#   --bottle:      Handle bottles, pulling the bottle-update commit and publishing files on Bintray
-#   --bump:        For one-formula PRs, automatically reword commit message to our preferred format
-#   --clean:       Do not rewrite or otherwise modify the commits found in the pulled PR
-#   --ignore-whitespace: Silently ignore whitespace discrepancies when applying diffs
-#   --resolve:     When a patch fails to apply, leave in progress and allow user to
-#                  resolve, instead of aborting
-#   --branch-okay: Do not warn if pulling to a branch besides master (useful for testing)
-#   --no-pbcopy:   Do not copy anything to the system clipboard
-#   --no-publish:  Do not publish bottles to Bintray
+#: @hide_from_man_page
+#: `pull` [`--bottle`] [`--bump`] [`--clean`] [`--ignore-whitespace`] [`--resolve`] [`--branch-okay`] [`--no-pbcopy`] [`--no-publish`] <patch-source> [<patch-source>]
+#:
+#:    Gets a patch from a GitHub commit or pull request and applies it to Homebrew.
+#:    Optionally, installs the formulae changed by the patch.
+#:
+#:
+#:    Each <patch-source> may be one of:
+#:      * The ID number of a PR (Pull Request) in the homebrew/core GitHub
+#:        repository
+#:      * The URL of a PR on GitHub, using either the web page or API URL
+#:        formats. In this form, the PR may be on Homebrew/brew,
+#:        Homebrew/homebrew-core or any tap.
+#:      * The URL of a commit on GitHub
+#:      * A "http://bot.brew.sh/job/..." string specifying a testing job ID
+#:
+#:   If `--bottle` was passed, handle bottles, pulling the bottle-update
+#:   commit and publishing files on Bintray.
+#:   If `--bump` was passed, for one-formula PRs, automatically reword
+#:   commit message to our preferred format.
+#:   If `--clean` was passed, do not rewrite or otherwise modify the
+#:   commits found in the pulled PR.
+#:   If `--ignore-whitespace` was passed, silently ignore whitespace
+#:   discrepancies when applying diffs.
+#:   If `--resolve` was passed, when a patch fails to apply, leave in
+#:   progress and allow user to
+#:                  resolve, instead of aborting.
+#:   If `--branch-okay` was passed, do not warn if pulling to a branch
+#:   besides master (useful for testing).
+#:   If `--no-pbcopy` was passed, do not copy anything to the system
+#    clipboard.
+#:   If `--no-publish` was passed, do not publish bottles to Bintray.
 
 require "net/http"
 require "net/https"

Library/Homebrew/cmd/readall.rb

@@ -1,7 +1,10 @@
-# `brew readall` tries to import all formulae one-by-one.
-# This can be useful for debugging issues across all formulae
-# when making significant changes to formula.rb,
-# or to determine if any current formulae have Ruby issues
+#: @hide_from_man_page
+#:  * `readall` [tap]:
+#:    Import all formulae in a tap (defaults to core tap).
+#:
+#:    This can be useful for debugging issues across all formulae
+#:    when making significant changes to `formula.rb`,
+#:    or to determine if any current formulae have Ruby issues
 
 require "readall"
 

Library/Homebrew/cmd/tap-readme.rb

@@ -1,3 +1,7 @@
+#: @hide_from_man_page
+#:  * `tap_readme` [`-v`] <name>:
+#:    Generate the README.md file for a new tap.
+
 module Homebrew
   def tap_readme
     name = ARGV.first

Library/Homebrew/cmd/update-report.rb

@@ -1,3 +1,7 @@
+#: @hide_from_man_page
+#:  * `update_report`:
+#:    The Ruby implementation of `brew update`. Never called manually.
+
 require "formula_versions"
 require "migrator"
 require "formulary"

Library/Homebrew/dev-cmd/aspell-dictionaries.rb

@@ -1,3 +1,7 @@
+#: @hide_from_man_page
+#:  * `aspell_dictionaries`:
+#:    Generates the new dictionaries for the `aspell` formula.
+
 require "open-uri"
 require "resource"
 require "formula"

Library/Homebrew/dev-cmd/boneyard-formula-pr.rb

@@ -1,10 +1,10 @@
-# Creates a pull request to boneyard a formula.
-#
-# Usage: brew boneyard-formula-pr [options...] <formula-name>
-#
-# Options:
-#   --dry-run:  Print what would be done rather than doing it.
-#   --local:    Perform only local operations (don't push and don't create PR).
+#: @hide_from_man_page
+#:  * `boneyard-formula-pr` [`--dry-run`] [`--local`]  <formula-name>:
+#:    Creates a pull request to boneyard a formula.
+#:
+#:    If `--dry-run` is passed, print what would be done rather than doing it.
+#:
+#:    If `--local` is passed, perform only local operations (i.e. don't push or create PR).
 
 require "formula"
 require "utils/json"

Library/Homebrew/dev-cmd/linkage.rb

@@ -1,16 +1,14 @@
-#
-# Description: check linkage of installed keg
-# Usage:
-#   brew linkage <formulae>
-#
-# Only works on installed formulae. An error is raised if it is run on uninstalled
-# formulae.
-#
-# Options:
-#  --test      - testing version: only display broken libs; exit non-zero if any
-#                breakage was found.
-#  --reverse   - For each dylib the keg references, print the dylib followed by the
-#                binaries which link to it.
+#:  * `linkage` [`--test`] [`--reverse`]  <formula-name>:
+#:    Checks the library links of an installed formula.
+#:
+#:    Only works on installed formulae. An error is raised if it is run on
+#:    uninstalled formulae.
+#:
+#:    If `--test` is passed, only display missing libraries and exit with a
+#:    non-zero exit code if any missing libraries were found.
+#:
+#:    If `--reverse` is passed, print the dylib followed by the binaries
+#:    which link to it for each library the keg references.
 
 require "os/mac/linkage_checker"
 

Library/Homebrew/dev-cmd/mirror.rb

@@ -1,6 +1,6 @@
-# Mirrors the stable URL for a formula on Bintray.
-#
-# Usage: brew mirror <formula> [<formula> ...]
+#: @hide_from_man_page
+#:  * `mirror` [`--test`] <formula-name> [<formula-name> ...]:
+#:    Reuploads the stable URL for a formula to Bintray to use it as a mirror.
 
 module Homebrew
   def mirror

Library/Homebrew/dev-cmd/test-bot.rb

@@ -1,37 +1,81 @@
-# Comprehensively test a formula or pull request.
+#: @hide_from_man_page
+#:  * `test-bot` [options]  <url|formula>:
+#:    Creates a pull request to boneyard a formula.
+#:
+#:    If `--dry-run` is passed, print what would be done rather than doing
+#:    it.
+#:
+#:    If `--local` is passed, perform only local operations (i.e. don't
+#:    push or create PR).
+#:
+#:    If `--keep-logs` is passed, write and keep log files under
+#:    `./brewbot/`.
+#:
+#:    If `--cleanup` is passed, clean all state from the Homebrew
+#:    directory. Use with care!
+#:
+#:    If `--clean-cache` is passed, remove all cached downloads. Use with
+#:    care!
+#:
+#:    If `--skip-setup` is passed, don't check the local system is setup
+#:    correctly.
+#:
+#:    If `--skip-homebrew` is passed, don't check Homebrew's files and
+#:    tests are all valid.
+#:
+#:    If `--junit` is passed, generate a JUnit XML test results file.
+#:
+#:    If `--no-bottle` is passed, run `brew install` without
+#:    `--build-bottle`.
+#:
+#:    If `--keep-old` is passed, run `brew bottle --keep-old` to build new
+#:    bottles for a single platform.
+#:
+#:    If `--skip-relocation` is passed, run
+#:   `brew bottle --skip-relocation` to build new bottles that don't
+#:    require relocation.
+#:
+#:    If `--HEAD` is passed, run `brew install` with `--HEAD`.
+#:
+#:    If `--local` is passed, ask Homebrew to write verbose logs under
+#:    `./logs/` and set `$HOME` to `./home/`.
+#:
+#:    If `--tap=<tap>` is passed, use the `git` repository of the given
+#:    tap.
+#:
+#:    If `--dry-run` is passed, just print commands, don't run them.
+#:
+#:    If `--fail-fast` is passed, immediately exit on a failing step.
+#:
+#:    If `--verbose` is passed, print test step output in real time. Has
+#:    the side effect of passing output as raw bytes instead of
+#:    re-encoding in UTF-8.
+#:
+#:    If `--fast` is passed, don't install any packages, but run e.g.
+#:    `brew audit` anyway.
+#:
+#:    If `--keep-tmp` is passed, keep temporary files written by main
+#:    installs and tests that are run.
+#:
+#:    If `--no-pull` is passed, don't use `brew pull` when possible.
+#:
+#:    If `--coverage` is passed, generate coverage report and send it to
+#:    Coveralls.
+#:
+#:    If `--ci-master` is passed, use the Homebrew master branch CI
+#:    options.
+#:
+#:    If `--ci-pr` is passed, use the Homebrew pull request CI options.
+#:
+#:    If `--ci-testing` is passed, use the Homebrew testing CI options.
+#:
+#:    If `--ci-upload` is passed, use the Homebrew CI bottle upload
+#:    options.
+#:
 #
-# Usage: brew test-bot [options...] <pull-request|formula>
-#
-# Options:
-# --keep-logs:           Write and keep log files under ./brewbot/.
-# --cleanup:             Clean the Homebrew directory. Very dangerous. Use with care.
-# --clean-cache:         Remove all cached downloads. Use with care.
-# --skip-setup:          Don't check the local system is setup correctly.
-# --skip-homebrew:       Don't check Homebrew's files and tests are all valid.
-# --junit:               Generate a JUnit XML test results file.
-# --no-bottle:           Run brew install without --build-bottle.
-# --keep-old:            Run brew bottle --keep-old to build new bottles for a single platform.
-# --skip-relocation:     Run brew bottle --skip-relocation to build new bottles for homebrew/portable.
-# --HEAD:                Run brew install with --HEAD.
-# --local:               Ask Homebrew to write verbose logs under ./logs/ and set HOME to ./home/.
-# --tap=<tap>:           Use the git repository of the given tap.
-# --dry-run:             Just print commands, don't run them.
-# --fail-fast:           Immediately exit on a failing step.
-# --verbose:             Print test step output in realtime. Has the side effect of passing output
-#                        as raw bytes instead of re-encoding in UTF-8.
-# --fast:                Don't install any packages, but run e.g. audit anyway.
-# --keep-tmp:            Keep temporary files written by main installs and tests that are run.
-# --no-pull:             Don't use `brew pull` when possible.
-# --coverage:            Generate coverage report and send it to Coveralls.
-#
-# --ci-master:           Shortcut for Homebrew master branch CI options.
-# --ci-pr:               Shortcut for Homebrew pull request CI options.
-# --ci-testing:          Shortcut for Homebrew testing CI options.
-# --ci-upload:           Homebrew CI bottle upload.
-#
-# Influential environment variables include:
-# TRAVIS_REPO_SLUG: same as --tap
-# GIT_URL: if set to URL of a tap remote, same as --tap
+#:    Influential environment variables include:
+#:    `TRAVIS_REPO_SLUG`: same as `--tap`
+#:    `GIT_URL`: if set to URL of a tap remote, same as `--tap`
 
 require "formula"
 require "utils"

Library/Homebrew/dev-cmd/update-test.rb

@@ -1,12 +1,18 @@
+#: @hide_from_man_page
+#:  * `update-test` [`--commit=<sha1>`] [`--before=<date>`] [`--keep-tmp`]:
+#:    Runs a test of `brew update` with a new repository clone.
+#:
+#:    If no arguments are passed, use `origin/master` as the start commit.
+#:
+#:    If `--commit=<sha1>` is passed, use `<sha1>` as the start commit.
+#:
+#:    If `--before=<date>` is passed, use the commit at `<date>` as the
+#:    start commit.
+#:
+#:    If `--keep-tmp` is passed, retain the temporary directory containing
+#:    the new repository clone.
+
 module Homebrew
-  #
-  # Usage:
-  #    brew update-test                 # using origin/master as start commit
-  #    brew update-test --commit=<sha1> # using <sha1> as start commit
-  #    brew update-test --before=<date> # using commit at <date> as start commit
-  #
-  # Options:
-  #   --keep-tmp      Retain temporary directory containing the new clone
   def update_test
     cd HOMEBREW_REPOSITORY
     start_sha1 = if commit = ARGV.value("commit")

Library/Homebrew/test/test_integration_cmds.rb

@@ -273,10 +273,8 @@ class IntegrationCommandTests < Homebrew::TestCase
                  cmd("help", "cat")) # Internal command (documented, Ruby).
     assert_match(/^brew update /,
                  cmd("help", "update")) # Internal command (documented, Shell).
-    if ARGV.homebrew_developer?
-      assert_match "Example usage:\n",
-                   cmd("help", "test-bot") # Internal developer command (undocumented).
-    end
+    assert_match(/^brew test-bot /,
+                 cmd("help", "test-bot")) # Internal developer command (documented, Ruby).
   end
 
   def test_config

share/doc/homebrew/brew.1.html

@@ -317,6 +317,7 @@ repository's HEAD will be checked for updates when a new stable or devel
 version has been released.</p></dd>
 <dt><code>pin</code> <var>formulae</var></dt><dd><p>Pin the specified <var>formulae</var>, preventing them from being upgraded when
 issuing the <code>brew upgrade</code> command. See also <code>unpin</code>.</p></dd>
+<dt><code>postinstall</code> <var>formula</var></dt><dd><p>Rerun the post-install steps for <var>formula</var>.</p></dd>
 <dt><code>prune</code> [<code>--dry-run</code>]</dt><dd><p>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 <code>/Applications</code> and <code>~/Applications</code> that were previously

share/man/man1/brew-cask.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW\-CASK" "1" "August 2016" "Homebrew" "brew-cask"
+.TH "BREW\-CASK" "1" "September 2016" "Homebrew" "brew-cask"
 .
 .SH "NAME"
 \fBbrew\-cask\fR \- a friendly binary installer for macOS

share/man/man1/brew.1

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BREW" "1" "August 2016" "Homebrew" "brew"
+.TH "BREW" "1" "September 2016" "Homebrew" "brew"
 .
 .SH "NAME"
 \fBbrew\fR \- The missing package manager for OS X
@@ -421,6 +421,10 @@ If \fB\-\-fetch\-HEAD\fR is passed, fetch the upstream repository to detect if t
 Pin the specified \fIformulae\fR, preventing them from being upgraded when issuing the \fBbrew upgrade\fR command\. See also \fBunpin\fR\.
 .
 .TP
+\fBpostinstall\fR \fIformula\fR
+Rerun the post\-install steps for \fIformula\fR\.
+.
+.TP
 \fBprune\fR [\fB\-\-dry\-run\fR]
 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 \fB/Applications\fR and \fB~/Applications\fR that were previously created by \fBbrew linkapps\fR\.
 .