diff options
24 files changed, 204 insertions, 136 deletions
diff --git a/Library/Homebrew/cmd/--env.rb b/Library/Homebrew/cmd/--env.rb index 90beee89c..e0a2b9f19 100644 --- a/Library/Homebrew/cmd/--env.rb +++ b/Library/Homebrew/cmd/--env.rb @@ -1,5 +1,11 @@ -#: * `--env`: -#: Show a summary of the Homebrew build environment. +#: * `--env` [`--shell=`(<shell>|`auto`)|`--plain`]: +#: Show a summary of the Homebrew build environment as a plain list. +#: +#: Pass `--shell=`<shell> to generate a list of environment variables for the +#: specified shell, or `--shell=auto` to detect the current shell. +#: +#: If the command's output is sent through a pipe and no shell is specified, +#: the list is formatted for export to `bash`(1) unless `--plain` is passed. require "extend/ENV" require "build_environment" diff --git a/Library/Homebrew/cmd/desc.rb b/Library/Homebrew/cmd/desc.rb index 53291602e..ccb7e9925 100644 --- a/Library/Homebrew/cmd/desc.rb +++ b/Library/Homebrew/cmd/desc.rb @@ -1,11 +1,12 @@ #: * `desc` <formula>: #: Display <formula>'s name and one-line description. #: -#: * `desc` [`-s`|`-n`|`-d`] (<text>|`/`<text>`/`): -#: Search both name and description (`-s`), just the names (`-n`), or just the -#: descriptions (`-d`) for <text>. If <text> is flanked by slashes, it is interpreted -#: as a regular expression. Formula descriptions are cached; the cache is created on -#: the first search, making that search slower than subsequent ones. +#: * `desc` [`--search`|`--name`|`--description`] (<text>|`/`<text>`/`): +#: Search both name and description (`--search` or `-s`), just the names +#: (`--name` or `-n`), or just the descriptions (`--description` or `-d`) for +#: <text>. If <text> is flanked by slashes, it is interpreted as a regular +#: expression. Formula descriptions are cached; the cache is created on the +#: first search, making that search slower than subsequent ones. require "descriptions" require "cmd/search" diff --git a/Library/Homebrew/cmd/doctor.rb b/Library/Homebrew/cmd/doctor.rb index 5ff8aa4eb..4e439fa0a 100644 --- a/Library/Homebrew/cmd/doctor.rb +++ b/Library/Homebrew/cmd/doctor.rb @@ -6,7 +6,8 @@ #: an issue; just ignore this. # Undocumented options: -# -D activates debugging and profiling of the audit methods (not the same as --debug) +# `-D` activates debugging and profiling of the audit methods (not the same as `--debug`) +# `--list-checks` lists all audit methods require "diagnostic" diff --git a/Library/Homebrew/cmd/gist-logs.rb b/Library/Homebrew/cmd/gist-logs.rb index 9c0302813..630361ca2 100644 --- a/Library/Homebrew/cmd/gist-logs.rb +++ b/Library/Homebrew/cmd/gist-logs.rb @@ -4,6 +4,8 @@ #: <formula> is usually the name of the formula to install, but it can be specified #: in several different ways. See [SPECIFYING FORMULAE](#specifying-formulae). #: +#: If `--with-hostname` is passed, include the hostname in the Gist. +#: #: If `--new-issue` is passed, automatically create a new issue in the appropriate #: GitHub repository as well as creating the Gist. #: diff --git a/Library/Homebrew/cmd/info.rb b/Library/Homebrew/cmd/info.rb index a78159a15..1eb9fe9fe 100644 --- a/Library/Homebrew/cmd/info.rb +++ b/Library/Homebrew/cmd/info.rb @@ -1,8 +1,11 @@ +#: * `info`: +#: Display brief statistics for your Homebrew installation. +#: #: * `info` <formula>: #: Display information about <formula>. #: #: * `info` `--github` <formula>: -#: Open a browser to the GitHub History page for formula <formula>. +#: Open a browser to the GitHub History page for <formula>. #: #: To view formula history locally: `brew log -p <formula>` #: diff --git a/Library/Homebrew/cmd/install.rb b/Library/Homebrew/cmd/install.rb index 575dbc4b3..e1e4712ea 100644 --- a/Library/Homebrew/cmd/install.rb +++ b/Library/Homebrew/cmd/install.rb @@ -1,4 +1,4 @@ -#: * `install` [`--debug`] [`--env=`(`std`|`super`)] [`--ignore-dependencies`|`--only-dependencies`] [`--cc=`<compiler>] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] <formula> [<options> ...]: +#: * `install` [`--debug`] [`--env=`(`std`|`super`)] [`--ignore-dependencies`|`--only-dependencies`] [`--cc=`<compiler>] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] [`--force`] [`--verbose`] <formula> [<options> ...]: #: Install <formula>. #: #: <formula> is usually the name of the formula to install, but it can be specified @@ -47,6 +47,11 @@ #: If `--build-bottle` is passed, prepare the formula for eventual bottling #: during installation. #: +#: If `--force` (or `-f`) is passed, install without checking for previously +#: installed keg-only or non-migrated versions +#: +#: If `--verbose` (or `-v`) is passed, print the verification and postinstall steps. +#: #: Installation options specific to <formula> may be appended to the command, #: and can be listed with `brew options` <formula>. #: diff --git a/Library/Homebrew/cmd/list.rb b/Library/Homebrew/cmd/list.rb index 1f90a3ac3..482100ba2 100644 --- a/Library/Homebrew/cmd/list.rb +++ b/Library/Homebrew/cmd/list.rb @@ -6,7 +6,7 @@ #: * `list`, `ls` `--unbrewed`: #: List all files in the Homebrew prefix not installed by Homebrew. #: -#: * `list`, `ls` [`--versions` [`--multiple`]] [`--pinned`] [<formulae>]: +#: * `list`, `ls` [`--verbose`] [`--versions` [`--multiple`]] [`--pinned`] [<formulae>]: #: List the installed files for <formulae>. Combined with `--verbose`, recursively #: list the contents of all subdirectories in each <formula>'s keg. #: diff --git a/Library/Homebrew/cmd/outdated.rb b/Library/Homebrew/cmd/outdated.rb index f163212e1..97367ca1e 100644 --- a/Library/Homebrew/cmd/outdated.rb +++ b/Library/Homebrew/cmd/outdated.rb @@ -9,8 +9,8 @@ #: #: If `--verbose` (or `-v`) is passed, display detailed version information. #: -#: If `--json=`<version> is passed, the output will be in JSON format. The only -#: valid version is `v1`. +#: If `--json=`<version> is passed, the output will be in JSON format. +#: Currently the only accepted value for <version> is `v1`. #: #: If `--fetch-HEAD` is passed, fetch the upstream repository to detect if #: the HEAD installation of the formula is outdated. Otherwise, the diff --git a/Library/Homebrew/cmd/pin.rb b/Library/Homebrew/cmd/pin.rb index 5a14f853c..9935d1636 100644 --- a/Library/Homebrew/cmd/pin.rb +++ b/Library/Homebrew/cmd/pin.rb @@ -1,7 +1,6 @@ #: * `pin` <formulae>: #: Pin the specified <formulae>, preventing them from being upgraded when -#: issuing the `brew upgrade <formulae>` command (but can still be upgraded -#: as dependencies for other formulae). See also `unpin`. +#: issuing the `brew upgrade <formulae>` command. See also `unpin`. require "formula" diff --git a/Library/Homebrew/cmd/readall.rb b/Library/Homebrew/cmd/readall.rb index 3bde16e7e..0a581c383 100644 --- a/Library/Homebrew/cmd/readall.rb +++ b/Library/Homebrew/cmd/readall.rb @@ -1,9 +1,13 @@ -#: * `readall` [tap]: -#: Import all formulae from specified taps (defaults to all installed taps). +#: * `readall` [`--aliases`] [`--syntax`] [<taps>]: +#: Import all formulae from specified <taps> (defaults to all installed taps). #: #: This can be useful for debugging issues across all formulae when making #: significant changes to `formula.rb`, testing the performance of loading #: all formulae or to determine if any current formulae have Ruby issues. +#: +#: If `--aliases` is passed, also verify any alias symlinks in each tap. +#: +#: If `--syntax` is passed, also syntax-check all of Homebrew's Ruby files. require "readall" diff --git a/Library/Homebrew/cmd/style.rb b/Library/Homebrew/cmd/style.rb index 89484d67d..1f0d385de 100644 --- a/Library/Homebrew/cmd/style.rb +++ b/Library/Homebrew/cmd/style.rb @@ -1,19 +1,19 @@ -#: * `style` [`--fix`] [`--display-cop-names`] [`--only-cops=`[COP1,COP2..]|`--except-cops=`[COP1,COP2..]] [<files>|<taps>|<formulae>]: +#: * `style` [`--fix`] [`--display-cop-names`] [`--only-cops=`<cops>|`--except-cops=`<cops>] [<files>|<taps>|<formulae>]: #: Check formulae or files for conformance to Homebrew style guidelines. #: -#: <formulae> and <files> may not be combined. If both are omitted, style will run -#: style checks on the whole Homebrew `Library`, including core code and all -#: formulae. +#: Lists of <files>, <taps> and <formulae> may not be combined. If none are +#: provided, `style` will run style checks on the whole Homebrew library, +#: including core code and all formulae. #: -#: If `--fix` is passed, style violations will be automatically fixed using -#: RuboCop's `--auto-correct` feature. +#: If `--fix` is passed, automatically fix style violations using RuboCop's +#: auto-correct feature. #: -#: If `--display-cop-names` is passed, the RuboCop cop name for each violation -#: is included in the output. +#: If `--display-cop-names` is passed, include the RuboCop cop name for each +#: violation in the output. #: -#: If `--only-cops` is passed, only the given Rubocop cop(s)' violations would be checked. -#: -#: If `--except-cops` is passed, the given Rubocop cop(s)' checks would be skipped. +#: Passing `--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. #: #: Exits with a non-zero status if any style violations are found. diff --git a/Library/Homebrew/cmd/uninstall.rb b/Library/Homebrew/cmd/uninstall.rb index f95b6c7bb..af0efaf62 100644 --- a/Library/Homebrew/cmd/uninstall.rb +++ b/Library/Homebrew/cmd/uninstall.rb @@ -46,6 +46,16 @@ module Homebrew rm_pin rack else kegs.each do |keg| + begin + f = Formulary.from_rack(rack) + if f.pinned? + onoe "#{f.full_name} is pinned. You must unpin it to uninstall." + next + end + rescue + nil + end + keg.lock do puts "Uninstalling #{keg}... (#{keg.abv})" keg.unlink diff --git a/Library/Homebrew/cmd/update-report.rb b/Library/Homebrew/cmd/update-report.rb index 98823a152..055c55a84 100644 --- a/Library/Homebrew/cmd/update-report.rb +++ b/Library/Homebrew/cmd/update-report.rb @@ -1,5 +1,5 @@ #: @hide_from_man_page -#: * `update_report`: +#: * `update_report` [`--preinstall`]: #: The Ruby implementation of `brew update`. Never called manually. require "formula_versions" diff --git a/Library/Homebrew/cmd/upgrade.rb b/Library/Homebrew/cmd/upgrade.rb index 7832983e3..401a02e67 100644 --- a/Library/Homebrew/cmd/upgrade.rb +++ b/Library/Homebrew/cmd/upgrade.rb @@ -50,11 +50,8 @@ module Homebrew exit 1 if outdated.empty? end - unless upgrade_pinned? - pinned = outdated.select(&:pinned?) - outdated -= pinned - end - + pinned = outdated.select(&:pinned?) + outdated -= pinned formulae_to_install = outdated.map(&:latest_formula) if formulae_to_install.empty? @@ -64,8 +61,8 @@ module Homebrew puts formulae_to_install.map { |f| "#{f.full_specified_name} #{f.pkg_version}" } * ", " end - unless upgrade_pinned? || pinned.empty? - oh1 "Not upgrading #{Formatter.pluralize(pinned.length, "pinned package")}:" + unless pinned.empty? + onoe "Not upgrading #{Formatter.pluralize(pinned.length, "pinned package")}:" puts pinned.map { |f| "#{f.full_specified_name} #{f.pkg_version}" } * ", " end @@ -95,10 +92,6 @@ module Homebrew end end - def upgrade_pinned? - !ARGV.named.empty? - end - def upgrade_formula(f) if f.opt_prefix.directory? keg = Keg.new(f.opt_prefix.resolved_path) @@ -143,13 +136,6 @@ module Homebrew fi.install fi.finish - - # If the formula was pinned, and we were force-upgrading it, unpin and - # pin it again to get a symlink pointing to the correct keg. - if f.pinned? - f.unpin - f.pin - end rescue FormulaInstallationAlreadyAttemptedError # We already attempted to upgrade f as part of the dependency tree of # another formula. In that case, don't generate an error, just move on. diff --git a/Library/Homebrew/dev-cmd/audit.rb b/Library/Homebrew/dev-cmd/audit.rb index 45de368e1..e3fb3a580 100644 --- a/Library/Homebrew/dev-cmd/audit.rb +++ b/Library/Homebrew/dev-cmd/audit.rb @@ -1,4 +1,4 @@ -#: * `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=`<method>|`--except=`<method>] [`--only-cops=`[COP1,COP2..]|`--except-cops=`[COP1,COP2..]] [<formulae>]: +#: * `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. #: @@ -8,7 +8,7 @@ #: style checks. #: #: If `--fix` is passed, style violations will be -#: automatically fixed using RuboCop's `--auto-correct` feature. +#: automatically fixed using RuboCop's auto-correct feature. #: #: If `--online` is passed, additional slower checks that require a network #: connection are run. @@ -23,19 +23,19 @@ #: 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. #: -#: If `--only` is passed, only the methods named `audit_<method>` will be run. +#: Passing `--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. #: -#: If `--except` is passed, the methods named `audit_<method>` will not be run. -#: -#: If `--only-cops` is passed, only the given Rubocop cop(s)' violations would be checked. -#: -#: If `--except-cops` is passed, the given Rubocop cop(s)' checks would be skipped. +#: Passing `--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. #: #: `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) +# `-D` activates debugging and profiling of the audit methods (not the same as `--debug`) require "formula" require "formula_versions" @@ -189,8 +189,6 @@ class FormulaAuditor swig ].freeze - FILEUTILS_METHODS = FileUtils.singleton_methods(false).map { |m| Regexp.escape(m) }.join "|" - def initialize(formula, options = {}) @formula = formula @new_formula = options[:new_formula] diff --git a/Library/Homebrew/dev-cmd/bottle.rb b/Library/Homebrew/dev-cmd/bottle.rb index 204e7cef9..a233dfb57 100644 --- a/Library/Homebrew/dev-cmd/bottle.rb +++ b/Library/Homebrew/dev-cmd/bottle.rb @@ -25,6 +25,10 @@ #: If `--write` is passed, write the changes to the formula file. A new #: commit will then be generated unless `--no-commit` is passed. +# Undocumented options: +# `--json` writes bottle information to a JSON file, which can be used as +# the argument for `--merge`. + require "formula" require "utils/bottles" require "tab" diff --git a/Library/Homebrew/dev-cmd/bump-formula-pr.rb b/Library/Homebrew/dev-cmd/bump-formula-pr.rb index 7da0f9321..1f44fa549 100644 --- a/Library/Homebrew/dev-cmd/bump-formula-pr.rb +++ b/Library/Homebrew/dev-cmd/bump-formula-pr.rb @@ -33,6 +33,9 @@ #: 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 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 diff --git a/Library/Homebrew/dev-cmd/linkage.rb b/Library/Homebrew/dev-cmd/linkage.rb index e4da827f2..31e9bd103 100644 --- a/Library/Homebrew/dev-cmd/linkage.rb +++ b/Library/Homebrew/dev-cmd/linkage.rb @@ -1,4 +1,4 @@ -#: * `linkage` [`--test`] [`--reverse`] <formula>: +#: * `linkage` [`--test`] [`--reverse`] <formula>: #: Checks the library links of an installed formula. #: #: Only works on installed formulae. An error is raised if it is run on diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb index 3fbdd2601..f06c89863 100644 --- a/Library/Homebrew/dev-cmd/man.rb +++ b/Library/Homebrew/dev-cmd/man.rb @@ -108,7 +108,7 @@ module Homebrew ronn.write markup ronn.close_write ronn_output = ronn.read - ronn_output.gsub!(%r{</?var>}, "`") if format_flag == "--markdown" + ronn_output.gsub!(%r{</var>`(?=[.!?,;:]?\s)}, "").gsub!(%r{</?var>}, "`") if format_flag == "--markdown" target.atomic_write ronn_output end end diff --git a/Library/Homebrew/utils.rb b/Library/Homebrew/utils.rb index 77eae6f69..989f05b45 100644 --- a/Library/Homebrew/utils.rb +++ b/Library/Homebrew/utils.rb @@ -83,9 +83,11 @@ def odeprecated(method, replacement = nil, disable: false, disable_on: nil, call backtrace = caller tap_message = nil - # Don't throw deprecations at all for cached or .brew formulae. + # Don't throw deprecations at all for cached, .brew or .metadata files. return if backtrace.any? do |line| - line.include?(HOMEBREW_CACHE) || line.include?("/.brew/") + line.include?(HOMEBREW_CACHE) || + line.include?("/.brew/") || + line.include?("/.metadata/") end caller_message = backtrace.detect do |line| diff --git a/docs/Brew-Test-Bot.md b/docs/Brew-Test-Bot.md index 4a3a639d5..46e2f9e71 100644 --- a/docs/Brew-Test-Bot.md +++ b/docs/Brew-Test-Bot.md @@ -3,7 +3,7 @@ `brew test-bot` is the name for the automated review and testing system funded by [our Kickstarter in 2013](https://www.kickstarter.com/projects/homebrew/brew-test-bot). -It comprises four Mac Minis running in a data centre in England which host +It comprises four Mac Minis and three Xserves running in two data centres which host [a Jenkins instance at https://jenkins.brew.sh](https://jenkins.brew.sh) and run the [`brew-test-bot.rb`](https://github.com/Homebrew/homebrew-test-bot/blob/master/cmd/brew-test-bot.rb) Ruby script to perform automated testing of commits to the master branch, pull @@ -36,8 +36,6 @@ A passed build looks like this: On failed or passed builds you can click the "Details" link to view the result in Jenkins. -When you click this you'll see the results. - A passed build looks like this:  diff --git a/docs/Interesting-Taps-and-Forks.md b/docs/Interesting-Taps-and-Forks.md index 5115fd9d5..4d569e6c0 100644 --- a/docs/Interesting-Taps-and-Forks.md +++ b/docs/Interesting-Taps-and-Forks.md @@ -33,11 +33,15 @@ You can be added as a maintainer for one of the Homebrew organization taps and a * [brewsci/science](https://github.com/brewsci/homebrew-science): Software tailored to scientific endeavours. +* [davidchall/hep](https://github.com/davidchall/homebrew-hep): High energy physics formulae. + +* [lifepillar/appleii](https://github.com/lifepillar/homebrew-appleii): Formulae for vintage Apple emulation. + ## Interesting forks -* [mistydemeo/tigerbrew](https://github.com/mistydemeo/tigerbrew): Experimental Tiger PowerPC version +* [mistydemeo/tigerbrew](https://github.com/mistydemeo/tigerbrew): Experimental Tiger PowerPC version. -* [Linuxbrew/brew](https://github.com/Linuxbrew/brew): Experimental Linux version +* [Linuxbrew/brew](https://github.com/Linuxbrew/brew): Experimental Linux version. ## Technical details diff --git a/docs/Manpage.md b/docs/Manpage.md index 6229a0a01..920518376 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -126,11 +126,12 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note * `desc` `formula`: Display `formula`'s name and one-line description. - * `desc` [`-s`|`-n`|`-d`] (`text`|`/``text``/`): - Search both name and description (`-s`), just the names (`-n`), or just the - descriptions (`-d`) for `text`. If `text` is flanked by slashes, it is interpreted - as a regular expression. Formula descriptions are cached; the cache is created on - the first search, making that search slower than subsequent ones. + * `desc` [`--search`|`--name`|`--description`] (`text`|`/``text``/`): + Search both name and description (`--search` or `-s`), just the names + (`--name` or `-n`), or just the descriptions (`--description` or `-d`) for + `text`. If `text` is flanked by slashes, it is interpreted as a regular + expression. Formula descriptions are cached; the cache is created on the + first search, making that search slower than subsequent ones. * `diy` [`--name=``name`] [`--version=``version`]: Automatically determine the installation prefix for non-Homebrew software. @@ -179,6 +180,8 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note `formula` is usually the name of the formula to install, but it can be specified in several different ways. See [SPECIFYING FORMULAE](#specifying-formulae). + If `--with-hostname` is passed, include the hostname in the Gist. + If `--new-issue` is passed, automatically create a new issue in the appropriate GitHub repository as well as creating the Gist. @@ -190,13 +193,16 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note * `home` `formula`: Open `formula`'s homepage in a browser. + * `info`: + Display brief statistics for your Homebrew installation. + * `info` `formula`: Display information about `formula`. * `info` `--github` `formula`: - Open a browser to the GitHub History page for formula `formula`. + Open a browser to the GitHub History page for `formula`. - To view formula history locally: `brew log -p `formula`` + To view formula history locally: `brew log -p `formula * `info` `--json=``version` (`--all`|`--installed`|`formulae`): Print a JSON representation of `formulae`. Currently the only accepted value @@ -208,7 +214,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note See the docs for examples of using the JSON output: <https://docs.brew.sh/Querying-Brew.html> - * `install` [`--debug`] [`--env=`(`std`|`super`)] [`--ignore-dependencies`|`--only-dependencies`] [`--cc=``compiler`] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] `formula` [`options` ...]: + * `install` [`--debug`] [`--env=`(`std`|`super`)] [`--ignore-dependencies`|`--only-dependencies`] [`--cc=``compiler`] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] [`--keep-tmp`] [`--build-bottle`] [`--force`] [`--verbose`] `formula` [`options` ...]: Install `formula`. `formula` is usually the name of the formula to install, but it can be specified @@ -257,6 +263,11 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note If `--build-bottle` is passed, prepare the formula for eventual bottling during installation. + If `--force` (or `-f`) is passed, install without checking for previously + installed keg-only or non-migrated versions + + If `--verbose` (or `-v`) is passed, print the verification and postinstall steps. + Installation options specific to `formula` may be appended to the command, and can be listed with `brew options` `formula`. @@ -299,7 +310,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note * `list`, `ls` `--unbrewed`: List all files in the Homebrew prefix not installed by Homebrew. - * `list`, `ls` [`--versions` [`--multiple`]] [`--pinned`] [`formulae`]: + * `list`, `ls` [`--verbose`] [`--versions` [`--multiple`]] [`--pinned`] [`formulae`]: List the installed files for `formulae`. Combined with `--verbose`, recursively list the contents of all subdirectories in each `formula`'s keg. @@ -350,8 +361,8 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note If `--verbose` (or `-v`) is passed, display detailed version information. - If `--json=``version` is passed, the output will be in JSON format. The only - valid version is `v1`. + If `--json=``version` is passed, the output will be in JSON format. + Currently the only accepted value for `version` is `v1`. If `--fetch-HEAD` is passed, fetch the upstream repository to detect if the HEAD installation of the formula is outdated. Otherwise, the @@ -360,8 +371,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note * `pin` `formulae`: Pin the specified `formulae`, preventing them from being upgraded when - issuing the `brew upgrade `formulae`` command (but can still be upgraded - as dependencies for other formulae). See also `unpin`. + issuing the `brew upgrade `formulae command. See also `unpin`. * `postinstall` `formula`: Rerun the post-install steps for `formula`. @@ -375,13 +385,17 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note If `--dry-run` or `-n` is passed, show what would be removed, but do not actually remove anything. - * `readall` [tap]: - Import all formulae from specified taps (defaults to all installed taps). + * `readall` [`--aliases`] [`--syntax`] [`taps`]: + Import all formulae from specified `taps` (defaults to all installed taps). This can be useful for debugging issues across all formulae when making significant changes to `formula.rb`, testing the performance of loading all formulae or to determine if any current formulae have Ruby issues. + If `--aliases` is passed, also verify any alias symlinks in each tap. + + If `--syntax` is passed, also syntax-check all of Homebrew's Ruby files. + * `reinstall` `formula`: Uninstall and then install `formula` (with existing install options). @@ -409,22 +423,22 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note If `--env=std` is passed, use the standard `PATH` instead of superenv's. - * `style` [`--fix`] [`--display-cop-names`] [`--only-cops=`[COP1,COP2..]|`--except-cops=`[COP1,COP2..]] [`files`|`taps`|`formulae`]: + * `style` [`--fix`] [`--display-cop-names`] [`--only-cops=``cops`|`--except-cops=``cops`] [`files`|`taps`|`formulae`]: Check formulae or files for conformance to Homebrew style guidelines. - `formulae` and `files` may not be combined. If both are omitted, style will run - style checks on the whole Homebrew `Library`, including core code and all - formulae. - - If `--fix` is passed, style violations will be automatically fixed using - RuboCop's `--auto-correct` feature. + Lists of `files`, `taps` and `formulae` may not be combined. If none are + provided, `style` will run style checks on the whole Homebrew library, + including core code and all formulae. - If `--display-cop-names` is passed, the RuboCop cop name for each violation - is included in the output. + If `--fix` is passed, automatically fix style violations using RuboCop's + auto-correct feature. - If `--only-cops` is passed, only the given Rubocop cop(s)' violations would be checked. + If `--display-cop-names` is passed, include the RuboCop cop name for each + violation in the output. - If `--except-cops` is passed, the given Rubocop cop(s)' checks would be skipped. + Passing `--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. Exits with a non-zero status if any style violations are found. @@ -439,7 +453,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note With `URL` unspecified, taps a formula repository from GitHub using HTTPS. Since so many taps are hosted on GitHub, this command is a shortcut for - `tap `user`/`repo` https://github.com/`user`/homebrew-`repo``. + `tap `user`/`repo` https://github.com/`user`/homebrew-`repo. With `URL` specified, taps a formula repository from anywhere, using any transport protocol that `git` handles. The one-argument form of `tap` @@ -500,7 +514,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note * `unlink` [`--dry-run`] `formula`: Remove symlinks for `formula` from the Homebrew prefix. This can be useful for temporarily disabling a formula: - `brew unlink `formula` && `commands` && brew link `formula`` + `brew unlink `formula` && `commands` && brew link `formula If `--dry-run` or `-n` is passed, Homebrew will list all files which would be unlinked, but will not actually unlink or delete any files. @@ -517,7 +531,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note source. This is useful for creating patches for the software. * `unpin` `formulae`: - Unpin `formulae`, allowing them to be upgraded by `brew upgrade `formulae``. + Unpin `formulae`, allowing them to be upgraded by `brew upgrade `formulae. See also `pin`. * `untap` `tap`: @@ -585,8 +599,14 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note Display the location in the cellar where `formula` would be installed, without any sort of versioned directory as the last path. - * `--env`: - Show a summary of the Homebrew build environment. + * `--env` [`--shell=`(`shell`|`auto`)|`--plain`]: + Show a summary of the Homebrew build environment as a plain list. + + Pass `--shell=``shell` to generate a list of environment variables for the + specified shell, or `--shell=auto` to detect the current shell. + + If the command's output is sent through a pipe and no shell is specified, + the list is formatted for export to `bash`(1) unless `--plain` is passed. * `--prefix`: Display Homebrew's install path. *Default:* `/usr/local` @@ -605,7 +625,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note ## DEVELOPER COMMANDS - * `audit` [`--strict`] [`--fix`] [`--online`] [`--new-formula`] [`--display-cop-names`] [`--display-filename`] [`--only=``method`|`--except=``method`] [`--only-cops=`[COP1,COP2..]|`--except-cops=`[COP1,COP2..]] [`formulae`]: + * `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. @@ -615,7 +635,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note style checks. If `--fix` is passed, style violations will be - automatically fixed using RuboCop's `--auto-correct` feature. + automatically fixed using RuboCop's auto-correct feature. If `--online` is passed, additional slower checks that require a network connection are run. @@ -630,13 +650,13 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note 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. - If `--only` is passed, only the methods named `audit_`method`` will be run. + Passing `--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. - If `--except` is passed, the methods named `audit_`method`` will not be run. - - If `--only-cops` is passed, only the given Rubocop cop(s)' violations would be checked. - - If `--except-cops` is passed, the given Rubocop cop(s)' checks would be skipped. + Passing `--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. `audit` exits with a non-zero status if any errors are found. This is useful, for instance, for implementing pre-commit hooks. @@ -703,6 +723,9 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note 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 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 @@ -738,7 +761,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note * `formula` `formula`: Display the path where `formula` is located. - * `linkage` [`--test`] [`--reverse`] `formula`: + * `linkage` [`--test`] [`--reverse`] `formula`: Checks the library links of an installed formula. Only works on installed formulae. An error is raised if it is run on diff --git a/manpages/brew.1 b/manpages/brew.1 index 40b2f25d6..56581bfc0 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -137,8 +137,8 @@ The \fIfilters\fR placeholder is any combination of options \fB\-\-include\-buil Display \fIformula\fR\'s name and one\-line description\. . .TP -\fBdesc\fR [\fB\-s\fR|\fB\-n\fR|\fB\-d\fR] (\fItext\fR|\fB/\fR\fItext\fR\fB/\fR) -Search both name and description (\fB\-s\fR), just the names (\fB\-n\fR), or just the descriptions (\fB\-d\fR) for \fItext\fR\. If \fItext\fR is flanked by slashes, it is interpreted as a regular expression\. Formula descriptions are cached; the cache is created on the first search, making that search slower than subsequent ones\. +\fBdesc\fR [\fB\-\-search\fR|\fB\-\-name\fR|\fB\-\-description\fR] (\fItext\fR|\fB/\fR\fItext\fR\fB/\fR) +Search both name and description (\fB\-\-search\fR or \fB\-s\fR), just the names (\fB\-\-name\fR or \fB\-n\fR), or just the descriptions (\fB\-\-description\fR or \fB\-d\fR) for \fItext\fR\. If \fItext\fR is flanked by slashes, it is interpreted as a regular expression\. Formula descriptions are cached; the cache is created on the first search, making that search slower than subsequent ones\. . .TP \fBdiy\fR [\fB\-\-name=\fR\fIname\fR] [\fB\-\-version=\fR\fIversion\fR] @@ -187,6 +187,9 @@ Upload logs for a failed build of \fIformula\fR to a new Gist\. \fIformula\fR is usually the name of the formula to install, but it can be specified in several different ways\. See \fISPECIFYING FORMULAE\fR\. . .IP +If \fB\-\-with\-hostname\fR is passed, include the hostname in the Gist\. +. +.IP If \fB\-\-new\-issue\fR is passed, automatically create a new issue in the appropriate GitHub repository as well as creating the Gist\. . .IP @@ -201,12 +204,16 @@ Open Homebrew\'s own homepage in a browser\. Open \fIformula\fR\'s homepage in a browser\. . .TP +\fBinfo\fR +Display brief statistics for your Homebrew installation\. +. +.TP \fBinfo\fR \fIformula\fR Display information about \fIformula\fR\. . .TP \fBinfo\fR \fB\-\-github\fR \fIformula\fR -Open a browser to the GitHub History page for formula \fIformula\fR\. +Open a browser to the GitHub History page for \fIformula\fR\. . .IP To view formula history locally: \fBbrew log \-p <formula>\fR @@ -222,7 +229,7 @@ Pass \fB\-\-all\fR to get information on all formulae, or \fB\-\-installed\fR to See the docs for examples of using the JSON output: \fIhttps://docs\.brew\.sh/Querying\-Brew\.html\fR . .TP -\fBinstall\fR [\fB\-\-debug\fR] [\fB\-\-env=\fR(\fBstd\fR|\fBsuper\fR)] [\fB\-\-ignore\-dependencies\fR|\fB\-\-only\-dependencies\fR] [\fB\-\-cc=\fR\fIcompiler\fR] [\fB\-\-build\-from\-source\fR|\fB\-\-force\-bottle\fR] [\fB\-\-devel\fR|\fB\-\-HEAD\fR] [\fB\-\-keep\-tmp\fR] [\fB\-\-build\-bottle\fR] \fIformula\fR [\fIoptions\fR \.\.\.] +\fBinstall\fR [\fB\-\-debug\fR] [\fB\-\-env=\fR(\fBstd\fR|\fBsuper\fR)] [\fB\-\-ignore\-dependencies\fR|\fB\-\-only\-dependencies\fR] [\fB\-\-cc=\fR\fIcompiler\fR] [\fB\-\-build\-from\-source\fR|\fB\-\-force\-bottle\fR] [\fB\-\-devel\fR|\fB\-\-HEAD\fR] [\fB\-\-keep\-tmp\fR] [\fB\-\-build\-bottle\fR] [\fB\-\-force\fR] [\fB\-\-verbose\fR] \fIformula\fR [\fIoptions\fR \.\.\.] Install \fIformula\fR\. . .IP @@ -268,6 +275,12 @@ If \fB\-\-keep\-tmp\fR is passed, the temporary files created during installatio If \fB\-\-build\-bottle\fR is passed, prepare the formula for eventual bottling during installation\. . .IP +If \fB\-\-force\fR (or \fB\-f\fR) is passed, install without checking for previously installed keg\-only or non\-migrated versions +. +.IP +If \fB\-\-verbose\fR (or \fB\-v\fR) is passed, print the verification and postinstall steps\. +. +.IP Installation options specific to \fIformula\fR may be appended to the command, and can be listed with \fBbrew options\fR \fIformula\fR\. . .TP @@ -310,7 +323,7 @@ List all installed formulae\. If \fB\-\-full\-name\fR is passed, print formulae List all files in the Homebrew prefix not installed by Homebrew\. . .TP -\fBlist\fR, \fBls\fR [\fB\-\-versions\fR [\fB\-\-multiple\fR]] [\fB\-\-pinned\fR] [\fIformulae\fR] +\fBlist\fR, \fBls\fR [\fB\-\-verbose\fR] [\fB\-\-versions\fR [\fB\-\-multiple\fR]] [\fB\-\-pinned\fR] [\fIformulae\fR] List the installed files for \fIformulae\fR\. Combined with \fB\-\-verbose\fR, recursively list the contents of all subdirectories in each \fIformula\fR\'s keg\. . .IP @@ -364,14 +377,14 @@ If \fB\-\-quiet\fR is passed, list only the names of outdated brews (takes prece If \fB\-\-verbose\fR (or \fB\-v\fR) is passed, display detailed version information\. . .IP -If \fB\-\-json=\fR\fIversion\fR is passed, the output will be in JSON format\. The only valid version is \fBv1\fR\. +If \fB\-\-json=\fR\fIversion\fR is passed, the output will be in JSON format\. Currently the only accepted value for \fIversion\fR is \fBv1\fR\. . .IP If \fB\-\-fetch\-HEAD\fR is passed, fetch the upstream repository to detect if the HEAD installation of the formula is outdated\. Otherwise, the repository\'s HEAD will be checked for updates when a new stable or devel version has been released\. . .TP \fBpin\fR \fIformulae\fR -Pin the specified \fIformulae\fR, preventing them from being upgraded when issuing the \fBbrew upgrade <formulae>\fR command (but can still be upgraded as dependencies for other formulae)\. See also \fBunpin\fR\. +Pin the specified \fIformulae\fR, preventing them from being upgraded when issuing the \fBbrew upgrade <formulae>\fR command\. See also \fBunpin\fR\. . .TP \fBpostinstall\fR \fIformula\fR @@ -385,12 +398,18 @@ Remove dead symlinks from the Homebrew prefix\. This is generally not needed, bu If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, show what would be removed, but do not actually remove anything\. . .TP -\fBreadall\fR [tap] -Import all formulae from specified taps (defaults to all installed taps)\. +\fBreadall\fR [\fB\-\-aliases\fR] [\fB\-\-syntax\fR] [\fItaps\fR] +Import all formulae from specified \fItaps\fR (defaults to all installed taps)\. . .IP This can be useful for debugging issues across all formulae when making significant changes to \fBformula\.rb\fR, testing the performance of loading all formulae or to determine if any current formulae have Ruby issues\. . +.IP +If \fB\-\-aliases\fR is passed, also verify any alias symlinks in each tap\. +. +.IP +If \fB\-\-syntax\fR is passed, also syntax\-check all of Homebrew\'s Ruby files\. +. .TP \fBreinstall\fR \fIformula\fR Uninstall and then install \fIformula\fR (with existing install options)\. @@ -418,23 +437,20 @@ Start a Homebrew build environment shell\. Uses our years\-battle\-hardened Home If \fB\-\-env=std\fR is passed, use the standard \fBPATH\fR instead of superenv\'s\. . .TP -\fBstyle\fR [\fB\-\-fix\fR] [\fB\-\-display\-cop\-names\fR] [\fB\-\-only\-cops=\fR[COP1,COP2\.\.]|\fB\-\-except\-cops=\fR[COP1,COP2\.\.]] [\fIfiles\fR|\fItaps\fR|\fIformulae\fR] +\fBstyle\fR [\fB\-\-fix\fR] [\fB\-\-display\-cop\-names\fR] [\fB\-\-only\-cops=\fR\fIcops\fR|\fB\-\-except\-cops=\fR\fIcops\fR] [\fIfiles\fR|\fItaps\fR|\fIformulae\fR] Check formulae or files for conformance to Homebrew style guidelines\. . .IP -\fIformulae\fR and \fIfiles\fR may not be combined\. If both are omitted, style will run style checks on the whole Homebrew \fBLibrary\fR, including core code and all formulae\. +Lists of \fIfiles\fR, \fItaps\fR and \fIformulae\fR may not be combined\. If none are provided, \fBstyle\fR will run style checks on the whole Homebrew library, including core code and all formulae\. . .IP -If \fB\-\-fix\fR is passed, style violations will be automatically fixed using RuboCop\'s \fB\-\-auto\-correct\fR feature\. +If \fB\-\-fix\fR is passed, automatically fix style violations using RuboCop\'s auto\-correct feature\. . .IP -If \fB\-\-display\-cop\-names\fR is passed, the RuboCop cop name for each violation is included in the output\. +If \fB\-\-display\-cop\-names\fR is passed, include the RuboCop cop name for each violation in the output\. . .IP -If \fB\-\-only\-cops\fR is passed, only the given Rubocop cop(s)\' violations would be checked\. -. -.IP -If \fB\-\-except\-cops\fR is passed, the given Rubocop cop(s)\' checks would be skipped\. +Passing \fB\-\-only\-cops=\fR\fIcops\fR will check for violations of only the listed RuboCop \fIcops\fR, while \fB\-\-except\-cops=\fR\fIcops\fR will skip checking the listed \fIcops\fR\. For either option \fIcops\fR should be a comma\-separated list of cop names\. . .IP Exits with a non\-zero status if any style violations are found\. @@ -602,8 +618,14 @@ Display Homebrew\'s Cellar path\. \fIDefault:\fR \fB$(brew \-\-prefix)/Cellar\fR Display the location in the cellar where \fIformula\fR would be installed, without any sort of versioned directory as the last path\. . .TP -\fB\-\-env\fR -Show a summary of the Homebrew build environment\. +\fB\-\-env\fR [\fB\-\-shell=\fR(\fIshell\fR|\fBauto\fR)|\fB\-\-plain\fR] +Show a summary of the Homebrew build environment as a plain list\. +. +.IP +Pass \fB\-\-shell=\fR\fIshell\fR to generate a list of environment variables for the specified shell, or \fB\-\-shell=auto\fR to detect the current shell\. +. +.IP +If the command\'s output is sent through a pipe and no shell is specified, the list is formatted for export to \fBbash\fR(1) unless \fB\-\-plain\fR is passed\. . .TP \fB\-\-prefix\fR @@ -628,7 +650,7 @@ Print the version number of Homebrew to standard output and exit\. .SH "DEVELOPER COMMANDS" . .TP -\fBaudit\fR [\fB\-\-strict\fR] [\fB\-\-fix\fR] [\fB\-\-online\fR] [\fB\-\-new\-formula\fR] [\fB\-\-display\-cop\-names\fR] [\fB\-\-display\-filename\fR] [\fB\-\-only=\fR\fImethod\fR|\fB\-\-except=\fR\fImethod\fR] [\fB\-\-only\-cops=\fR[COP1,COP2\.\.]|\fB\-\-except\-cops=\fR[COP1,COP2\.\.]] [\fIformulae\fR] +\fBaudit\fR [\fB\-\-strict\fR] [\fB\-\-fix\fR] [\fB\-\-online\fR] [\fB\-\-new\-formula\fR] [\fB\-\-display\-cop\-names\fR] [\fB\-\-display\-filename\fR] [\fB\-\-only=\fR\fImethod\fR|\fB\-\-except=\fR\fImethod\fR] [\fB\-\-only\-cops=\fR\fIcops\fR|\fB\-\-except\-cops=\fR\fIcops\fR] [\fIformulae\fR] Check \fIformulae\fR for Homebrew coding style violations\. This should be run before submitting a new formula\. . .IP @@ -638,7 +660,7 @@ If no \fIformulae\fR are provided, all of them are checked\. If \fB\-\-strict\fR is passed, additional checks are run, including RuboCop style checks\. . .IP -If \fB\-\-fix\fR is passed, style violations will be automatically fixed using RuboCop\'s \fB\-\-auto\-correct\fR feature\. +If \fB\-\-fix\fR is passed, style violations will be automatically fixed using RuboCop\'s auto\-correct feature\. . .IP If \fB\-\-online\fR is passed, additional slower checks that require a network connection are run\. @@ -653,16 +675,10 @@ If \fB\-\-display\-cop\-names\fR is passed, the RuboCop cop name for each violat If \fB\-\-display\-filename\fR 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\. . .IP -If \fB\-\-only\fR is passed, only the methods named \fBaudit_<method>\fR will be run\. +Passing \fB\-\-only=\fR\fImethod\fR will run only the methods named \fBaudit_<method>\fR, while \fB\-\-except=\fR\fImethod\fR will skip the methods named \fBaudit_<method>\fR\. For either option \fImethod\fR should be a comma\-separated list\. . .IP -If \fB\-\-except\fR is passed, the methods named \fBaudit_<method>\fR will not be run\. -. -.IP -If \fB\-\-only\-cops\fR is passed, only the given Rubocop cop(s)\' violations would be checked\. -. -.IP -If \fB\-\-except\-cops\fR is passed, the given Rubocop cop(s)\' checks would be skipped\. +Passing \fB\-\-only\-cops=\fR\fIcops\fR will check for violations of only the listed RuboCop \fIcops\fR, while \fB\-\-except\-cops=\fR\fIcops\fR will skip checking the listed \fIcops\fR\. For either option \fIcops\fR should be a comma\-separated list of cop names\. . .IP \fBaudit\fR exits with a non\-zero status if any errors are found\. This is useful, for instance, for implementing pre\-commit hooks\. @@ -731,6 +747,9 @@ If \fB\-\-message=\fR\fImessage\fR is passed, append \fImessage\fR to the defaul If \fB\-\-no\-browse\fR is passed, don\'t pass the \fB\-\-browse\fR argument to \fBhub\fR which opens the pull request URL in a browser\. Instead, output it to the command line\. . .IP +If \fB\-\-quiet\fR is passed, don\'t output replacement messages or warn about duplicate pull requests\. +. +.IP 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\. . .TP |