dev-cmd: remove --help headers and tweak docs.

This commit is contained in:
Mike McQuaid 2019-01-30 21:33:03 +00:00
parent 6cb7a00f2d
commit bbea109926
No known key found for this signature in database
GPG Key ID: 48A898132FD8EE70
20 changed files with 29 additions and 341 deletions

View File

@ -1,40 +1,3 @@
#: * `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=`<method>|`--except=`<method>] [`--only-cops=`<cops>|`--except-cops=`<cops>] [<formulae>]:
#: Check <formulae> for Homebrew coding style violations. This should be run
#: before submitting a new formula. Will exit with a non-zero status if any errors
#: are found, which can be useful for implementing pre-commit hooks.
#:
#: If no <formulae> are provided, all of them are checked.
#:
#: If `--strict` is passed, additional checks are run, including RuboCop
#: style checks.
#:
#: If `--fix` is passed, style violations will be
#: automatically fixed using RuboCop's auto-correct feature.
#:
#: If `--online` is passed, additional slower checks that require a network
#: connection are run.
#:
#: If `--new-formula` is passed, various additional checks are run that check
#: if a new formula is eligible for Homebrew. This should be used when creating
#: new formulae and implies `--strict` and `--online`.
#:
#: If `--display-cop-names` is passed, the RuboCop cop name for each violation
#: is included in the output.
#:
#: If `--display-filename` is passed, every line of output is prefixed with the
#: name of the file or formula being audited, to make the output easy to grep.
#:
#: Specifying `--only=`<method> will run only the methods named `audit_`<method>,
#: while `--except=`<method> will skip the methods named `audit_`<method>.
#: For either option <method> should be a comma-separated list.
#:
#: Specifying `--only-cops=`<cops> will check for violations of only the listed
#: RuboCop <cops>, while `--except-cops=`<cops> will skip checking the listed
#: <cops>. For either option <cops> should be a comma-separated list of cop names.
# Undocumented options:
# `-D` activates debugging and profiling of the audit methods (not the same as `--debug`)
require "formula"
require "formula_versions"
require "utils/curl"
@ -53,12 +16,12 @@ module Homebrew
def audit_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`audit` [<options>] <formulae>
`audit` [<options>] <formula>
Check <formulae> for Homebrew coding style violations. This should be run before
Check <formula> for Homebrew coding style violations. This should be run before
submitting a new formula. Will exit with a non-zero status if any errors are
found, which can be useful for implementing pre-commit hooks.
If no <formulae> are provided, all of them are checked.
If no <formula> are provided, all of them are checked.
EOS
switch "--strict",
description: "Run additional style checks, including RuboCop style checks."
@ -93,6 +56,9 @@ module Homebrew
switch :debug
conflicts "--only", "--except"
conflicts "--only-cops", "--except-cops"
# Undocumented options:
# `-D` activates debugging and profiling of the audit methods (not the same as `--debug`)
end
end

View File

@ -1,35 +1,3 @@
#: * `bottle` [`--verbose`] [`--no-rebuild`|`--keep-old`] [`--skip-relocation`] [`--or-later`] [`--root-url=`<URL>] [`--force-core-tap`] [`--json`] <formulae>:
#: Generate a bottle (binary package) from a formula that was installed with
#: `--build-bottle`.
#:
#: If the formula specifies a rebuild version, it will be incremented in the
#: generated DSL. Passing `--keep-old` will attempt to keep it at its original
#: value, while `--no-rebuild` will remove it.
#:
#: If `--verbose` (or `-v`) is passed, print the bottling commands and any warnings
#: encountered.
#:
#: If `--skip-relocation` is passed, do not check if the bottle can be marked
#: as relocatable.
#:
#: If `--root-url` is passed, use the specified <URL> as the root of the
#: bottle's URL instead of Homebrew's default.
#:
#: If `--or-later` is passed, append `_or_later` to the bottle tag.
#:
#: If `--force-core-tap` is passed, build a bottle even if <formula> is not
#: in homebrew/core or any installed taps.
#:
#: If `--json` is passed, write bottle information to a JSON file, which can
#: be used as the argument for `--merge`.
#:
#: * `bottle` `--merge` [`--keep-old`] [`--write` [`--no-commit`]] <bottle_json_files>:
#: Generate a bottle from a `--json` output file and print the new DSL merged
#: into the existing formula.
#:
#: If `--write` is passed, write the changes to the formula file. A new
#: commit will then be generated unless `--no-commit` is passed.
require "formula"
require "utils/bottles"
require "tab"
@ -72,7 +40,7 @@ module Homebrew
def bottle_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`bottle` [<options>] <formulae>
`bottle` [<options>] <formula>
Generate a bottle (binary package) from a formula that was installed with
`--build-bottle`.

View File

