admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

Merge pull request #5855 from EricFromCanada/help-wrap-output

Browse Source 
help: rewrap output to 80 columns
This commit is contained in:
Mike McQuaid 2019-03-12 19:25:28 +00:00 committed by GitHub
commit 7ed0627586
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 166 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
Library/Homebrew/cli_parser.rb
View File

@ -2,6 +2,9 @@ require "optparse"
require "ostruct" require "ostruct"
require "set" require "set"
COMMAND_DESC_WIDTH = 80
OPTION_DESC_WIDTH = 43
module Homebrew module Homebrew
module CLI module CLI
class Parser class Parser
@ -29,7 +32,6 @@ module Homebrew
@conflicts = [] @conflicts = []
@switch_sources = {} @switch_sources = {}
@processed_options = [] @processed_options = []
@desc_line_length = 43
@hide_from_man_page = false @hide_from_man_page = false
instance_eval(&block) instance_eval(&block)
post_initialize post_initialize
@ -64,7 +66,7 @@ module Homebrew
alias switch_option switch alias switch_option switch
def usage_banner(text) def usage_banner(text)
@parser.banner = "#{text}\n" @parser.banner = Formatter.wrap("#{text}\n", COMMAND_DESC_WIDTH)
end end
def usage_banner_text def usage_banner_text
@ -198,7 +200,7 @@ module Homebrew
end end
def wrap_option_desc(desc) def wrap_option_desc(desc)
Formatter.wrap(desc, @desc_line_length).split("\n") Formatter.wrap(desc, OPTION_DESC_WIDTH).split("\n")
end end
def set_constraints(name, depends_on:, required_for:) def set_constraints(name, depends_on:, required_for:)

2
Library/Homebrew/cmd/--cellar.rb
View File

@ -6,7 +6,7 @@ module Homebrew
def __cellar_args def __cellar_args
Homebrew::CLI::Parser.new do Homebrew::CLI::Parser.new do
usage_banner <<~EOS usage_banner <<~EOS
`--cache` [<formula>] `--cellar` [<formula>]
Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if
that directory doesn't exist, `$(brew --repository)/Cellar`. that directory doesn't exist, `$(brew --repository)/Cellar`.

4
Library/Homebrew/cmd/analytics.rb
View File

@ -6,9 +6,9 @@ module Homebrew
def analytics_args def analytics_args
Homebrew::CLI::Parser.new do Homebrew::CLI::Parser.new do
usage_banner <<~EOS usage_banner <<~EOS
`analytics` (`on`|`off`) [`state`] [`regenerate-uuid`] `analytics` [`on`|`off`|`state`|`regenerate-uuid`]
If `on`|`off` is passed, turn Homebrew's analytics on or off respectively. If `on` or `off` is passed, turn Homebrew's analytics on or off respectively.
If `state` is passed, display anonymous user behaviour analytics state. If `state` is passed, display anonymous user behaviour analytics state.
Read more at <https://docs.brew.sh/Analytics>. Read more at <https://docs.brew.sh/Analytics>.

3
Library/Homebrew/cmd/install.rb
View File

@ -64,7 +64,8 @@ module Homebrew
description: "Don't delete the temporary files created during installation." description: "Don't delete the temporary files created during installation."
switch "--build-bottle", switch "--build-bottle",
description: "Prepare the formula for eventual bottling during installation." description: "Prepare the formula for eventual bottling during installation."
switch "--bottle-arch=", flag "--bottle-arch=",
depends_on: "--build-bottle",
description: "Optimise bottles for the given architecture rather than the oldest "\ description: "Optimise bottles for the given architecture rather than the oldest "\
"architecture supported by the version of macOS the bottles are built on." "architecture supported by the version of macOS the bottles are built on."
switch :force, switch :force,

2
Library/Homebrew/dev-cmd/bottle.rb
View File

@ -53,7 +53,7 @@ module Homebrew
switch "--or-later", switch "--or-later",
description: "Append `_or_later` to the bottle tag." description: "Append `_or_later` to the bottle tag."
switch "--force-core-tap", switch "--force-core-tap",
description: "Build a bottle even if <formula> is not in homebrew/core or any installed taps." description: "Build a bottle even if <formula> is not in `homebrew/core` or any installed taps."
switch "--no-rebuild", switch "--no-rebuild",
description: "If the formula specifies a rebuild version, remove it from the generated DSL." description: "If the formula specifies a rebuild version, remove it from the generated DSL."
switch "--keep-old", switch "--keep-old",

2
Library/Homebrew/dev-cmd/prof.rb
View File

@ -1,3 +1,5 @@
require "cli_parser"
module Homebrew module Homebrew
module_function module_function

