diff --git a/Library/Homebrew/dev-cmd/audit.rb b/Library/Homebrew/dev-cmd/audit.rb index a33b4c05fb..759bae9428 100644 --- a/Library/Homebrew/dev-cmd/audit.rb +++ b/Library/Homebrew/dev-cmd/audit.rb @@ -1,6 +1,7 @@ #: * `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=`|`--except=`] [`--only-cops=`|`--except-cops=`] []: -#: Check for Homebrew coding style violations. This should be -#: run before submitting a new formula. +#: Check 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 are provided, all of them are checked. #: @@ -23,16 +24,13 @@ #: 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. #: -#: Passing `--only=` will run only the methods named `audit_`, -#: while `--except=` will skip the methods named `audit_`. +#: Specifying `--only=` will run only the methods named `audit_`, +#: while `--except=` will skip the methods named `audit_`. #: For either option should be a comma-separated list. #: -#: Passing `--only-cops=` will check for violations of only the listed +#: Specifying `--only-cops=` will check for violations of only the listed #: RuboCop , while `--except-cops=` will skip checking the listed #: . For either option should be a comma-separated list of cop names. -#: -#: `audit` exits with a non-zero status if any errors are found. This is useful, -#: for instance, for implementing pre-commit hooks. # Undocumented options: # `-D` activates debugging and profiling of the audit methods (not the same as `--debug`) @@ -55,14 +53,15 @@ module Homebrew def audit_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `audit` [] : + `audit` [] - Check for Homebrew coding style violations. This should be - run before submitting a new formula. + Check 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 are provided, all of them are checked. EOS switch "--strict", - description: "Run additional style checks, including Rubocop style checks." + description: "Run additional style checks, including RuboCop style checks." switch "--online", description: "Run additional slower style checks that require a network connection." switch "--new-formula", @@ -74,24 +73,26 @@ module Homebrew switch "--display-cop-names", description: "Include the RuboCop cop name for each violation in the output." switch "--display-filename", - description: "Prefix everyline of output with name of the file or formula being audited, to "\ + description: "Prefix every line of output with name of the file or formula being audited, to "\ "make output easy to grep." switch "-D", "--audit-debug", - description: "Activates debugging and profiling" + description: "Enable debugging and profiling of audit methods." comma_array "--only", - description: "Passing `--only=` will run only the methods named audit_. "\ - " should be a comma-separated list." + description: "Specify a comma-separated list to only run the methods named "\ + "`audit_`." comma_array "--except", - description: "Passing `--except=` will run only the methods named audit_, "\ - " should be a comma-separated list." + description: "Specify a comma-separated list to skip running the methods named "\ + "`audit_`." comma_array "--only-cops", - description: "Passing `--only-cops=` will check for violations of only the listed "\ - "RuboCop cops. should be a comma-separated list of cop names." + description: "Specify a comma-separated list to check for violations of only the listed "\ + "RuboCop cops." comma_array "--except-cops", - description: "Passing `--except-cops=` will skip checking the listed RuboCop cops "\ - "violations. should be a comma-separated list of cop names." + description: "Specify a comma-separated list to skip checking for violations of the listed "\ + "RuboCop cops." switch :verbose switch :debug + conflicts "--only", "--except" + conflicts "--only-cops", "--except-cops" end end @@ -126,7 +127,7 @@ module Homebrew if only_cops && except_cops odie "--only-cops and --except-cops cannot be used simultaneously!" elsif (only_cops || except_cops) && (strict || args.only) - odie "--only-cops/--except-cops and --strict/--only cannot be used simultaneously" + odie "--only-cops/--except-cops and --strict/--only cannot be used simultaneously!" end options = { fix: args.fix?, realpath: true } diff --git a/Library/Homebrew/dev-cmd/bottle.rb b/Library/Homebrew/dev-cmd/bottle.rb index 3f43214f02..6f4c372a31 100644 --- a/Library/Homebrew/dev-cmd/bottle.rb +++ b/Library/Homebrew/dev-cmd/bottle.rb @@ -1,10 +1,10 @@ #: * `bottle` [`--verbose`] [`--no-rebuild`|`--keep-old`] [`--skip-relocation`] [`--or-later`] [`--root-url=`] [`--force-core-tap`] [`--json`] : -#: Generate a bottle (binary package) from a formula installed with +#: 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. +#: 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. @@ -15,7 +15,7 @@ #: If `--root-url` is passed, use the specified 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 `--or-later` is passed, append `_or_later` to the bottle tag. #: #: If `--force-core-tap` is passed, build a bottle even if is not #: in homebrew/core or any installed taps. @@ -72,13 +72,13 @@ module Homebrew def bottle_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `bottle` [] : + `bottle` [] - Generate a bottle (binary package) from a formula installed with + 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. + generated DSL. Passing `--keep-old` will attempt to keep it at its original + value, while `--no-rebuild` will remove it. EOS switch "--skip-relocation", description: "Do not check if the bottle can be marked as relocatable." @@ -87,28 +87,30 @@ module Homebrew switch "--force-core-tap", description: "Build a bottle even if is not in homebrew/core or any installed taps." switch "--no-rebuild", - description: "If the formula specifies a rebuild version, it will be removed in the generated DSL." + description: "If the formula specifies a rebuild version, remove it from the generated DSL." switch "--keep-old", - description: "If the formula specifies a rebuild version, it will attempted to be kept in the "\ - " generated DSL." - switch "--merge", - description: "Generate a bottle from a formula and print the new DSL merged into the "\ - "existing formula." - switch "--write", - description: "Changes will be written to the formula file. A new commit will be generated unless "\ - "`--no-commit` is passed." - switch "--no-commit", - description: "When passed with `--write`, a new commit will not generated while writing changes "\ - "to the formula file.", - depends_on: "--write" + description: "If the formula specifies a rebuild version, attempt to preserve its value in the "\ + "generated DSL." switch "--json", description: "Write bottle information to a JSON file, which can be used as the argument for "\ "`--merge`." + switch "--merge", + description: "Generate an updated bottle block for a formula and optionally merge it into the "\ + "formula file. Instead of a formula name, requires a JSON file generated with "\ + "`brew bottle --json` ." + switch "--write", + depends_on: "--merge", + description: "Write the changes to the formula file. A new commit will be generated unless "\ + "`--no-commit` is passed." + switch "--no-commit", + depends_on: "--write", + description: "When passed with `--write`, a new commit will not generated after writing changes "\ + "to the formula file." flag "--root-url", - description: "Use the specified as the root of the bottle's URL instead of Homebrew's "\ - "default." + description: "Use the specified as the root of the bottle's URL instead of Homebrew's default." switch :verbose switch :debug + conflicts "--no-rebuild", "--keep-old" end end @@ -228,7 +230,7 @@ module Homebrew unless tap = f.tap unless args.force_core_tap? - return ofail "Formula not from core or any taps: #{f.full_name}" + return ofail "Formula not from core or any installed taps: #{f.full_name}" end tap = CoreTap.instance diff --git a/Library/Homebrew/dev-cmd/bump-formula-pr.rb b/Library/Homebrew/dev-cmd/bump-formula-pr.rb index 16f3d24af6..67c5ab484e 100644 --- a/Library/Homebrew/dev-cmd/bump-formula-pr.rb +++ b/Library/Homebrew/dev-cmd/bump-formula-pr.rb @@ -1,11 +1,11 @@ -#: * `bump-formula-pr` [`--devel`] [`--dry-run` [`--write`]] [`--audit`|`--strict`] [`--mirror=`] [`--version=`] [`--message=`] (`--url=` `--sha256=`|`--tag=` `--revision=`) : -#: Creates a pull request to update the formula with a new URL or a new tag. +#: * `bump-formula-pr` [`--devel`] [`--dry-run` [`--write`]] [`--audit`|`--strict`] [`--no-browse] [`--mirror=`] [`--version=`] [`--message=`] (`--url=` `--sha256=`|`--tag=` `--revision=`) []: +#: Create a pull request to update a formula with a new URL or a new tag. #: -#: If a is specified, the checksum of the new download must -#: also be specified. A best effort to determine the and +#: If a is specified, the checksum of the new download should +#: also be specified. A best effort to determine the and #: name will be made if either or both values are not supplied by the user. #: -#: If a is specified, the git commit corresponding to that +#: If a is specified, the Git commit corresponding to that #: tag must also be specified. #: #: If `--devel` is passed, bump the development rather than stable version. @@ -13,8 +13,8 @@ #: #: 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 -#: making the expected file modifications but not taking any git actions. +#: 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 `--audit` is passed, run `brew audit` before opening the PR. #: @@ -24,7 +24,7 @@ #: #: If `--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. +#: an existing version override from a formula if it has become redundant. #: #: If `--message=` is passed, append to the default PR #: message. @@ -36,8 +36,8 @@ #: If `--quiet` is passed, don't output replacement messages or warn about #: duplicate pull requests. #: -#: Note that this command cannot be used to transition a formula from a -#: URL-and-sha256 style specification into a tag-and-revision style +#: *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. @@ -50,57 +50,58 @@ module Homebrew def bump_formula_pr_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `bump-formula-pr` [] : + `bump-formula-pr` [] [] - Creates a pull request to update the formula with a new URL or a new tag. + Create a pull request to update a formula with a new URL or a new tag. - If a is specified, the checksum of the new download must - also be specified. A best effort to determine the and - name will be made if either or both values are not supplied by the user. + If a is specified, the checksum of the new download should also + be specified. A best effort to determine the and name will + be made if either or both values are not supplied by the user. - If a is specified, the git commit corresponding to that - tag must also be specified. + If a is specified, the Git commit corresponding to that tag + must also be specified. - Note that this command cannot be used to transition a formula from a - URL-and-sha256 style specification into a tag-and-revision style - specification, nor vice versa. It must use whichever style specification - the preexisting formula already uses. + *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. EOS switch "--devel", description: "Bump the development rather than stable version. The development spec must already exist." switch "-n", "--dry-run", description: "Print what would be done rather than doing it." switch "--write", - description: "When passed along with `--dry-run`, perform a not-so-dry run making the expected "\ - "file modifications but not taking any git actions." + depends_on: "--dry-run", + description: "When passed along with `--dry-run`, perform a not-so-dry run by making the expected "\ + "file modifications but not taking any Git actions." switch "--audit", description: "Run `brew audit` before opening the PR." switch "--strict", description: "Run `brew audit --strict` before opening the PR." switch "--no-browse", - description: "Output the pull request URL instead of opening in a browser" - flag "--url=", - description: "Provide new for the formula. If a is specified, the "\ - "checksum of the new download must also be specified." - flag "--revision=", - description: "Specify the new git commit corresponding to a specified ." - flag "--tag=", - required_for: "--revision=", - description: "Specify the new git commit for the formula." - flag "--sha256=", - depends_on: "--url=", - description: "Specify the checksum of new download." - flag "--mirror=", + description: "Print the pull request URL instead of opening in a browser." + flag "--mirror=", description: "Use the provided as a mirror URL." - flag "--version=", + flag "--version=", description: "Use the provided 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 "\ + "that `--version=0` can be used to delete an existing version override from a "\ "formula if it has become redundant." - flag "--message=", - description: "Append provided to the default PR message." + flag "--message=", + description: "Append the provided to the default PR message." + flag "--url=", + description: "Specify the for the new download. If a is specified, the "\ + "checksum of the new download should also be specified." + flag "--sha256=", + depends_on: "--url=", + description: "Specify the checksum of the new download." + flag "--tag=", + description: "Specify the new git commit for the formula." + flag "--revision=", + required_for: "--tag=", + description: "Specify the new git commit corresponding to a specified ." - switch :quiet switch :force + switch :quiet switch :verbose switch :debug conflicts "--url", "--tag" @@ -352,7 +353,7 @@ module Homebrew "#{new_formula_version}#{devel_message}' -- #{formula.path}" ohai "git push --set-upstream $HUB_REMOTE #{branch}:#{branch}" ohai "create pull request with GitHub API" - ohai "git checkout -" + ohai "git checkout --quiet -" else begin diff --git a/Library/Homebrew/dev-cmd/create.rb b/Library/Homebrew/dev-cmd/create.rb index 4d65c8f416..69b3a7e12e 100644 --- a/Library/Homebrew/dev-cmd/create.rb +++ b/Library/Homebrew/dev-cmd/create.rb @@ -1,17 +1,17 @@ -#: * `create` [`--autotools`|`--cmake`|`--meson`] [`--no-fetch`] [`--set-name` ] [`--set-version` ] [`--tap` `/`]: +#: * `create` [`--autotools`|`--cmake`|`--meson`] [`--no-fetch`] [`--set-name` ] [`--set-version` ] [`--tap` `/`] : #: Generate a formula for the downloadable file at 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 -#: . +#: formula serves as a simple example. For the complete API, see: +#: #: #: 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 to the cache and -#: will thus not add the SHA256 to the formula for you. It will also not check -#: the GitHub API for GitHub projects (to fill out the description and homepage). +#: 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. @@ -30,13 +30,13 @@ module Homebrew def create_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `create` []: + `create` [] Generate a formula for the downloadable file at 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 - . + 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: + EOS switch "--autotools", description: "Create a basic template for an Autotools-style build." @@ -45,17 +45,17 @@ module Homebrew switch "--meson", description: "Create a basic template for a Meson-style build." switch "--no-fetch", - description: "Homebrew will not download to the cache and will thus not add the SHA256 to "\ - "the formula for you. It will also not check the GitHub API for GitHub projects "\ - "(to fill out the description and homepage)." - switch "--HEAD" + description: "Homebrew will not download 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)." + switch "--HEAD", + description: "Indicate that points to the package's repository rather than a file." flag "--set-name=", - description: "Set the provided name of the package you are creating." + description: "Set the name of the new formula to the provided ." flag "--set-version=", - description: "Set the provided version of the package you are creating." + description: "Set the version of the new formula to the provided ." flag "--tap=", - description: "Takes a tap [`/`] as argument and generates the formula in the "\ - "specified tap." + description: "Generate the new formula in the provided tap, specified as `/`." switch :force switch :verbose switch :debug diff --git a/Library/Homebrew/dev-cmd/edit.rb b/Library/Homebrew/dev-cmd/edit.rb index 42d7ecf941..14f0780bfb 100644 --- a/Library/Homebrew/dev-cmd/edit.rb +++ b/Library/Homebrew/dev-cmd/edit.rb @@ -1,8 +1,8 @@ #: * `edit`: -#: Open all of Homebrew for editing. +#: Open the Homebrew repository for editing. #: #: * `edit` : -#: Open in the editor. +#: Open in the editor set by `EDITOR` or `HOMEBREW_EDITOR`. require "formula" require "cli_parser" @@ -13,9 +13,10 @@ module Homebrew def edit_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `edit` : - Open in the editor. Open all of Homebrew for editing if - no is provided. + `edit` [] + + Open a formula in the editor set by `EDITOR` or `HOMEBREW_EDITOR`, or open the + Homebrew repository for editing if no is provided. EOS switch :force switch :verbose @@ -29,7 +30,7 @@ module Homebrew unless (HOMEBREW_REPOSITORY/".git").directory? raise <<~EOS Changes will be lost! - The first time you `brew update', all local changes will be lost, you should + The first time you `brew update', all local changes will be lost; you should thus `brew update' before you `brew edit'! EOS end diff --git a/Library/Homebrew/dev-cmd/extract.rb b/Library/Homebrew/dev-cmd/extract.rb index 3e4813fdd8..0a0ac2787d 100644 --- a/Library/Homebrew/dev-cmd/extract.rb +++ b/Library/Homebrew/dev-cmd/extract.rb @@ -1,7 +1,7 @@ #: * `extract` [`--force`] [`--version=`]: -#: Looks through repository history to find the of and -#: creates a copy in /Formula/@.rb. If the tap is -#: not installed yet, attempts to install/clone the tap before continuing. +#: Look through repository history to find the most recent version of and +#: create a copy in `/Formula/``@``.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. @@ -99,18 +99,17 @@ module Homebrew def extract_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `extract` [] : + `extract` [] - Looks through repository history to find the of and - creates a copy in /Formula/@.rb. If the tap is - not installed yet, attempts to install/clone the tap before continuing. + Look through repository history to find the most recent version of and + create a copy in `/Formula/``@``.rb`. If the tap is not + installed yet, attempt to install/clone the tap before continuing. EOS flag "--version=", - description: "Provided of will be extracted and placed in the destination "\ - "tap. Otherwise, the most recent version that can be found will be used." - switch :debug + description: "Extract the provided of instead of the most recent." switch :force + switch :debug end end @@ -128,7 +127,7 @@ module Homebrew repo = CoreTap.instance.path # Formulae can technically live in "/.rb" or # "/Formula/.rb", but explicitly use the latter for now - # since that is now core tap is structured. + # since that is how the core tap is structured. file = repo/"Formula/#{name}.rb" if args.version @@ -175,7 +174,7 @@ module Homebrew odie <<~EOS Destination formula already exists: #{path} To overwrite it and continue anyways, run: - `brew extract #{name} --version=#{version} --tap=#{destination_tap.name} --force` + brew extract --force --version=#{version} #{name} #{destination_tap.name} EOS end ohai "Overwriting existing formula at #{path}" if ARGV.debug? diff --git a/Library/Homebrew/dev-cmd/formula.rb b/Library/Homebrew/dev-cmd/formula.rb index 904f8e2aa6..43f355f20c 100644 --- a/Library/Homebrew/dev-cmd/formula.rb +++ b/Library/Homebrew/dev-cmd/formula.rb @@ -1,5 +1,5 @@ -#: * `formula` : -#: Display the path where is located. +#: * `formula` : +#: Display the path where a formula is located. require "formula" require "cli_parser" @@ -10,12 +10,12 @@ module Homebrew def formula_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `formula` : + `formula` - Display the path where is located. + Display the path where a formula is located. EOS - switch :debug switch :verbose + switch :debug end end diff --git a/Library/Homebrew/dev-cmd/irb.rb b/Library/Homebrew/dev-cmd/irb.rb index 816ab6047c..b001a89182 100644 --- a/Library/Homebrew/dev-cmd/irb.rb +++ b/Library/Homebrew/dev-cmd/irb.rb @@ -2,8 +2,9 @@ #: 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. +#: +#: If `--pry` is passed or `HOMEBREW_PRY` is set, Pry will be +#: used instead of IRB. require "cli_parser" @@ -25,7 +26,7 @@ module Homebrew def irb_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `irb` []: + `irb` [] Enter the interactive Homebrew Ruby shell. EOS @@ -33,7 +34,7 @@ module Homebrew description: "Show several examples." switch "--pry", env: :pry, - description: "Pry will be used instead of irb if `--pry` is passed or HOMEBREW_PRY is set." + description: "Use Pry instead of IRB. Implied if `HOMEBREW_PRY` is set." end end diff --git a/Library/Homebrew/dev-cmd/linkage.rb b/Library/Homebrew/dev-cmd/linkage.rb index 2feb98f899..3cd56bf629 100644 --- a/Library/Homebrew/dev-cmd/linkage.rb +++ b/Library/Homebrew/dev-cmd/linkage.rb @@ -1,14 +1,12 @@ #: * `linkage` [`--test`] [`--reverse`] []: -#: Checks the library links of installed formulae. -#: -#: Only works on installed formulae. An error is raised if it is run on -#: uninstalled 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 exit code if any missing libraries were found. +#: non-zero status if any missing libraries are found. #: -#: If `--reverse` is passed, print the dylib followed by the binaries -#: which link to it for each library the keg references. +#: If `--reverse` is passed, for every library that a keg references, +#: print its dylib path followed by the binaries that link to it. #: #: If are given, check linkage for only the specified brews. @@ -22,21 +20,19 @@ module Homebrew def linkage_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `linkage` [] : + `linkage` [] [] - Checks the library links of an installed formula. - - Only works on installed formulae. An error is raised if it is run on - uninstalled formulae. + Check the library links for kegs of installed formulae. + Raises an error if run on uninstalled formulae. EOS switch "--test", - description: "Display only missing libraries and exit with a non-zero exit code if any missing "\ - "libraries were found." + description: "Display only missing libraries and exit with a non-zero status if any missing "\ + "libraries are found." switch "--reverse", - description: "Print the dylib followed by the binaries which link to it for each library the keg "\ - "references." + description: "For every library that a keg references, print its dylib path followed by the "\ + "binaries that link to it." switch "--cached", - description: "Print the cached linkage values stored in HOMEBREW_CACHE, set from a previous "\ + description: "Print the cached linkage values stored in `HOMEBREW_CACHE`, set by a previous "\ "`brew linkage` run." switch :verbose switch :debug diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb index d11780923f..45e514de5f 100644 --- a/Library/Homebrew/dev-cmd/man.rb +++ b/Library/Homebrew/dev-cmd/man.rb @@ -16,14 +16,17 @@ require "dev-cmd/bottle" require "dev-cmd/bump-formula-pr" require "dev-cmd/create" require "dev-cmd/edit" +require "dev-cmd/extract" require "dev-cmd/formula" require "dev-cmd/irb" require "dev-cmd/linkage" require "dev-cmd/mirror" +require "dev-cmd/prof" require "dev-cmd/pull" -require "dev-cmd/extract" require "dev-cmd/release-notes" +require "dev-cmd/ruby" require "dev-cmd/tap-new" +require "dev-cmd/test" require "dev-cmd/tests" require "dev-cmd/update-test" @@ -37,7 +40,7 @@ module Homebrew def man_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `man` []: + `man` [] Generate Homebrew's manpages. EOS @@ -47,7 +50,7 @@ module Homebrew "the date used in new manpages will match those in the existing manpages (to allow "\ "comparison without factoring in the date)." switch "--link", - description: "It is now done automatically by `brew update`." + description: "This is now done automatically by `brew update`." end end @@ -220,15 +223,16 @@ module Homebrew end def generate_option_doc(short, long, desc) - "* #{format_short_opt(short)} #{format_long_opt(long)}:" + "\n" + desc + "\n" + comma = (short && long) ? ", " : "" + "* #{format_short_opt(short)}" + comma + "#{format_long_opt(long)}:" + "\n " + desc + "\n" end def format_short_opt(opt) - "`#{opt}`, " unless opt.nil? + "`#{opt}`" unless opt.nil? end def format_long_opt(opt) - "`#{opt}`" + "`#{opt}`" unless opt.nil? end def format_usage_banner(usage_banner) diff --git a/Library/Homebrew/dev-cmd/mirror.rb b/Library/Homebrew/dev-cmd/mirror.rb index a707e1dc7e..fc408cabc7 100644 --- a/Library/Homebrew/dev-cmd/mirror.rb +++ b/Library/Homebrew/dev-cmd/mirror.rb @@ -10,19 +10,19 @@ module Homebrew def mirror_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `mirror` : + `mirror` Reuploads the stable URL for a formula to Bintray to use it as a mirror. EOS - switch :debug switch :verbose + switch :debug end end def mirror mirror_args.parse - odie "This command requires at least formula argument!" if ARGV.named.empty? + odie "This command requires at least one formula argument!" if ARGV.named.empty? bintray_user = ENV["HOMEBREW_BINTRAY_USER"] bintray_key = ENV["HOMEBREW_BINTRAY_KEY"] diff --git a/Library/Homebrew/dev-cmd/prof.rb b/Library/Homebrew/dev-cmd/prof.rb index f2750e83c2..9a573bb68b 100644 --- a/Library/Homebrew/dev-cmd/prof.rb +++ b/Library/Homebrew/dev-cmd/prof.rb @@ -1,11 +1,23 @@ #: * `prof` []: #: Run Homebrew with the Ruby profiler. -#: For example: -#: brew prof readall +#: +#: *Example:* `brew prof readall` module Homebrew module_function + def prof_args + Homebrew::CLI::Parser.new do + usage_banner <<~EOS + `prof` [] + + Run Homebrew with the Ruby profiler. + + *Example:* `brew prof readall` + EOS + end + end + def prof Homebrew.install_gem_setup_path! "ruby-prof" FileUtils.mkdir_p "prof" diff --git a/Library/Homebrew/dev-cmd/pull.rb b/Library/Homebrew/dev-cmd/pull.rb index 1779be9478..b496f3aa19 100644 --- a/Library/Homebrew/dev-cmd/pull.rb +++ b/Library/Homebrew/dev-cmd/pull.rb @@ -1,6 +1,6 @@ #: * `pull` [`--bottle`] [`--bump`] [`--clean`] [`--ignore-whitespace`] [`--resolve`] [`--branch-okay`] [`--no-pbcopy`] [`--no-publish`] [`--warn-on-publish-failure`] [`--bintray-org=`] [`--test-bot-user=`] []: -#: Gets a patch from a GitHub commit or pull request and applies it to Homebrew. -#: Optionally, installs the formulae changed by the 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 may be one of: #: @@ -41,11 +41,11 @@ #: If `--warn-on-publish-failure` was passed, do not exit if there's a #: failure publishing bottles on Bintray. #: -#: If `--bintray-org=` is passed, publish at the given Bintray +#: If `--bintray-org=` is passed, publish at the provided Bintray #: organisation. #: #: If `--test-bot-user=` is passed, pull the bottle block -#: commit from the specified user on GitHub. +#: commit from the provided user on GitHub. require "net/http" require "net/https" @@ -74,12 +74,12 @@ module Homebrew def pull_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `pull` [] : + `pull` [] - Gets a patch from a GitHub commit or pull request and applies it to Homebrew. - Optionally, installs the formulae changed by the 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 may be one of: + Each may be one of: ~ The ID number of a PR (pull request) in the homebrew/core GitHub repository @@ -112,9 +112,9 @@ module Homebrew switch "--warn-on-publish-failure", description: "Do not exit if there's a failure publishing bottles on Bintray." flag "--bintray-org=", - description: "Publish at the given Bintray organisation." + description: "Publish bottles at the provided Bintray ." flag "--test-bot-user=", - description: "Pull the bottle block commit from the specified user on GitHub." + description: "Pull the bottle block commit from the provided on GitHub." switch :verbose switch :debug end diff --git a/Library/Homebrew/dev-cmd/release-notes.rb b/Library/Homebrew/dev-cmd/release-notes.rb index 2a990a8617..2c3711c1c3 100644 --- a/Library/Homebrew/dev-cmd/release-notes.rb +++ b/Library/Homebrew/dev-cmd/release-notes.rb @@ -1,9 +1,9 @@ #: * `release-notes` [`--markdown`] [] []: -#: Output the merged pull requests on Homebrew/brew between two Git refs. +#: Print the merged pull requests on Homebrew/brew between two Git refs. #: If no is provided it defaults to the latest tag. #: If no is provided it defaults to `origin/master`. #: -#: If `--markdown` is passed, output as a Markdown list. +#: If `--markdown` is passed, print as a Markdown list. require "cli_parser" @@ -13,14 +13,14 @@ module Homebrew def release_notes_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `release-notes` [] [] []: + `release-notes` [] [] [] - Output the merged pull requests on Homebrew/brew between two Git refs. + Print the merged pull requests on Homebrew/brew between two Git refs. If no is provided it defaults to the latest tag. If no is provided it defaults to `origin/master`. EOS switch "--markdown", - description: "Output as a Markdown list." + description: "Print as a Markdown list." end end diff --git a/Library/Homebrew/dev-cmd/ruby.rb b/Library/Homebrew/dev-cmd/ruby.rb index f658529e07..35a4eb1c5c 100644 --- a/Library/Homebrew/dev-cmd/ruby.rb +++ b/Library/Homebrew/dev-cmd/ruby.rb @@ -1,13 +1,32 @@ #: * `ruby` []: #: Run a Ruby instance with Homebrew's libraries loaded. -#: For example: -# brew ruby -e "puts :gcc.f.deps" -# brew ruby script.rb +#: +#: *Example:* `brew ruby -e "puts :gcc.f.deps"` or `brew ruby script.rb` + +require "cli_parser" module Homebrew module_function + def ruby_args + Homebrew::CLI::Parser.new do + usage_banner <<~EOS + `ruby` [] + + Run a Ruby instance with Homebrew's libraries loaded. + + *Example:* `brew ruby -e "puts :gcc.f.deps"` or `brew ruby script.rb` + EOS + switch "-e", + description: "Execute the provided string argument as a script." + switch :verbose + switch :debug + end + end + def ruby + ruby_args.parse + exec ENV["HOMEBREW_RUBY_PATH"], "-I", $LOAD_PATH.join(File::PATH_SEPARATOR), "-rglobal", "-rdev-cmd/irb", *ARGV end end diff --git a/Library/Homebrew/dev-cmd/tap-new.rb b/Library/Homebrew/dev-cmd/tap-new.rb index 92ff6a40b9..e227fee242 100644 --- a/Library/Homebrew/dev-cmd/tap-new.rb +++ b/Library/Homebrew/dev-cmd/tap-new.rb @@ -7,23 +7,15 @@ require "cli_parser" module Homebrew module_function - def write_path(tap, filename, content) - path = tap.path/filename - tap.path.mkpath - raise "#{path} already exists" if path.exist? - - path.write content - end - def tap_new_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `tap-new` /: + `tap-new` `/` Generate the template files for a new tap. EOS - switch :debug switch :verbose + switch :debug end end @@ -84,4 +76,12 @@ module Homebrew YAML write_path(tap, ".travis.yml", travis) end + + def write_path(tap, filename, content) + path = tap.path/filename + tap.path.mkpath + raise "#{path} already exists" if path.exist? + + path.write content + end end diff --git a/Library/Homebrew/dev-cmd/test.rb b/Library/Homebrew/dev-cmd/test.rb index 7eadd67598..1198bd73d3 100644 --- a/Library/Homebrew/dev-cmd/test.rb +++ b/Library/Homebrew/dev-cmd/test.rb @@ -1,8 +1,7 @@ -#: * `test` [`--devel`|`--HEAD`] [`--debug`] [`--keep-tmp`] : -#: Most 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. +#: * `test` [`--devel`|`--HEAD`] [`--debug`] [`--keep-tmp`] : +#: 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`. @@ -13,7 +12,7 @@ #: If `--keep-tmp` is passed, the temporary files created for the test are #: not deleted. #: -#: Example: `brew install jruby && brew test jruby` +#: *Example:* `brew install jruby && brew test jruby` require "extend/ENV" require "formula_assertions" @@ -23,6 +22,28 @@ require "timeout" module Homebrew module_function + def test_args + Homebrew::CLI::Parser.new do + usage_banner <<~EOS + `test` [] + + Run the test method provided by an installed formula. + There is no standard output or return code, but generally it should notify the + user if something is wrong with the installed formula. + + *Example:* `brew install jruby && brew test jruby` + EOS + switch "--devel", + description: "Test the development version of a formula." + switch "--HEAD", + description: "Test the head version of a formula." + switch "--keep-tmp", + description: "Keep the temporary files created for the test." + switch :verbose + switch :debug + end + end + def test raise FormulaUnspecifiedError if ARGV.named.empty? diff --git a/Library/Homebrew/dev-cmd/tests.rb b/Library/Homebrew/dev-cmd/tests.rb index add193d968..2d0e5b3ffa 100644 --- a/Library/Homebrew/dev-cmd/tests.rb +++ b/Library/Homebrew/dev-cmd/tests.rb @@ -1,6 +1,6 @@ -#: * `tests` [`--verbose`] [`--coverage`] [`--generic`] [`--no-compat`] [`--only=`[`:`]] [`--seed=`] [`--online`] [`--official-cmd-taps`]: +#: * `tests` [`--verbose`] [`--coverage`] [`--generic`] [`--no-compat`] [`--only=`[`:`]] [`--seed=`] [`--online`]: #: Run Homebrew's unit and integration tests. If provided, -#: `--only=` runs only _spec.rb, and `--seed` +#: `--only=` runs only `_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. @@ -24,25 +24,24 @@ module Homebrew def tests_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `tests` []: + `tests` [] - Run Homebrew's unit and integration tests. If provided, - `--only=` runs only _spec.rb, and `--seed` - randomizes tests with the provided value instead of a random seed. + Run Homebrew's unit and integration tests. EOS switch "--coverage", description: "Generate code coverage reports." switch "--generic", - description: "Run only OS-agnostic tests." + description: "Run only OS-agnostic tests." switch "--no-compat", description: "Do not load the compatibility layer when running tests." switch "--online", description: "Include tests that use the GitHub API and tests that use any of the taps for "\ "official external commands." flag "--only=", - description: "Run only _spec.rb" + description: "Run only `_spec.rb`. Appending `:` will start at a "\ + "specific line." flag "--seed=", - description: "Randomizes tests with the provided value instead of a random seed." + description: "Randomize tests with the provided instead of a random seed." switch :verbose switch :debug end diff --git a/Library/Homebrew/dev-cmd/update-test.rb b/Library/Homebrew/dev-cmd/update-test.rb index c9aec5b31a..dadcdef1b7 100644 --- a/Library/Homebrew/dev-cmd/update-test.rb +++ b/Library/Homebrew/dev-cmd/update-test.rb @@ -1,5 +1,5 @@ #: * `update-test` [`--commit=`] [`--before=`] [`--to-tag`] [`--keep-tmp`]: -#: Runs a test of `brew update` with a new repository clone. +#: Run a test of `brew update` with a new repository clone. #: #: If no arguments are passed, use `origin/master` as the start commit. #: @@ -22,10 +22,9 @@ module Homebrew def update_test_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `update-test` []: - - Runs a test of `brew update` with a new repository clone. + `update-test` [] + Run a test of `brew update` with a new repository clone. If no arguments are passed, use `origin/master` as the start commit. EOS switch "--to-tag", diff --git a/Library/Homebrew/test/dev-cmd/bottle_spec.rb b/Library/Homebrew/test/dev-cmd/bottle_spec.rb index b31f557bf2..fceb87b5b0 100644 --- a/Library/Homebrew/test/dev-cmd/bottle_spec.rb +++ b/Library/Homebrew/test/dev-cmd/bottle_spec.rb @@ -8,7 +8,7 @@ describe "brew bottle", :integration_test do (HOMEBREW_CELLAR/"patchelf/1.0/bin").mkpath expect { brew "bottle", "--no-rebuild", testball } - .to output(/Formula not from core or any taps/).to_stderr + .to output(/Formula not from core or any installed taps/).to_stderr .and not_to_output.to_stdout .and be_a_failure diff --git a/docs/Manpage.md b/docs/Manpage.md index 5d8387d9c1..764f348791 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -663,199 +663,201 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note ## DEVELOPER COMMANDS -### `audit` [*`options`*] *`formulae`*: +### `audit` [*`options`*] *`formulae`* -Check *`formulae`* for Homebrew coding style violations. This should be -run before submitting a new formula. +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. -* `--strict`: -Run additional style checks, including Rubocop style checks. -* `--online`: -Run additional slower style checks that require a network connection. -* `--new-formula`: -Run various additional style checks to determine if a new formula is eligible for Homebrew. This should be used when creating new formula and implies `--strict` and `--online`. -* `--fix`: -Fix style violations automatically using RuboCop's auto-correct feature. -* `--display-cop-names`: -Include the RuboCop cop name for each violation in the output. -* `--display-filename`: -Prefix everyline of output with name of the file or formula being audited, to make output easy to grep. -* `-D`, `--audit-debug`: -Activates debugging and profiling -* `--only`: -Passing `--only=`*`method`* will run only the methods named audit_*`method`*. *`method`* should be a comma-separated list. -* `--except`: -Passing `--except=`*`method`* will run only the methods named audit_*`method`*, *`method`* should be a comma-separated list. -* `--only-cops`: -Passing `--only-cops=`*`cops`* will check for violations of only the listed RuboCop cops. *`cops`* should be a comma-separated list of cop names. -* `--except-cops`: -Passing `--except-cops=`*`cops`* will skip checking the listed RuboCop cops violations. *`cops`* should be a comma-separated list of cop names. +* `--strict`: + Run additional style checks, including RuboCop style checks. +* `--online`: + Run additional slower style checks that require a network connection. +* `--new-formula`: + Run various additional style checks to determine if a new formula is eligible for Homebrew. This should be used when creating new formula and implies `--strict` and `--online`. +* `--fix`: + Fix style violations automatically using RuboCop's auto-correct feature. +* `--display-cop-names`: + Include the RuboCop cop name for each violation in the output. +* `--display-filename`: + Prefix every line of output with name of the file or formula being audited, to make output easy to grep. +* `-D`, `--audit-debug`: + Enable debugging and profiling of audit methods. +* `--only`: + Specify a comma-separated *`method`* list to only run the methods named `audit_`*`method`*. +* `--except`: + Specify a comma-separated *`method`* list to skip running the methods named `audit_`*`method`*. +* `--only-cops`: + Specify a comma-separated *`cops`* list to check for violations of only the listed RuboCop cops. +* `--except-cops`: + Specify a comma-separated *`cops`* list to skip checking for violations of the listed RuboCop cops. -### `bottle` [*`options`*] *`formulae`*: +### `bottle` [*`options`*] *`formulae`* -Generate a bottle (binary package) from a formula installed with +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. +generated DSL. Passing `--keep-old` will attempt to keep it at its original +value, while `--no-rebuild` will remove it. -* `--skip-relocation`: -Do not check if the bottle can be marked as relocatable. -* `--or-later`: -Append `_or_later` to the bottle tag. -* `--force-core-tap`: -Build a bottle even if *`formula`* is not in homebrew/core or any installed taps. -* `--no-rebuild`: -If the formula specifies a rebuild version, it will be removed in the generated DSL. -* `--keep-old`: -If the formula specifies a rebuild version, it will attempted to be kept in the generated DSL. -* `--merge`: -Generate a bottle from a formula and print the new DSL merged into the existing formula. -* `--write`: -Changes will be written to the formula file. A new commit will be generated unless `--no-commit` is passed. -* `--no-commit`: -When passed with `--write`, a new commit will not generated while writing changes to the formula file. -* `--json`: -Write bottle information to a JSON file, which can be used as the argument for `--merge`. -* `--root-url`: -Use the specified *`URL`* as the root of the bottle's URL instead of Homebrew's default. +* `--skip-relocation`: + Do not check if the bottle can be marked as relocatable. +* `--or-later`: + Append `_or_later` to the bottle tag. +* `--force-core-tap`: + Build a bottle even if *`formula`* is not in homebrew/core or any installed taps. +* `--no-rebuild`: + If the formula specifies a rebuild version, remove it from the generated DSL. +* `--keep-old`: + If the formula specifies a rebuild version, attempt to preserve its value in the generated DSL. +* `--json`: + Write bottle information to a JSON file, which can be used as the argument for `--merge`. +* `--merge`: + Generate an updated bottle block for a formula and optionally merge it into the formula file. Instead of a formula name, requires a JSON file generated with `brew bottle --json` *`formula`*. +* `--write`: + Write the changes to the formula file. A new commit will be generated unless `--no-commit` is passed. +* `--no-commit`: + When passed with `--write`, a new commit will not generated after writing changes to the formula file. +* `--root-url`: + Use the specified *`URL`* as the root of the bottle's URL instead of Homebrew's default. -### `bump-formula-pr` [*`options`*] *`formula`*: +### `bump-formula-pr` [*`options`*] [*`formula`*] -Creates a pull request to update the formula with a new URL or a new tag. +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 must -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 *`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 a *`tag`* is specified, the Git commit *`revision`* corresponding to that tag +must also be specified. -Note that this command cannot be used to transition a formula from a -URL-and-sha256 style specification into a tag-and-revision style -specification, nor vice versa. It must use whichever style specification -the preexisting formula already uses. +*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. -* `--devel`: -Bump the development rather than stable version. The development spec must already exist. -* `-n`, `--dry-run`: -Print what would be done rather than doing it. -* `--write`: -When passed along with `--dry-run`, perform a not-so-dry run making the expected file modifications but not taking any git actions. -* `--audit`: -Run `brew audit` before opening the PR. -* `--strict`: -Run `brew audit --strict` before opening the PR. -* `--no-browse`: -Output the pull request URL instead of opening in a browser -* `--url`: -Provide new *`URL`* for the formula. If a *`URL`* is specified, the *`sha-256`* checksum of the new download must also be specified. -* `--revision`: -Specify the new git commit *`revision`* corresponding to a specified *`tag`*. -* `--tag`: -Specify the new git commit *`tag`* for the formula. -* `--sha256`: -Specify the *`sha-256`* checksum of new download. -* `--mirror`: -Use the provided *`URL`* as a mirror URL. -* `--version`: -Use the provided *`version`* 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. -* `--message`: -Append provided *`message`* to the default PR message. +* `--devel`: + Bump the development rather than stable version. The development spec must already exist. +* `-n`, `--dry-run`: + Print what would be done rather than doing it. +* `--write`: + When passed along with `--dry-run`, perform a not-so-dry run by making the expected file modifications but not taking any Git actions. +* `--audit`: + Run `brew audit` before opening the PR. +* `--strict`: + Run `brew audit --strict` before opening the PR. +* `--no-browse`: + Print the pull request URL instead of opening in a browser. +* `--mirror`: + Use the provided *`URL`* as a mirror URL. +* `--version`: + Use the provided *`version`* 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. +* `--message`: + Append the provided *`message`* to the default PR message. +* `--url`: + Specify the *`URL`* for the new download. If a *`URL`* is specified, the *`SHA-256`* checksum of the new download should also be specified. +* `--sha256`: + Specify the *`SHA-256`* checksum of the new download. +* `--tag`: + Specify the new git commit *`tag`* for the formula. +* `--revision`: + Specify the new git commit *`revision`* corresponding to a specified *`tag`*. -### `create` *`URL`* [*`options`*]: +### `create` [*`options`*] *`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 have a look at -. +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: + -* `--autotools`: -Create a basic template for an Autotools-style build. -* `--cmake`: -Create a basic template for a CMake-style build. -* `--meson`: -Create a basic template for a Meson-style build. -* `--no-fetch`: -Homebrew will not download *`URL`* to the cache and will thus not add the SHA256 to the formula for you. It will also not check the GitHub API for GitHub projects (to fill out the description and homepage). -* `--HEAD`: -HEAD -* `--set-name`: -Set the provided name of the package you are creating. -* `--set-version`: -Set the provided version of the package you are creating. -* `--tap`: -Takes a tap [*`user`*`/`*`repo`*] as argument and generates the formula in the specified tap. +* `--autotools`: + Create a basic template for an Autotools-style build. +* `--cmake`: + Create a basic template for a CMake-style build. +* `--meson`: + Create a basic template for a Meson-style build. +* `--no-fetch`: + 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). +* `--HEAD`: + Indicate that *`URL`* points to the package's repository rather than a file. +* `--set-name`: + Set the name of the new formula to the provided *`name`*. +* `--set-version`: + Set the version of the new formula to the provided *`version`*. +* `--tap`: + Generate the new formula in the provided tap, specified as *`user`*`/`*`repo`*. -### `edit` *`formula`*: - Open *`formula`* in the editor. Open all of Homebrew for editing if - no *`formula`* is provided. +### `edit` [*`formulae`*] + +Open a formula in the editor set by `EDITOR` or `HOMEBREW_EDITOR`, or open the +Homebrew repository for editing if no *`formula`* is provided. -### `extract` [*`options`*] *`formula`* *`tap`*: +### `extract` [*`options`*] *`formula`* *`tap`* -Looks through repository history to find the *`version`* of *`formula`* and -creates a copy in *`tap`*/Formula/*`formula`*@*`version`*.rb. If the tap is -not installed yet, attempts to install/clone the tap before continuing. +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. -* `--version`: -Provided *`version`* of *`formula`* will be extracted and placed in the destination tap. Otherwise, the most recent version that can be found will be used. +* `--version`: + Extract the provided *`version`* of *`formula`* instead of the most recent. -### `formula` *`formula`*: +### `formula` *`formulae`* -Display the path where *`formula`* is located. +Display the path where a formula is located. -### `irb` [*`options`*]: +### `irb` [*`options`*] Enter the interactive Homebrew Ruby shell. -* `--examples`: -Show several examples. -* `--pry`: -Pry will be used instead of irb if `--pry` is passed or HOMEBREW_PRY is set. +* `--examples`: + Show several examples. +* `--pry`: + Use Pry instead of IRB. Implied if `HOMEBREW_PRY` is set. -### `linkage` [*`options`*] *`formula`*: +### `linkage` [*`options`*] [*`formulae`*] -Checks the library links of an installed formula. +Check the library links for kegs of installed formulae. +Raises an error if run on uninstalled formulae. -Only works on installed formulae. An error is raised if it is run on -uninstalled formulae. +* `--test`: + Display only missing libraries and exit with a non-zero status if any missing libraries are found. +* `--reverse`: + For every library that a keg references, print its dylib path followed by the binaries that link to it. +* `--cached`: + Print the cached linkage values stored in `HOMEBREW_CACHE`, set by a previous `brew linkage` run. -* `--test`: -Display only missing libraries and exit with a non-zero exit code if any missing libraries were found. -* `--reverse`: -Print the dylib followed by the binaries which link to it for each library the keg references. -* `--cached`: -Print the cached linkage values stored in HOMEBREW_CACHE, set from a previous `brew linkage` run. - -### `man` [*`options`*]: +### `man` [*`options`*] Generate Homebrew's manpages. -* `--fail-if-changed`: -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). -* `--link`: -It is now done automatically by `brew update`. +* `--fail-if-changed`: + 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). +* `--link`: + This is now done automatically by `brew update`. -### `mirror` *`formulae`*: +### `mirror` *`formulae`* Reuploads the stable URL for a formula to Bintray to use it as a mirror. - * `prof` [*`ruby options`*]: - Run Homebrew with the Ruby profiler. - For example: - brew prof readall +### `prof` [*`ruby options`*] -### `pull` [*`options`*] *`formula`*: +Run Homebrew with the Ruby profiler. -Gets a patch from a GitHub commit or pull request and applies it to Homebrew. -Optionally, installs the formulae changed by the patch. +*Example:* `brew prof readall` -Each *`patch-source`* may be one of: + +### `pull` [*`options`*] *`patch sources`* + +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 @@ -868,113 +870,113 @@ Each *`patch-source`* may be one of: ~ A "https://jenkins.brew.sh/job/..." string specifying a testing job ID -* `--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. -* `--warn-on-publish-failure`: -Do not exit if there's a failure publishing bottles on Bintray. -* `--bintray-org`: -Publish at the given Bintray organisation. -* `--test-bot-user`: -Pull the bottle block commit from the specified user on GitHub. +* `--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. +* `--warn-on-publish-failure`: + Do not exit if there's a failure publishing bottles on Bintray. +* `--bintray-org`: + Publish bottles at the provided Bintray *`organisation`*. +* `--test-bot-user`: + Pull the bottle block commit from the provided *`user`* on GitHub. -### `release-notes` [*`options`*] [*`previous_tag`*] [*`end_ref`*]: +### `release-notes` [*`options`*] [*`previous_tag`*] [*`end_ref`*] -Output the merged pull requests on Homebrew/brew between two Git refs. +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`. -* `--markdown`: -Output as a Markdown list. +* `--markdown`: + Print as a Markdown list. - * `ruby` [*`ruby options`*]: - Run a Ruby instance with Homebrew's libraries loaded. - For example: +### `ruby` [*`ruby options`*] -### `tap-new` *`user`*/*`repo`*: +Run a Ruby instance with Homebrew's libraries loaded. + +*Example:* `brew ruby -e "puts :gcc.f.deps"` or `brew ruby script.rb` + +* `-e`: + Execute the provided string argument as a script. + +### `tap-new` *`user`*`/`*`repo`* Generate the template files for a new tap. - * `test` [`--devel`|`--HEAD`] [`--debug`] [`--keep-tmp`] *`formula`*: - Most 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. +### `test` [*`options`*] *`formulae`* - To test the development or head version of a formula, use `--devel` or - `--HEAD`. +Run the test method provided by an installed formula. +There is no standard output or return code, but generally it should notify the +user if something is wrong with the installed formula. - 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. +*Example:* `brew install jruby && brew test jruby` - If `--keep-tmp` is passed, the temporary files created for the test are - not deleted. +* `--devel`: + Test the development version of a formula. +* `--HEAD`: + Test the head version of a formula. +* `--keep-tmp`: + Keep the temporary files created for the test. - Example: `brew install jruby && brew test jruby` +### `tests` [*`options`*] -### `tests` [*`options`*]: +Run Homebrew's unit and integration tests. -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. +* `--coverage`: + Generate code coverage reports. +* `--generic`: + Run only OS-agnostic tests. +* `--no-compat`: + Do not load the compatibility layer when running tests. +* `--online`: + Include tests that use the GitHub API and tests that use any of the taps for official external commands. +* `--only`: + Run only *`test_script`*`_spec.rb`. Appending `:`*`line_number`* will start at a specific line. +* `--seed`: + Randomize tests with the provided *`value`* instead of a random seed. -* `--coverage`: -Generate code coverage reports. -* `--generic`: -Run only OS-agnostic tests. -* `--no-compat`: -Do not load the compatibility layer when running tests. -* `--online`: -Include tests that use the GitHub API and tests that use any of the taps for official external commands. -* `--only`: -Run only *`test_script`*_spec.rb -* `--seed`: -Randomizes tests with the provided value instead of a random seed. - -### `update-test` [*`options`*]: - -Runs a test of `brew update` with a new repository clone. +### `update-test` [*`options`*] +Run a test of `brew update` with a new repository clone. If no arguments are passed, use `origin/master` as the start commit. -* `--to-tag`: -Set `HOMEBREW_UPDATE_TO_TAG` to test updating between tags. -* `--keep-tmp`: -Retain the temporary directory containing the new repository clone. -* `--commit`: -Use provided *`commit`* as the start commit. -* `--before`: -Use the commit at provided *`date`* as the start commit. +* `--to-tag`: + Set `HOMEBREW_UPDATE_TO_TAG` to test updating between tags. +* `--keep-tmp`: + Retain the temporary directory containing the new repository clone. +* `--commit`: + Use provided *`commit`* as the start commit. +* `--before`: + Use the commit at provided *`date`* as the start commit. ## GLOBAL OPTIONS These options are applicable across all sub-commands. -* `-q`, `--quiet`: -Suppress any warnings. +* `-q`, `--quiet`: + Suppress any warnings. -* `-v`, `--verbose`: -Make some output more verbose. +* `-v`, `--verbose`: + Make some output more verbose. -* `-d`, `--debug`: -Display any debugging information. +* `-d`, `--debug`: + Display any debugging information. -* `-f`, `--force`: -Override warnings and enable potentially unsafe operations. +* `-f`, `--force`: + Override warnings and enable potentially unsafe operations. ## OFFICIAL EXTERNAL COMMANDS diff --git a/manpages/brew.1 b/manpages/brew.1 index 817dfa0df4..af285a9e91 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -676,12 +676,12 @@ Print the version number of Homebrew to standard output and exit\. . .SH "DEVELOPER COMMANDS" . -.SS "\fBaudit\fR [\fIoptions\fR] \fIformulae\fR:" -Check \fIformulae\fR for Homebrew coding style violations\. This should be run before submitting a new formula\. If no \fIformulae\fR are provided, all of them are checked\. +.SS "\fBaudit\fR [\fIoptions\fR] \fIformulae\fR" +Check \fIformulae\fR 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 \fIformulae\fR are provided, all of them are checked\. . .TP \fB\-\-strict\fR -Run additional style checks, including Rubocop style checks\. +Run additional style checks, including RuboCop style checks\. . .TP \fB\-\-online\fR @@ -701,30 +701,30 @@ Include the RuboCop cop name for each violation in the output\. . .TP \fB\-\-display\-filename\fR -Prefix everyline of output with name of the file or formula being audited, to make output easy to grep\. +Prefix every line of output with name of the file or formula being audited, to make output easy to grep\. . .TP \fB\-D\fR, \fB\-\-audit\-debug\fR -Activates debugging and profiling +Enable debugging and profiling of audit methods\. . .TP \fB\-\-only\fR -Passing \fB\-\-only=\fR\fImethod\fR will run only the methods named audit_\fImethod\fR\. \fImethod\fR should be a comma\-separated list\. +Specify a comma\-separated \fImethod\fR list to only run the methods named \fBaudit_\fR\fImethod\fR\. . .TP \fB\-\-except\fR -Passing \fB\-\-except=\fR\fImethod\fR will run only the methods named audit_\fImethod\fR, \fImethod\fR should be a comma\-separated list\. +Specify a comma\-separated \fImethod\fR list to skip running the methods named \fBaudit_\fR\fImethod\fR\. . .TP \fB\-\-only\-cops\fR -Passing \fB\-\-only\-cops=\fR\fIcops\fR will check for violations of only the listed RuboCop cops\. \fIcops\fR should be a comma\-separated list of cop names\. +Specify a comma\-separated \fIcops\fR list to check for violations of only the listed RuboCop cops\. . .TP \fB\-\-except\-cops\fR -Passing \fB\-\-except\-cops=\fR\fIcops\fR will skip checking the listed RuboCop cops violations\. \fIcops\fR should be a comma\-separated list of cop names\. +Specify a comma\-separated \fIcops\fR list to skip checking for violations of the listed RuboCop cops\. . -.SS "\fBbottle\fR [\fIoptions\fR] \fIformulae\fR:" -Generate a bottle (binary package) from a formula installed with \fB\-\-build\-bottle\fR\. If the formula specifies a rebuild version, it will be incremented in the generated DSL\. Passing \fB\-\-keep\-old\fR will attempt to keep it at its original value, while \fB\-\-no\-rebuild\fR will remove it\. +.SS "\fBbottle\fR [\fIoptions\fR] \fIformulae\fR" +Generate a bottle (binary package) from a formula that was installed with \fB\-\-build\-bottle\fR\. If the formula specifies a rebuild version, it will be incremented in the generated DSL\. Passing \fB\-\-keep\-old\fR will attempt to keep it at its original value, while \fB\-\-no\-rebuild\fR will remove it\. . .TP \fB\-\-skip\-relocation\fR @@ -740,43 +740,43 @@ Build a bottle even if \fIformula\fR is not in homebrew/core or any installed ta . .TP \fB\-\-no\-rebuild\fR -If the formula specifies a rebuild version, it will be removed in the generated DSL\. +If the formula specifies a rebuild version, remove it from the generated DSL\. . .TP \fB\-\-keep\-old\fR -If the formula specifies a rebuild version, it will attempted to be kept in the generated DSL\. -. -.TP -\fB\-\-merge\fR -Generate a bottle from a formula and print the new DSL merged into the existing formula\. -. -.TP -\fB\-\-write\fR -Changes will be written to the formula file\. A new commit will be generated unless \fB\-\-no\-commit\fR is passed\. -. -.TP -\fB\-\-no\-commit\fR -When passed with \fB\-\-write\fR, a new commit will not generated while writing changes to the formula file\. +If the formula specifies a rebuild version, attempt to preserve its value in the generated DSL\. . .TP \fB\-\-json\fR Write bottle information to a JSON file, which can be used as the argument for \fB\-\-merge\fR\. . .TP +\fB\-\-merge\fR +Generate an updated bottle block for a formula and optionally merge it into the formula file\. Instead of a formula name, requires a JSON file generated with \fBbrew bottle \-\-json\fR \fIformula\fR\. +. +.TP +\fB\-\-write\fR +Write the changes to the formula file\. A new commit will be generated unless \fB\-\-no\-commit\fR is passed\. +. +.TP +\fB\-\-no\-commit\fR +When passed with \fB\-\-write\fR, a new commit will not generated after writing changes to the formula file\. +. +.TP \fB\-\-root\-url\fR Use the specified \fIURL\fR as the root of the bottle\'s URL instead of Homebrew\'s default\. . -.SS "\fBbump\-formula\-pr\fR [\fIoptions\fR] \fIformula\fR:" -Creates a pull request to update the formula with a new URL or a new tag\. +.SS "\fBbump\-formula\-pr\fR [\fIoptions\fR] [\fIformula\fR]" +Create a pull request to update a formula with a new URL or a new tag\. . .P -If a \fIURL\fR is specified, the \fIsha\-256\fR checksum of the new download must also be specified\. A best effort to determine the \fIsha\-256\fR and \fIformula\fR name will be made if either or both values are not supplied by the user\. +If a \fIURL\fR is specified, the \fISHA\-256\fR checksum of the new download should also be specified\. A best effort to determine the \fISHA\-256\fR and \fIformula\fR name will be made if either or both values are not supplied by the user\. . .P -If a \fItag\fR is specified, the git commit \fIrevision\fR corresponding to that tag must also be specified\. +If a \fItag\fR is specified, the Git commit \fIrevision\fR corresponding to that tag must also be specified\. . .P -Note that this command cannot be used to transition a formula from a URL\-and\-sha256 style specification into a tag\-and\-revision style specification, nor vice versa\. It must use whichever style specification the preexisting formula already uses\. +\fINote:\fR 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\. . .TP \fB\-\-devel\fR @@ -788,7 +788,7 @@ Print what would be done rather than doing it\. . .TP \fB\-\-write\fR -When passed along with \fB\-\-dry\-run\fR, perform a not\-so\-dry run making the expected file modifications but not taking any git actions\. +When passed along with \fB\-\-dry\-run\fR, perform a not\-so\-dry run by making the expected file modifications but not taking any Git actions\. . .TP \fB\-\-audit\fR @@ -800,23 +800,7 @@ Run \fBbrew audit \-\-strict\fR before opening the PR\. . .TP \fB\-\-no\-browse\fR -Output the pull request URL instead of opening in a browser -. -.TP -\fB\-\-url\fR -Provide new \fIURL\fR for the formula\. If a \fIURL\fR is specified, the \fIsha\-256\fR checksum of the new download must also be specified\. -. -.TP -\fB\-\-revision\fR -Specify the new git commit \fIrevision\fR corresponding to a specified \fItag\fR\. -. -.TP -\fB\-\-tag\fR -Specify the new git commit \fItag\fR for the formula\. -. -.TP -\fB\-\-sha256\fR -Specify the \fIsha\-256\fR checksum of new download\. +Print the pull request URL instead of opening in a browser\. . .TP \fB\-\-mirror\fR @@ -824,14 +808,30 @@ Use the provided \fIURL\fR as a mirror URL\. . .TP \fB\-\-version\fR -Use the provided \fIversion\fR to override the value parsed from the URL or tag\. Note that \fB\-\-version=0\fR can be used to delete an existing \fBversion\fR override from a formula if it has become redundant\. +Use the provided \fIversion\fR to override the value parsed from the URL or tag\. Note that \fB\-\-version=0\fR can be used to delete an existing version override from a formula if it has become redundant\. . .TP \fB\-\-message\fR -Append provided \fImessage\fR to the default PR message\. +Append the provided \fImessage\fR to the default PR message\. . -.SS "\fBcreate\fR \fIURL\fR [\fIoptions\fR]:" -Generate a formula for the downloadable file at \fIURL\fR 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 \fBwget\fR formula serves as a simple example\. For the complete API have a look at \fIhttp://www\.rubydoc\.info/github/Homebrew/brew/master/Formula\fR\. +.TP +\fB\-\-url\fR +Specify the \fIURL\fR for the new download\. If a \fIURL\fR is specified, the \fISHA\-256\fR checksum of the new download should also be specified\. +. +.TP +\fB\-\-sha256\fR +Specify the \fISHA\-256\fR checksum of the new download\. +. +.TP +\fB\-\-tag\fR +Specify the new git commit \fItag\fR for the formula\. +. +.TP +\fB\-\-revision\fR +Specify the new git commit \fIrevision\fR corresponding to a specified \fItag\fR\. +. +.SS "\fBcreate\fR [\fIoptions\fR] \fIURL\fR" +Generate a formula for the downloadable file at \fIURL\fR 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 \fBwget\fR formula serves as a simple example\. For the complete API, see: \fIhttp://www\.rubydoc\.info/github/Homebrew/brew/master/Formula\fR . .TP \fB\-\-autotools\fR @@ -847,38 +847,38 @@ Create a basic template for a Meson\-style build\. . .TP \fB\-\-no\-fetch\fR -Homebrew will not download \fIURL\fR to the cache and will thus not add the SHA256 to the formula for you\. It will also not check the GitHub API for GitHub projects (to fill out the description and homepage)\. +Homebrew will not download \fIURL\fR 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)\. . .TP \fB\-\-HEAD\fR -HEAD +Indicate that \fIURL\fR points to the package\'s repository rather than a file\. . .TP \fB\-\-set\-name\fR -Set the provided name of the package you are creating\. +Set the name of the new formula to the provided \fIname\fR\. . .TP \fB\-\-set\-version\fR -Set the provided version of the package you are creating\. +Set the version of the new formula to the provided \fIversion\fR\. . .TP \fB\-\-tap\fR -Takes a tap [\fIuser\fR\fB/\fR\fIrepo\fR] as argument and generates the formula in the specified tap\. +Generate the new formula in the provided tap, specified as \fIuser\fR\fB/\fR\fIrepo\fR\. . -.SS "\fBedit\fR \fIformula\fR:" -Open \fIformula\fR in the editor\. Open all of Homebrew for editing if no \fIformula\fR is provided\. +.SS "\fBedit\fR [\fIformulae\fR]" +Open a formula in the editor set by \fBEDITOR\fR or \fBHOMEBREW_EDITOR\fR, or open the Homebrew repository for editing if no \fIformula\fR is provided\. . -.SS "\fBextract\fR [\fIoptions\fR] \fIformula\fR \fItap\fR:" -Looks through repository history to find the \fIversion\fR of \fIformula\fR and creates a copy in \fItap\fR/Formula/\fIformula\fR@\fIversion\fR\.rb\. If the tap is not installed yet, attempts to install/clone the tap before continuing\. +.SS "\fBextract\fR [\fIoptions\fR] \fIformula\fR \fItap\fR" +Look through repository history to find the most recent version of \fIformula\fR and create a copy in \fItap\fR\fB/Formula/\fR\fIformula\fR\fB@\fR\fIversion\fR\fB\.rb\fR\. If the tap is not installed yet, attempt to install/clone the tap before continuing\. . .TP \fB\-\-version\fR -Provided \fIversion\fR of \fIformula\fR will be extracted and placed in the destination tap\. Otherwise, the most recent version that can be found will be used\. +Extract the provided \fIversion\fR of \fIformula\fR instead of the most recent\. . -.SS "\fBformula\fR \fIformula\fR:" -Display the path where \fIformula\fR is located\. +.SS "\fBformula\fR \fIformulae\fR" +Display the path where a formula is located\. . -.SS "\fBirb\fR [\fIoptions\fR]:" +.SS "\fBirb\fR [\fIoptions\fR]" Enter the interactive Homebrew Ruby shell\. . .TP @@ -887,27 +887,24 @@ Show several examples\. . .TP \fB\-\-pry\fR -Pry will be used instead of irb if \fB\-\-pry\fR is passed or HOMEBREW_PRY is set\. +Use Pry instead of IRB\. Implied if \fBHOMEBREW_PRY\fR is set\. . -.SS "\fBlinkage\fR [\fIoptions\fR] \fIformula\fR:" -Checks the library links of an installed formula\. -. -.P -Only works on installed formulae\. An error is raised if it is run on uninstalled formulae\. +.SS "\fBlinkage\fR [\fIoptions\fR] [\fIformulae\fR]" +Check the library links for kegs of installed formulae\. Raises an error if run on uninstalled formulae\. . .TP \fB\-\-test\fR -Display only missing libraries and exit with a non\-zero exit code if any missing libraries were found\. +Display only missing libraries and exit with a non\-zero status if any missing libraries are found\. . .TP \fB\-\-reverse\fR -Print the dylib followed by the binaries which link to it for each library the keg references\. +For every library that a keg references, print its dylib path followed by the binaries that link to it\. . .TP \fB\-\-cached\fR -Print the cached linkage values stored in HOMEBREW_CACHE, set from a previous \fBbrew linkage\fR run\. +Print the cached linkage values stored in \fBHOMEBREW_CACHE\fR, set by a previous \fBbrew linkage\fR run\. . -.SS "\fBman\fR [\fIoptions\fR]:" +.SS "\fBman\fR [\fIoptions\fR]" Generate Homebrew\'s manpages\. . .TP @@ -916,20 +913,22 @@ Return a failing status code if changes are detected in the manpage outputs\. Th . .TP \fB\-\-link\fR -It is now done automatically by \fBbrew update\fR\. +This is now done automatically by \fBbrew update\fR\. . -.SS "\fBmirror\fR \fIformulae\fR:" +.SS "\fBmirror\fR \fIformulae\fR" Reuploads the stable URL for a formula to Bintray to use it as a mirror\. . -.TP -\fBprof\fR [\fIruby options\fR] -Run Homebrew with the Ruby profiler\. For example: brew prof readall -. -.SS "\fBpull\fR [\fIoptions\fR] \fIformula\fR:" -Gets a patch from a GitHub commit or pull request and applies it to Homebrew\. Optionally, installs the formulae changed by the patch\. +.SS "\fBprof\fR [\fIruby options\fR]" +Run Homebrew with the Ruby profiler\. . .P -Each \fIpatch\-source\fR may be one of: +\fIExample:\fR \fBbrew prof readall\fR +. +.SS "\fBpull\fR [\fIoptions\fR] \fIpatch sources\fR" +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\. +. +.P +Each \fIpatch source\fR may be one of: . .P ~ The ID number of a PR (pull request) in the homebrew/core GitHub repository @@ -981,44 +980,52 @@ Do not exit if there\'s a failure publishing bottles on Bintray\. . .TP \fB\-\-bintray\-org\fR -Publish at the given Bintray organisation\. +Publish bottles at the provided Bintray \fIorganisation\fR\. . .TP \fB\-\-test\-bot\-user\fR -Pull the bottle block commit from the specified user on GitHub\. +Pull the bottle block commit from the provided \fIuser\fR on GitHub\. . -.SS "\fBrelease\-notes\fR [\fIoptions\fR] [\fIprevious_tag\fR] [\fIend_ref\fR]:" -Output the merged pull requests on Homebrew/brew between two Git refs\. If no \fIprevious_tag\fR is provided it defaults to the latest tag\. If no \fIend_ref\fR is provided it defaults to \fBorigin/master\fR\. +.SS "\fBrelease\-notes\fR [\fIoptions\fR] [\fIprevious_tag\fR] [\fIend_ref\fR]" +Print the merged pull requests on Homebrew/brew between two Git refs\. If no \fIprevious_tag\fR is provided it defaults to the latest tag\. If no \fIend_ref\fR is provided it defaults to \fBorigin/master\fR\. . .TP \fB\-\-markdown\fR -Output as a Markdown list\. +Print as a Markdown list\. +. +.SS "\fBruby\fR [\fIruby options\fR]" +Run a Ruby instance with Homebrew\'s libraries loaded\. +. +.P +\fIExample:\fR \fBbrew ruby \-e "puts :gcc\.f\.deps"\fR or \fBbrew ruby script\.rb\fR . .TP -\fBruby\fR [\fIruby options\fR] -Run a Ruby instance with Homebrew\'s libraries loaded\. For example: +\fB\-e\fR +Execute the provided string argument as a script\. . -.SS "\fBtap\-new\fR \fIuser\fR/\fIrepo\fR:" +.SS "\fBtap\-new\fR \fIuser\fR\fB/\fR\fIrepo\fR" Generate the template files for a new tap\. . +.SS "\fBtest\fR [\fIoptions\fR] \fIformulae\fR" +Run the test method provided by an installed formula\. There is no standard output or return code, but generally it should notify the user if something is wrong with the installed formula\. +. +.P +\fIExample:\fR \fBbrew install jruby && brew test jruby\fR +. .TP -\fBtest\fR [\fB\-\-devel\fR|\fB\-\-HEAD\fR] [\fB\-\-debug\fR] [\fB\-\-keep\-tmp\fR] \fIformula\fR -Most formulae provide a test method\. \fBbrew test\fR \fIformula\fR 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\. +\fB\-\-devel\fR +Test the development version of a formula\. . -.IP -To test the development or head version of a formula, use \fB\-\-devel\fR or \fB\-\-HEAD\fR\. +.TP +\fB\-\-HEAD\fR +Test the head version of a formula\. . -.IP -If \fB\-\-debug\fR (or \fB\-d\fR) is passed and the test fails, an interactive debugger will be launched with access to IRB or a shell inside the temporary test directory\. +.TP +\fB\-\-keep\-tmp\fR +Keep the temporary files created for the test\. . -.IP -If \fB\-\-keep\-tmp\fR is passed, the temporary files created for the test are not deleted\. -. -.IP -Example: \fBbrew install jruby && brew test jruby\fR -. -.SS "\fBtests\fR [\fIoptions\fR]:" -Run Homebrew\'s unit and integration tests\. If provided, \fB\-\-only=\fR\fItest_script\fR runs only \fItest_script\fR_spec\.rb, and \fB\-\-seed\fR randomizes tests with the provided value instead of a random seed\. +.SS "\fBtests\fR [\fIoptions\fR]" +Run Homebrew\'s unit and integration tests\. . .TP \fB\-\-coverage\fR @@ -1038,17 +1045,14 @@ Include tests that use the GitHub API and tests that use any of the taps for off . .TP \fB\-\-only\fR -Run only \fItest_script\fR_spec\.rb +Run only \fItest_script\fR\fB_spec\.rb\fR\. Appending \fB:\fR\fIline_number\fR will start at a specific line\. . .TP \fB\-\-seed\fR -Randomizes tests with the provided value instead of a random seed\. +Randomize tests with the provided \fIvalue\fR instead of a random seed\. . -.SS "\fBupdate\-test\fR [\fIoptions\fR]:" -Runs a test of \fBbrew update\fR with a new repository clone\. -. -.P -If no arguments are passed, use \fBorigin/master\fR as the start commit\. +.SS "\fBupdate\-test\fR [\fIoptions\fR]" +Run a test of \fBbrew update\fR with a new repository clone\. If no arguments are passed, use \fBorigin/master\fR as the start commit\. . .TP \fB\-\-to\-tag\fR