@ -1,46 +1,3 @@
#: * `bump-formula-pr` [`--devel`] [`--dry-run` [`--write`]] [`--no-audit`|`--strict`] [`--no-browse] [`--mirror=`<URL>] [`--version=`<version>] [`--message=`<message>] (`--url=`<URL> `--sha256=`<SHA-256>|`--tag=`<tag> `--revision=`<revision>) [<formula>]:
#: Create a pull request to update a formula with a new URL or a new tag.
#:
#: If a <URL> is specified, the <SHA-256> checksum of the new download should
#: also be specified. A best effort to determine the <SHA-256> and <formula>
#: name will be made if either or both values are not supplied by the user.
#:
#: If a <tag> is specified, the Git commit <revision> corresponding to that
#: tag must also be specified.
#:
#: If `--devel` is passed, bump the development rather than stable version.
#: The development spec must already exist.
#:
#: If `--dry-run` is passed, print what would be done rather than doing it.
#:
#: If `--write` is passed along with `--dry-run`, perform a not-so-dry run by
#: making the expected file modifications but not taking any Git actions.
#:
#: If `--no-audit` is passed, don't run `brew audit` before opening the PR.
#:
#: If `--strict` is passed, run `brew audit --strict` before opening the PR.
#:
#: If `--mirror=`<URL> is passed, use the value as a mirror URL.
#:
#: If `--version=`<version> is passed, use the value to override the value
#: parsed from the URL or tag. Note that `--version=0` can be used to delete
#: an existing version override from a formula if it has become redundant.
#:
#: If `--message=`<message> is passed, append <message> to the default PR
#: message.
#:
#: If `--no-browse` is passed, don't pass the `--browse` argument to `hub`
#: which opens the pull request URL in a browser. Instead, output it to the
#: command line.
#:
#: If `--quiet` is passed, don't output replacement messages or warn about
#: duplicate pull requests.
#:
#: *Note:* this command cannot be used to transition a formula from a
#: URL-and-SHA-256 style specification into a tag-and-revision style
#: specification, nor vice versa. It must use whichever style specification
#: the preexisting formula already uses.
require "formula"
require "cli_parser"

View File

@ -1,24 +1,3 @@
#: * `create` [`--autotools`|`--cmake`|`--meson`] [`--no-fetch`] [`--set-name` <name>] [`--set-version` <version>] [`--tap` <user>`/`<repo>] <URL>:
#: 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, see:
#: <https://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 `--meson` is passed, create a basic template for a Meson-style build.
#:
#: If `--no-fetch` is passed, Homebrew will not download <URL> to the cache and
#: will thus not add the SHA-256 to the formula for you, nor will it check
#: the GitHub API for GitHub projects (to fill out its description and homepage).
#:
#: 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.
#:
#: The option `--tap` takes a tap as its argument and generates the formula in
#: the specified tap.
require "formula"
require "formula_creator"
require "missing_formula"

View File

@ -1,9 +1,3 @@
#: * `edit`:
#: Open the Homebrew repository for editing.
#:
#: * `edit` <formula>:
#: Open <formula> in the editor set by `EDITOR` or `HOMEBREW_EDITOR`.
require "formula"
require "cli_parser"
@ -13,7 +7,7 @@ module Homebrew
def edit_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`edit` [<formulae>]
`edit` [<formula>]
Open a formula in the editor set by `EDITOR` or `HOMEBREW_EDITOR`, or open the
Homebrew repository for editing if no <formula> is provided.

View File

@ -1,15 +1,3 @@
#: * `extract` [`--force`] <formula> <tap> [`--version=`<version>]:
#: Look through repository history to find the most recent version of <formula> and
#: create a copy in <tap>`/Formula/`<formula>`@`<version>`.rb`. If the tap is
#: not installed yet, attempt to install/clone the tap before continuing.
#:
#: If `--force` is passed, the file at the destination will be overwritten
#: if it already exists. Otherwise, existing files will be preserved.
#:
#: If an argument is passed through `--version`, <version> of <formula>
#: will be extracted and placed in the destination tap. Otherwise, the most
#: recent version that can be found will be used.
require "cli_parser"
require "utils/git"
require "formulary"

View File

@ -1,6 +1,3 @@
#: * `formula` <formulae>:
#: Display the path where a formula is located.
require "formula"
require "cli_parser"
@ -10,7 +7,7 @@ module Homebrew
def formula_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`formula` <formulae>
`formula` <formula>
Display the path where a formula is located.
EOS

View File

@ -1,11 +1,3 @@
#: * `irb` [`--examples`] [`--pry`]:
#: Enter the interactive Homebrew Ruby shell.
#:
#: If `--examples` is passed, several examples will be shown.
#:
#: If `--pry` is passed or `HOMEBREW_PRY` is set, Pry will be
#: used instead of IRB.
require "cli_parser"
class Symbol

View File