2
Library/Homebrew/dev-cmd/pull.rb
View File

@ -30,7 +30,7 @@ module Homebrew
Get a patch from a GitHub commit or pull request and apply it to Homebrew. 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. Optionally, publish updated bottles for the formulae changed by the patch.
Each <patch> may be the number of a PR in homebrew/core, the URL of a PR Each <patch> may be the number of a PR in `homebrew/core`, the URL of a PR
on GitHub, the URL of a commit on GitHub or a "https://jenkins.brew.sh/job/..." testing job URL. on GitHub, the URL of a commit on GitHub or a "https://jenkins.brew.sh/job/..." testing job URL.
EOS EOS
switch "--bottle", switch "--bottle",

13
Library/Homebrew/help.rb
View File

@ -31,6 +31,7 @@ EOS
# NOTE Keep lines less than 80 characters! Wrapping is just not cricket. # NOTE Keep lines less than 80 characters! Wrapping is just not cricket.
# NOTE The reason the string is at the top is so 25 lines is easy to measure! # NOTE The reason the string is at the top is so 25 lines is easy to measure!
require "cli_parser"
require "commands" require "commands"
module Homebrew module Homebrew
@ -92,15 +93,13 @@ module Homebrew
opoo "No help text in: #{path}" if ARGV.homebrew_developer? opoo "No help text in: #{path}" if ARGV.homebrew_developer?
HOMEBREW_HELP HOMEBREW_HELP
else else
help_lines.map do |line| Formatter.wrap(help_lines.join.gsub(/^ /, ""), COMMAND_DESC_WIDTH)
line.gsub(/^ /, "") .sub("@hide_from_man_page ", "")
.sub(/^\* /, "#{Tty.bold}Usage: brew#{Tty.reset} ") .sub(/^\* /, "#{Tty.bold}Usage: brew#{Tty.reset} ")
.gsub(/`(.*?)`/, "#{Tty.bold}\\1#{Tty.reset}") .gsub(/`(.*?)`/m, "#{Tty.bold}\\1#{Tty.reset}")
.gsub(%r{<([^\s]+?://[^\s]+?)>}) { |url| Formatter.url(url) } .gsub(%r{<([^\s]+?://[^\s]+?)>}) { |url| Formatter.url(url) }
.gsub(/<(.*?)>/, "#{Tty.underline}\\1#{Tty.reset}") .gsub(/<(.*?)>/m, "#{Tty.underline}\\1#{Tty.reset}")
.gsub(/\*(.*?)\*/, "#{Tty.underline}\\1#{Tty.reset}") .gsub(/\*(.*?)\*/m, "#{Tty.underline}\\1#{Tty.reset}")
.gsub("@hide_from_man_page", "")
end.join.strip
end end
end end
end end

15
Library/Homebrew/utils/formatter.rb
View File

@ -31,8 +31,21 @@ module Formatter
label(label, string, :red) label(label, string, :red)
end end
# Wraps text to fit within a given number of columns using regular expressions that:
#
# 1. convert hard-wrapped paragraphs to a single line
# 2. find any option descriptions longer than a pre-set length and wrap between words
# with a hanging indent, without breaking any words that overflow
# 3. wrap any remaining description lines that need wrapping with the same indent
# 4. wrap all lines to the given width.
# @see https://macromates.com/blog/2006/wrapping-text-with-regular-expressions/
def wrap(s, width = 172) def wrap(s, width = 172)
s.gsub(/(.{1,#{width}})(\s+|\Z)/, "\\1\n") desc = OPTION_DESC_WIDTH
indent = width - desc
s.gsub(/(?<=\S) *\n(?=\S)/, " ")
.gsub(/^( +-.+ +(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)\n?/, "\\1\\2\n" + " " * indent)
.gsub(/^( {#{indent}}(?=\S.{#{desc}}))(.{1,#{desc}})( +|$)\n?/, "\\1\\2\n" + " " * indent)
.gsub(/(.{1,#{width}})( +|$)\n?/, "\\1\n")
end end
def url(string) def url(string)

226
docs/Manpage.md
View File

@ -38,12 +38,12 @@ If no search term is given, all locally available formulae are listed.
## COMMANDS ## COMMANDS
### `analytics` (`on`|`off`) [`state`] [`regenerate-uuid`] ### `analytics` [`on`|`off`|`state`|`regenerate-uuid`]
If `on`|`off` is passed, turn Homebrew's analytics on or off respectively. If `on` or `off` is passed, turn Homebrew's analytics on or off respectively.
If `state` is passed, display anonymous user behaviour analytics state. If `state` is passed, display anonymous user behaviour analytics state. Read
Read more at <https://docs.brew.sh/Analytics>. more at <https://docs.brew.sh/Analytics>.
If `regenerate-uuid` is passed, regenerate UUID used in Homebrew's analytics. If `regenerate-uuid` is passed, regenerate UUID used in Homebrew's analytics.
@ -53,9 +53,9 @@ Display the source of *`formula`*.
### `cleanup` [*`options`*] [*`formula`*|*`cask`*] ### `cleanup` [*`options`*] [*`formula`*|*`cask`*]
Remove stale lock files and outdated downloads for formulae and casks, Remove stale lock files and outdated downloads for formulae and casks, and
and remove old versions of installed formulae. If arguments are specified, remove old versions of installed formulae. If arguments are specified, only do
only do this for the specified formulae and casks. this for the specified formulae and casks.
* `--prune`: * `--prune`:
Remove all cache files older than specified *`days`*. Remove all cache files older than specified *`days`*.
@ -79,14 +79,13 @@ Show a list of built-in and external commands.
### `config` ### `config`
Show Homebrew and system configuration useful for debugging. If you file Show Homebrew and system configuration useful for debugging. If you file a bug
a bug report, you will likely be asked for this information if you do not report, you will likely be asked for this information if you do not provide it.
provide it.
### `deps` [*`options`*] *`formula`* ### `deps` [*`options`*] *`formula`*
Show dependencies for *`formula`*. When given multiple formula arguments, Show dependencies for *`formula`*. When given multiple formula arguments, show the
show the intersection of dependencies for *`formula`*. intersection of dependencies for *`formula`*.
* `--1`: * `--1`:
Only show dependencies one level down, instead of recursing. Only show dependencies one level down, instead of recursing.
@ -119,9 +118,9 @@ show the intersection of dependencies for *`formula`*.
### `desc` [*`options`*] (*`text`*|`/`*`text`*`/`|*`formula`*) ### `desc` [*`options`*] (*`text`*|`/`*`text`*`/`|*`formula`*)
Display *`formula`*'s name and one-line description. Display *`formula`*'s name and one-line description. Formula descriptions are
Formula descriptions are cached; the cache is created on the cached; the cache is created on the first search, making that search slower than
first search, making that search slower than subsequent ones. subsequent ones.
* `-s`, `--search`: * `-s`, `--search`:
Search both name and description for provided *`text`*. If *`text`* is flanked by slashes, it is interpreted as a regular expression. Search both name and description for provided *`text`*. If *`text`* is flanked by slashes, it is interpreted as a regular expression.
@ -132,9 +131,9 @@ first search, making that search slower than subsequent ones.
### `diy` [*`options`*] ### `diy` [*`options`*]
Automatically determine the installation prefix for non-Homebrew software. Automatically determine the installation prefix for non-Homebrew software. Using
Using the output from this command, you can install your own software into the output from this command, you can install your own software into the Cellar
the Cellar and then link it into Homebrew's prefix with `brew link`. and then link it into Homebrew's prefix with `brew link`.
* `--name`: * `--name`:
Explicitly set the provided *`name`* of the package being installed. Explicitly set the provided *`name`* of the package being installed.
@ -143,11 +142,11 @@ the Cellar and then link it into Homebrew's prefix with `brew link`.
### `doctor` [*`options`*] ### `doctor` [*`options`*]
Check your system for potential problems. Doctor exits with a non-zero status Check your system for potential problems. Doctor exits with a non-zero status if
if any potential problems are found. Please note that these warnings are just any potential problems are found. Please note that these warnings are just used
used to help the Homebrew maintainers with debugging if you file an issue. If to help the Homebrew maintainers with debugging if you file an issue. If
everything you use Homebrew for is working fine: please don't worry or file everything you use Homebrew for is working fine: please don't worry or file an
an issue; just ignore this. issue; just ignore this.
* `--list-checks`: * `--list-checks`:
List all audit methods. List all audit methods.
@ -156,8 +155,8 @@ an issue; just ignore this.
### `fetch` [*`options`*] *`formula`* ### `fetch` [*`options`*] *`formula`*
Download the source packages for the given *`formula`*. Download the source packages for the given *`formula`*. For tarballs, also print
For tarballs, also print SHA-256 checksums. SHA-256 checksums.
* `--HEAD`: * `--HEAD`:
Fetch HEAD version instead of stable version. Fetch HEAD version instead of stable version.
@ -192,8 +191,8 @@ If no logs are found, an error message is presented.
### `home` [*`formula`*] ### `home` [*`formula`*]
Open *`formula`*'s homepage in a browser. If no formula is provided, Open *`formula`*'s homepage in a browser. If no formula is provided, open
open Homebrew's own homepage in a browser. Homebrew's own homepage in a browser.
### `info` [*`formula`*] ### `info` [*`formula`*]
@ -221,7 +220,8 @@ Install *`formula`*.
*`formula`* is usually the name of the formula to install, but it can be specified *`formula`* is usually the name of the formula to install, but it can be specified
in several different ways. in several different ways.
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will be run for the installed formulae or, every 30 days, for all formulae. Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will be run for the
installed formulae or, every 30 days, for all formulae.
* `--env`: * `--env`:
If `std` is passed, use the standard build environment instead of superenv.If `super` is passed, use superenv even if the formula specifies the standard build environment. If `std` is passed, use the standard build environment instead of superenv.If `super` is passed, use superenv even if the formula specifies the standard build environment.
@ -262,8 +262,8 @@ Show installed formulae that are not dependencies of another installed formula.
### `ln`, `link` [*`options`*] *`formula`* ### `ln`, `link` [*`options`*] *`formula`*
Symlink all of *`formula`*'s installed files into the Homebrew prefix. This Symlink all of *`formula`*'s installed files into the Homebrew prefix. This is
is done automatically when you install formulae but can be useful for DIY done automatically when you install formulae but can be useful for DIY
installations. installations.
* `--overwrite`: * `--overwrite`:
@ -309,13 +309,12 @@ Show the `git log` for the given *`formula`*.
### `migrate` [*`options`*] *`formula`* ### `migrate` [*`options`*] *`formula`*
Migrate renamed packages to new name, where *`formula`* are old names of Migrate renamed packages to new name, where *`formula`* are old names of packages.
packages.
### `missing` [*`options`*] [*`formule`*] ### `missing` [*`options`*] [*`formule`*]
Check the given *`formula`* for missing dependencies. If no *`formula`* are Check the given *`formula`* for missing dependencies. If no *`formula`* are given,
given, check all installed brews. check all installed brews.
`missing` exits with a non-zero status if any formulae are missing dependencies. `missing` exits with a non-zero status if any formulae are missing dependencies.
@ -347,8 +346,8 @@ suppressed otherwise.
### `pin` *`formula`* ### `pin` *`formula`*
Pin the specified *`formula`*, preventing them from being upgraded when Pin the specified *`formula`*, preventing them from being upgraded when issuing
issuing the `brew upgrade` *`formula`* command. See also `unpin`. the `brew upgrade` *`formula`* command. See also `unpin`.
### `postinstall` *`formula`* ### `postinstall` *`formula`*
@ -356,10 +355,10 @@ Rerun the post-install steps for *`formula`*.
### `readall` [*`options`*] [*`tap`*] ### `readall` [*`options`*] [*`tap`*]
Import all formulae from specified *`tap`* (defaults to all installed taps). Import all formulae from specified *`tap`* (defaults to all installed taps). This
This can be useful for debugging issues across all formulae when making can be useful for debugging issues across all formulae when making significant
significant changes to `formula.rb`, testing the performance of loading changes to `formula.rb`, testing the performance of loading all formulae or to
all formulae or to determine if any current formulae have Ruby issues. determine if any current formulae have Ruby issues.
* `--aliases`: * `--aliases`:
Verify any alias symlinks in each tap. Verify any alias symlinks in each tap.
@ -368,9 +367,11 @@ all formulae or to determine if any current formulae have Ruby issues.
### `reinstall` [*`options`*] *`formula`* ### `reinstall` [*`options`*] *`formula`*
Uninstall and then install *`formula`* (with existing and any appended install options). Uninstall and then install *`formula`* (with existing and any appended install
options).
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will be run for the reinstalled formulae or, every 30 days, for all formulae. Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will be run for the
reinstalled formulae or, every 30 days, for all formulae.
* `-s`, `--build-from-source`: * `-s`, `--build-from-source`:
Compile *`formula`* from source even if a bottle is available. Compile *`formula`* from source even if a bottle is available.
@ -383,12 +384,13 @@ Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will be run for the
### `search` [*`options`*] [*`text`*|`/`*`text`*`/`] ### `search` [*`options`*] [*`text`*|`/`*`text`*`/`]
Perform a substring search of cask tokens and formula names for *`text`*. If *`text`* Perform a substring search of cask tokens and formula names for *`text`*. If
is surrounded with slashes, then it is interpreted as a regular expression. *`text`* is surrounded with slashes, then it is interpreted as a regular
The search for *`text`* is extended online to `homebrew/core` and `homebrew/cask`. expression. The search for *`text`* is extended online to `homebrew/core` and
`homebrew/cask`.
If no *`text`* is passed, display all locally available formulae (including tapped ones). If no *`text`* is passed, display all locally available formulae (including tapped
No online search is performed. ones). No online search is performed.
* `--casks`: * `--casks`:
Display all locally available casks (including tapped ones). No online search is performed. Display all locally available casks (including tapped ones). No online search is performed.
@ -410,10 +412,10 @@ Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will be run for the
### `sh` [*`options`*] ### `sh` [*`options`*]
Start a Homebrew build environment shell. Uses our years-battle-hardened Start a Homebrew build environment shell. Uses our years-battle-hardened
Homebrew build logic to help your `./configure && make && make install` Homebrew build logic to help your `./configure && make && make install` or even
or even your `gem install` succeed. Especially handy if you run Homebrew your `gem install` succeed. Especially handy if you run Homebrew in an
in an Xcode-only configuration since it adds tools like `make` to your `PATH` Xcode-only configuration since it adds tools like `make` to your `PATH` which
which otherwise build systems would not find. otherwise build systems would not find.
* `--env`: * `--env`:
Use the standard `PATH` instead of superenv's, when *`std`* is passed Use the standard `PATH` instead of superenv's, when *`std`* is passed
@ -429,9 +431,9 @@ Consider adding evaluating the output in your dotfiles (e.g. `~/.profile`) with
Check formulae or files for conformance to Homebrew style guidelines. Check formulae or files for conformance to Homebrew style guidelines.
Lists of *`file`*, *`tap`* and *`formula`* may not be combined. If none are Lists of *`file`*, *`tap`* and *`formula`* may not be combined. If none are provided,
provided, `style` will run style checks on the whole Homebrew library, `style` will run style checks on the whole Homebrew library, including core code
including core code and all formulae. and all formulae.
* `--fix`: * `--fix`:
Fix style violations automatically using RuboCop's auto-correct feature. Fix style violations automatically using RuboCop's auto-correct feature.
@ -452,15 +454,15 @@ Tap a formula repository.
List all installed taps when no arguments are passed. List all installed taps when no arguments are passed.
With *`URL`* unspecified, taps a formula repository from GitHub using HTTPS. With *`URL`* unspecified, taps a formula repository from GitHub using HTTPS. Since
Since so many taps are hosted on GitHub, this command is a shortcut for so many taps are hosted on GitHub, this command is a shortcut for `brew tap`
`brew tap` *`user`*`/`*`repo`* `https://github.com/`*`user`*`/homebrew-`*`repo`*. *`user`*`/`*`repo`* `https://github.com/`*`user`*`/homebrew-`*`repo`*.
With *`URL`* specified, taps a formula repository from anywhere, using With *`URL`* specified, taps a formula repository from anywhere, using any
any transport protocol that `git` handles. The one-argument form of `tap` transport protocol that `git` handles. The one-argument form of `tap` simplifies
simplifies but also limits. This two-argument command makes no but also limits. This two-argument command makes no assumptions, so taps can be
assumptions, so taps can be cloned from places other than GitHub and cloned from places other than GitHub and using protocols other than HTTPS, e.g.,
using protocols other than HTTPS, e.g., SSH, GIT, HTTP, FTP(S), RSYNC. SSH, GIT, HTTP, FTP(S), RSYNC.
* `--full`: * `--full`:
Use a full clone when tapping a repository. By default, the repository is cloned as a shallow copy (`--depth=1`). To convert a shallow copy to a full copy, you can retap passing `--full` without first untapping. Use a full clone when tapping a repository. By default, the repository is cloned as a shallow copy (`--depth=1`). To convert a shallow copy to a full copy, you can retap passing `--full` without first untapping.
@ -475,8 +477,8 @@ using protocols other than HTTPS, e.g., SSH, GIT, HTTP, FTP(S), RSYNC.
### `tap-info` [*`options`*] [*`tap`*] ### `tap-info` [*`options`*] [*`tap`*]
Display detailed information about one or more provided *`tap`*. Display detailed information about one or more provided *`tap`*. Display a brief
Display a brief summary of all installed taps if no *`tap`* are passed. summary of all installed taps if no *`tap`* are passed.
* `--installed`: * `--installed`:
Display information on all installed taps. Display information on all installed taps.
@ -501,17 +503,17 @@ Uninstall *`formula`*.
### `unlink` [*`options`*] *`formula`* ### `unlink` [*`options`*] *`formula`*
Remove symlinks for *`formula`* from the Homebrew prefix. This can be useful Remove symlinks for *`formula`* from the Homebrew prefix. This can be useful for
for temporarily disabling a formula: temporarily disabling a formula: `brew unlink` *`formula`* `&&` *`commands`* `&&
`brew unlink` *`formula`* `&&` *`commands`* `&& brew link` *`formula`* brew link` *`formula`*
* `-n`, `--dry-run`: * `-n`, `--dry-run`:
List all files which would be unlinked, but will not actually unlink or delete any files. List all files which would be unlinked, but will not actually unlink or delete any files.
### `unpack` [*`options`*] *`formula`* ### `unpack` [*`options`*] *`formula`*
Unpack the source files for *`formula`* into subdirectories of the current Unpack the source files for *`formula`* into subdirectories of the current working
working directory. directory.
* `--destdir`: * `--destdir`:
Create subdirectories in the directory named by *`path`* instead. Create subdirectories in the directory named by *`path`* instead.
@ -522,8 +524,8 @@ working directory.
### `unpin` *`formula`* ### `unpin` *`formula`*
Unpin *`formula`*, allowing them to be upgraded by `brew upgrade` *`formula`*. Unpin *`formula`*, allowing them to be upgraded by `brew upgrade` *`formula`*. See
See also `pin`. also `pin`.
### `untap` *`tap`* ### `untap` *`tap`*
@ -543,12 +545,14 @@ Fetches and resets Homebrew and all tap repositories (or any specified `reposito
### `upgrade` [*`options`*] *`formula`* ### `upgrade` [*`options`*] *`formula`*
Upgrade outdated, unpinned brews (with existing and any appended install options). Upgrade outdated, unpinned brews (with existing and any appended install
options).
If *`formula`* are given, upgrade only the specified brews (unless they If *`formula`* are given, upgrade only the specified brews (unless they are
are pinned; see `pin`, `unpin`). pinned; see `pin`, `unpin`).
Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will be run for the upgraded formulae or, every 30 days, for all formulae. Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will be run for the
upgraded formulae or, every 30 days, for all formulae.
* `-s`, `--build-from-source`: * `-s`, `--build-from-source`:
Compile *`formula`* from source even if a bottle is available. Compile *`formula`* from source even if a bottle is available.
@ -565,12 +569,11 @@ Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will be run for the
### `uses` [*`options`*] *`formula`* ### `uses` [*`options`*] *`formula`*
Show the formulae that specify *`formula`* as a dependency. When given Show the formulae that specify *`formula`* as a dependency. When given multiple
multiple formula arguments, show the intersection of formulae that use formula arguments, show the intersection of formulae that use *`formula`*.
*`formula`*.
By default, `uses` shows all formulae that specify *`formula`* as a required By default, `uses` shows all formulae that specify *`formula`* as a required or
or recommended dependency. recommended dependency.
By default, `uses` shows usage of *`formula`* by stable builds. By default, `uses` shows usage of *`formula`* by stable builds.
@ -602,10 +605,10 @@ If *`formula`* is provided, display the file or directory used to cache *`formul
* `--force-bottle`: * `--force-bottle`:
Show the cache file used when pouring a bottle. Show the cache file used when pouring a bottle.
### `--cache` [*`formula`*] ### `--cellar` [*`formula`*]
Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if Display Homebrew's Cellar path. *Default:* `$(brew --prefix)/Cellar`, or if that
that directory doesn't exist, `$(brew --repository)/Cellar`. directory doesn't exist, `$(brew --repository)/Cellar`.
If *`formula`* is provided, display the location in the cellar where *`formula`* If *`formula`* is provided, display the location in the cellar where *`formula`*
would be installed, without any sort of versioned directory as the last path. would be installed, without any sort of versioned directory as the last path.
@ -614,8 +617,8 @@ would be installed, without any sort of versioned directory as the last path.
Show a summary of the Homebrew build environment as a plain list. Show a summary of the Homebrew build environment as a plain list.
If the command's output is sent through a pipe and no shell is specified, If the command's output is sent through a pipe and no shell is specified, the
the list is formatted for export to `bash`(1) unless `--plain` is passed. list is formatted for export to `bash`(1) unless `--plain` is passed.
* `--shell`: * `--shell`:
Generate a list of environment variables for the specified shell, or `--shell=auto` to detect the current shell. Generate a list of environment variables for the specified shell, or `--shell=auto` to detect the current shell.
@ -627,19 +630,20 @@ the list is formatted for export to `bash`(1) unless `--plain` is passed.
Display Homebrew's install path. *Default:* `/usr/local` on macOS and Display Homebrew's install path. *Default:* `/usr/local` on macOS and
`/home/linuxbrew/.linuxbrew` on Linux. `/home/linuxbrew/.linuxbrew` on Linux.
If *`formula`* is provided, display the location in the cellar where *`formula`* If *`formula`* is provided, display the location in the cellar where *`formula`* is
is or would be installed. or would be installed.
### `--repository` [*`user`*`/`*`repo`*] ### `--repository` [*`user`*`/`*`repo`*]
Display where Homebrew's `.git` directory is located. Display where Homebrew's `.git` directory is located.
If *`user`*`/`*`repo`* are provided, display where tap *`user`*`/`*`repo`*'s directory is located. If *`user`*`/`*`repo`* are provided, display where tap *`user`*`/`*`repo`*'s directory
is located.
### `--version` ### `--version`
Print the version number of Homebrew, Homebrew/homebrew-core and Homebrew/homebrew-cask Print the version number of Homebrew, Homebrew/homebrew-core and
(if tapped) to standard output and exit. Homebrew/homebrew-cask (if tapped) to standard output and exit.
## DEVELOPER COMMANDS ## DEVELOPER COMMANDS
@ -647,8 +651,8 @@ Print the version number of Homebrew, Homebrew/homebrew-core and Homebrew/homebr
Check *`formula`* for Homebrew coding style violations. This should be run before Check *`formula`* for Homebrew coding style violations. This should be run before
submitting a new formula. Will exit with a non-zero status if any errors are 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. found, which can be useful for implementing pre-commit hooks. If no *`formula`*
If no *`formula`* are provided, all of them are checked. are provided, all of them are checked.
* `--strict`: * `--strict`:
Run additional style checks, including RuboCop style checks. Run additional style checks, including RuboCop style checks.
@ -676,17 +680,16 @@ If no *`formula`* are provided, all of them are checked.
### `bottle` [*`options`*] *`formula`* ### `bottle` [*`options`*] *`formula`*
Generate a bottle (binary package) from a formula that was installed with Generate a bottle (binary package) from a formula that was installed with
`--build-bottle`. `--build-bottle`. If the formula specifies a rebuild version, it will be
If the formula specifies a rebuild version, it will be incremented in the incremented in the generated DSL. Passing `--keep-old` will attempt to keep it
generated DSL. Passing `--keep-old` will attempt to keep it at its original at its original value, while `--no-rebuild` will remove it.
value, while `--no-rebuild` will remove it.
* `--skip-relocation`: * `--skip-relocation`:
Do not check if the bottle can be marked as relocatable. Do not check if the bottle can be marked as relocatable.
* `--or-later`: * `--or-later`:
Append `_or_later` to the bottle tag. Append `_or_later` to the bottle tag.
* `--force-core-tap`: * `--force-core-tap`:
Build a bottle even if *`formula`* is not in homebrew/core or any installed taps. Build a bottle even if *`formula`* is not in `homebrew/core` or any installed taps.
* `--no-rebuild`: * `--no-rebuild`:
If the formula specifies a rebuild version, remove it from the generated DSL. If the formula specifies a rebuild version, remove it from the generated DSL.
* `--keep-old`: * `--keep-old`:
@ -799,8 +802,8 @@ Enter the interactive Homebrew Ruby shell.
### `linkage` [*`options`*] [*`formula`*] ### `linkage` [*`options`*] [*`formula`*]
Check the library links for kegs of installed formulae. Check the library links for kegs of installed formulae. Raises an error if run
Raises an error if run on uninstalled formulae. on uninstalled formulae.
* `--test`: * `--test`:
Display only missing libraries and exit with a non-zero status if any missing libraries are found. Display only missing libraries and exit with a non-zero status if any missing libraries are found.
@ -827,8 +830,9 @@ Run Homebrew with the Ruby profiler e.g. `brew prof readall`.
Get a patch from a GitHub commit or pull request and apply it to Homebrew. 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. Optionally, publish updated bottles for the formulae changed by the patch.
Each *`patch`* may be the number of a PR in homebrew/core, the URL of a PR Each *`patch`* may be the number of a PR in `homebrew/core`, the URL of a PR on
on GitHub, the URL of a commit on GitHub or a "https://jenkins.brew.sh/job/..." testing job URL. GitHub, the URL of a commit on GitHub or a "https://jenkins.brew.sh/job/..."
testing job URL.
* `--bottle`: * `--bottle`:
Handle bottles, pulling the bottle-update commit and publishing files on Bintray. Handle bottles, pulling the bottle-update commit and publishing files on Bintray.
@ -855,17 +859,17 @@ on GitHub, the URL of a commit on GitHub or a "https://jenkins.brew.sh/job/..."
### `release-notes` [*`options`*] [*`previous_tag`*] [*`end_ref`*] ### `release-notes` [*`options`*] [*`previous_tag`*] [*`end_ref`*]
Print 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
If no *`previous_tag`* is provided it defaults to the latest tag. *`previous_tag`* is provided it defaults to the latest tag. If no *`end_ref`* is
If no *`end_ref`* is provided it defaults to `origin/master`. provided it defaults to `origin/master`.
* `--markdown`: * `--markdown`:
Print as a Markdown list. Print as a Markdown list.
### `ruby` [`-e`]: ### `ruby` [`-e`]:
Run a Ruby instance with Homebrew's libraries loaded e.g. Run a Ruby instance with Homebrew's libraries loaded e.g. `brew ruby -e "puts
`brew ruby -e "puts :gcc.f.deps"` or `brew ruby script.rb` :gcc.f.deps"` or `brew ruby script.rb`
* `-e`: * `-e`:
Execute the provided string argument as a script. Execute the provided string argument as a script.
@ -876,9 +880,9 @@ Generate the template files for a new tap.
### `test` [*`options`*] *`formula`* ### `test` [*`options`*] *`formula`*
Run the test method provided by an installed formula. Run the test method provided by an installed formula. There is no standard
There is no standard output or return code, but generally it should notify the output or return code, but generally it should notify the user if something is
user if something is wrong with the installed formula. wrong with the installed formula.
*Example:* `brew install jruby && brew test jruby` *Example:* `brew install jruby && brew test jruby`
@ -908,8 +912,8 @@ Run Homebrew's unit and integration tests.
### `update-test` [*`options`*] ### `update-test` [*`options`*]
Run 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
If no arguments are passed, use `origin/master` as the start commit. passed, use `origin/master` as the start commit.
* `--to-tag`: * `--to-tag`:
Set `HOMEBREW_UPDATE_TO_TAG` to test updating between tags. Set `HOMEBREW_UPDATE_TO_TAG` to test updating between tags.

10
manpages/brew.1
View File

@ -35,8 +35,8 @@ Perform a substring search of cask tokens and formula names for \fItext\fR\. If
. .
.SH "COMMANDS" .SH "COMMANDS"
. .
.SS "\fBanalytics\fR (\fBon\fR|\fBoff\fR) [\fBstate\fR] [\fBregenerate\-uuid\fR]" .SS "\fBanalytics\fR [\fBon\fR|\fBoff\fR|\fBstate\fR|\fBregenerate\-uuid\fR]"
If \fBon\fR|\fBoff\fR is passed, turn Homebrew\'s analytics on or off respectively\. If \fBon\fR or \fBoff\fR is passed, turn Homebrew\'s analytics on or off respectively\.
. .
.P .P
If \fBstate\fR is passed, display anonymous user behaviour analytics state\. Read more at \fIhttps://docs\.brew\.sh/Analytics\fR\. If \fBstate\fR is passed, display anonymous user behaviour analytics state\. Read more at \fIhttps://docs\.brew\.sh/Analytics\fR\.
@ -752,7 +752,7 @@ Show the cache file used when building from source\.
\fB\-\-force\-bottle\fR \fB\-\-force\-bottle\fR
Show the cache file used when pouring a bottle\. Show the cache file used when pouring a bottle\.
. .
.SS "\fB\-\-cache\fR [\fIformula\fR]" .SS "\fB\-\-cellar\fR [\fIformula\fR]"
Display Homebrew\'s Cellar path\. \fIDefault:\fR \fB$(brew \-\-prefix)/Cellar\fR, or if that directory doesn\'t exist, \fB$(brew \-\-repository)/Cellar\fR\. Display Homebrew\'s Cellar path\. \fIDefault:\fR \fB$(brew \-\-prefix)/Cellar\fR, or if that directory doesn\'t exist, \fB$(brew \-\-repository)/Cellar\fR\.
. .
.P .P
@ -849,7 +849,7 @@ Append \fB_or_later\fR to the bottle tag\.
. .
.TP .TP
\fB\-\-force\-core\-tap\fR \fB\-\-force\-core\-tap\fR
Build a bottle even if \fIformula\fR is not in homebrew/core or any installed taps\. Build a bottle even if \fIformula\fR is not in \fBhomebrew/core\fR or any installed taps\.
. .
.TP .TP
\fB\-\-no\-rebuild\fR \fB\-\-no\-rebuild\fR
@ -1035,7 +1035,7 @@ Run Homebrew with the Ruby profiler e\.g\. \fBbrew prof readall\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\. 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 .P
Each \fIpatch\fR may be the number of a PR in homebrew/core, the URL of a PR on GitHub, the URL of a commit on GitHub or a "https://jenkins\.brew\.sh/job/\.\.\." testing job URL\. Each \fIpatch\fR may be the number of a PR in \fBhomebrew/core\fR, the URL of a PR on GitHub, the URL of a commit on GitHub or a "https://jenkins\.brew\.sh/job/\.\.\." testing job URL\.
. .
.TP .TP
\fB\-\-bottle\fR \fB\-\-bottle\fR