@ -1,15 +1,3 @@
#: * `linkage` [`--test`] [`--reverse`] [<formulae>]:
#: Check the library links for kegs of installed formulae.
#: Raises an error if run on uninstalled formulae.
#:
#: If `--test` is passed, only display missing libraries and exit with a
#: non-zero status if any missing libraries are found.
#:
#: If `--reverse` is passed, for every library that a keg references,
#: print its dylib path followed by the binaries that link to it.
#:
#: If <formulae> are given, check linkage for only the specified brews.
require "cache_store"
require "linkage_checker"
require "cli_parser"
@ -20,7 +8,7 @@ module Homebrew
def linkage_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`linkage` [<options>] [<formulae>]
`linkage` [<options>] [<formula>]
Check the library links for kegs of installed formulae.
Raises an error if run on uninstalled formulae.

View File

@ -1,12 +1,3 @@
#: * `man` [`--fail-if-changed`]:
#: Generate Homebrew's manpages.
#:
#: If `--fail-if-changed` is passed, the command will return a failing
#: status code if changes are detected in the manpage outputs.
#: This can be used for CI to be notified when the manpages are out of date.
#: Additionally, the date used in new manpages will match those in the existing
#: manpages (to allow comparison without factoring in the date).
require "formula"
require "erb"
require "ostruct"

View File

@ -1,7 +1,3 @@
#: @hide_from_man_page
#: * `mirror` <formulae>:
#: Reuploads the stable URL for a formula to Bintray to use it as a mirror.
require "cli_parser"
module Homebrew
@ -10,12 +6,13 @@ module Homebrew
def mirror_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`mirror` <formulae>
`mirror` <formula>
Reuploads the stable URL for a formula to Bintray to use it as a mirror.
EOS
switch :verbose
switch :debug
hide_from_man_page!
end
end

View File

@ -1,19 +1,12 @@
#: * `prof` [<ruby options>]:
#: Run Homebrew with the Ruby profiler.
#:
#: *Example:* `brew prof readall`
module Homebrew
module_function
def prof_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`prof` [<ruby options>]
`prof` <command>
Run Homebrew with the Ruby profiler.
*Example:* `brew prof readall`
Run Homebrew with the Ruby profiler e.g. `brew prof readall`.
EOS
end
end

View File

@ -1,52 +1,3 @@
#: * `pull` [`--bottle`] [`--bump`] [`--clean`] [`--ignore-whitespace`] [`--resolve`] [`--branch-okay`] [`--no-pbcopy`] [`--no-publish`] [`--warn-on-publish-failure`] [`--bintray-org=`<bintray-org>] [`--test-bot-user=`<test-bot-user>] <patch-source> [<patch-source>]:
#: Get a patch from a GitHub commit or pull request and apply it to Homebrew.
#: Optionally, publish updated bottles for 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 "https://jenkins.brew.sh/job/..." string specifying a testing job ID
#:
#: If `--bottle` is passed, handle bottles, pulling the bottle-update
#: commit and publishing files on Bintray.
#:
#: If `--bump` is passed, for one-formula PRs, automatically reword
#: commit message to our preferred format.
#:
#: If `--clean` is passed, do not rewrite or otherwise modify the
#: commits found in the pulled PR.
#:
#: If `--ignore-whitespace` is passed, silently ignore whitespace
#: discrepancies when applying diffs.
#:
#: If `--resolve` is passed, when a patch fails to apply, leave in
#: progress and allow user to resolve, instead of aborting.
#:
#: If `--branch-okay` is passed, do not warn if pulling to a branch
#: besides master (useful for testing).
#:
#: If `--no-pbcopy` is passed, do not copy anything to the system
#: clipboard.
#:
#: If `--no-publish` is passed, do not publish bottles to Bintray.
#:
#: If `--warn-on-publish-failure` was passed, do not exit if there's a
#: failure publishing bottles on Bintray.
#:
#: If `--bintray-org=`<bintray-org> is passed, publish at the provided Bintray
#: organisation.
#:
#: If `--test-bot-user=`<test-bot-user> is passed, pull the bottle block
#: commit from the provided user on GitHub.
require "net/http"
require "net/https"
require "json"
@ -74,23 +25,13 @@ module Homebrew
def pull_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`pull` [<options>] <patch sources>
`pull` [<options>] <patch>
Get a patch from a GitHub commit or pull request and apply it to Homebrew.
Optionally, publish updated bottles for 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 "https://jenkins.brew.sh/job/..." string specifying a testing job ID
Each <patch> may be the number of a PR in homebrew/core, the URL of a PR
on GitHub, the URL of a commit on GitHub or a "https://jenkins.brew.sh/job/..." testing job URL.
EOS
switch "--bottle",
description: "Handle bottles, pulling the bottle-update commit and publishing files on Bintray."

View File

@ -1,10 +1,3 @@
#: * `release-notes` [`--markdown`] [<previous_tag>] [<end_ref>]:
#: Print the merged pull requests on Homebrew/brew between two Git refs.
#: If no <previous_tag> is provided it defaults to the latest tag.
#: If no <end_ref> is provided it defaults to `origin/master`.
#:
#: If `--markdown` is passed, print as a Markdown list.
require "cli_parser"
module Homebrew

View File

@ -1,8 +1,3 @@
#: * `ruby` [<ruby options>]:
#: Run a Ruby instance with Homebrew's libraries loaded.
#:
#: *Example:* `brew ruby -e "puts :gcc.f.deps"` or `brew ruby script.rb`
require "cli_parser"
module Homebrew
@ -11,11 +6,10 @@ module Homebrew
def ruby_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`ruby` [<ruby options>]
`ruby` [`-e`]:
Run a Ruby instance with Homebrew's libraries loaded.
*Example:* `brew ruby -e "puts :gcc.f.deps"` or `brew ruby script.rb`
Run a Ruby instance with Homebrew's libraries loaded e.g.
`brew ruby -e "puts :gcc.f.deps"` or `brew ruby script.rb`
EOS
switch "-e",
description: "Execute the provided string argument as a script."

View File

@ -1,6 +1,3 @@
#: * `tap-new` <user>`/`<repo>:
#: Generate the template files for a new tap.
require "tap"
require "cli_parser"

View File

@ -1,23 +1,8 @@
#: * `test` [`--devel`|`--HEAD`] [`--debug`] [`--keep-tmp`] <formulae>:
#: Run the test method provided by a formula.
#: There is no standard output or return code, but generally it should notify 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` (or `-d`) is passed and the test fails, an interactive debugger will be
#: launched with access to IRB or a shell inside the temporary test directory.
#:
#: If `--keep-tmp` is passed, the temporary files created for the test are
#: not deleted.
#:
#: *Example:* `brew install jruby && brew test jruby`
require "extend/ENV"
require "formula_assertions"
require "sandbox"
require "timeout"
require "cli_parser"
module Homebrew
module_function
@ -25,7 +10,7 @@ module Homebrew
def test_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`test` [<options>] <formulae>
`test` [<options>] <formula>
Run the test method provided by an installed formula.
There is no standard output or return code, but generally it should notify the

View File

@ -1,20 +1,3 @@
#: * `tests` [`--verbose`] [`--coverage`] [`--generic`] [`--no-compat`] [`--only=`<test_script>[`:`<line_number>]] [`--seed=`<seed>] [`--online`]:
#: Run Homebrew's unit and integration tests. If provided,
#: `--only=`<test_script> runs only <test_script>`_spec.rb`, and `--seed`
#: randomizes tests with the provided value instead of a random seed.
#:
#: If `--verbose` (or `-v`) is passed, print the command that runs the tests.
#:
#: If `--coverage` is passed, also generate code coverage reports.
#:
#: If `--generic` is passed, only run OS-agnostic tests.
#:
#: If `--no-compat` is passed, do not load the compatibility layer when
#: running tests.
#:
#: If `--online` is passed, include tests that use the GitHub API and tests
#: that use any of the taps for official external commands.
require "cli_parser"
require "fileutils"
@ -41,7 +24,7 @@ module Homebrew
description: "Run only <test_script>`_spec.rb`. Appending `:`<line_number> will start at a "\
"specific line."
flag "--seed=",
description: "Randomize tests with the provided <value> instead of a random seed."
description: "Randomise tests with the provided <value> instead of a random seed."
switch :verbose
switch :debug
end

View File

@ -1,19 +1,3 @@
#: * `update-test` [`--commit=`<commit>] [`--before=`<date>] [`--to-tag`] [`--keep-tmp`]:
#: Run a test of `brew update` with a new repository clone.
#:
#: If no arguments are passed, use `origin/master` as the start commit.
#:
#: If `--commit=`<commit> is passed, use <commit> as the start commit.
#:
#: If `--before=`<date> is passed, use the commit at <date> as the
#: start commit.
#:
#: If `--to-tag` is passed, set `HOMEBREW_UPDATE_TO_TAG` to test updating
#: between tags.
#:
#: If `--keep-tmp` is passed, retain the temporary directory containing
#: the new repository clone.
require "cli_parser"
module Homebrew

View File

@ -1,13 +1,10 @@
#: * `vendor-gems`:
#: Install and commit Homebrew's vendored gems.
require "formula"
require "cli_parser"
module Homebrew
module_function
def vendor_gems
def vendor_gems_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`vendor-gems`
@ -15,7 +12,11 @@ module Homebrew
Install and commit Homebrew's vendored gems.
EOS
switch :debug
end.parse
end
end
def vendor_gems
vendor_gems_args.parse
Homebrew.install_bundler!