Merge pull request #7663 from MikeMcQuaid/external-man

manpage: update external commands.

Library/Homebrew/commands.rb

@@ -101,7 +101,7 @@ def internal_developer_commands_paths
   end
 
   def official_external_commands_paths
-    %w[bundle services].map do |cmd|
+    %w[bundle services test-bot].map do |cmd|
       tap = Tap.fetch("Homebrew/#{cmd}")
       tap.install unless tap.installed?
       external_ruby_v2_cmd_path(cmd)

docs/Manpage.md

@@ -1082,23 +1082,52 @@ Bundler for non-Ruby dependencies from Homebrew, Homebrew Cask, Mac App Store
 and Whalebrew.
 
 `brew bundle` [`install`]:
-    Install or upgrade all dependencies in a `Brewfile`.
+    Install and upgrade (by default) all dependencies from the `Brewfile`.
+
+You can skip the installation of dependencies by adding space-separated values
+to one or more of the following environment variables:
+`HOMEBREW_BUNDLE_BREW_SKIP`, `HOMEBREW_BUNDLE_CASK_SKIP`,
+`HOMEBREW_BUNDLE_MAS_SKIP`, `HOMEBREW_BUNDLE_WHALEBREW_SKIP`,
+`HOMEBREW_BUNDLE_TAP_SKIP`
+
+`brew bundle` will output a `Brewfile.lock.json` in the same directory as the
+`Brewfile` if all dependencies are installed successfully. This contains
+dependency and system status information which can be useful in debugging `brew
+bundle` failures and replicating a "last known good build" state. You can
+opt-out of this behaviour by setting the `HOMEBREW_BUNDLE_NO_LOCK` environment
+variable or passing the `--no-lock` option. You may wish to check this file into
+the same version control system as your `Brewfile` (or ensure your version
+control system ignores it if you'd prefer to rely on debugging information from
+a local machine).
 
 `brew bundle dump`:
     Write all installed casks/formulae/images/taps into a `Brewfile`.
 
 `brew bundle cleanup`:
-    Uninstall all dependencies not listed in a `Brewfile`.
+    Uninstall all dependencies not listed from the `Brewfile`.
+
+This workflow is useful for maintainers or testers who regularly install lots of
+formulae.
 
 `brew bundle check`:
-    Check if all dependencies are installed in a `Brewfile`.
+    Check if all dependencies are installed from the `Brewfile` .
 
-`brew bundle exec` *`command`*:
-    Run an external command in an isolated build environment.
+This provides a successful exit code if everything is up-to-date, making it
+useful for scripting.
 
 `brew bundle list`:
-    List all dependencies present in a `Brewfile`. By default, only Homebrew
-dependencies are listed.
+    List all dependencies present in a `Brewfile`.
+
+By default, only Homebrew dependencies are listed.
+
+`brew bundle exec` *`command`*:
+    Run an external command in an isolated build environment based on the
+`Brewfile` dependencies.
+
+This sanitized build environment ignores unrequested dependencies, which makes
+sure that things you didn't specify in your `Brewfile` won't get picked up by
+commands like `bundle install`, `npm install`, etc. It will also add compiler
+flags which will help find keg-only dependencies like `openssl`, `icu4c`, etc.
 
 * `--file`:
   Read the `Brewfile` from this location. Use `--file=-` to pipe to stdin/stdout.
@@ -1139,7 +1168,7 @@ If `sudo` is passed, operate on `/Library/LaunchDaemons` (started at boot).
 Otherwise, operate on `~/Library/LaunchAgents` (started at login).
 
 [`sudo`] `brew services` [`list`]:
-    List all running services for the current user (or root).
+    List all managed services for the current user (or root).
 
 [`sudo`] `brew services run` (*`formula`*|`--all`):
     Run the service *`formula`* without registering to launch at login (or boot).
@@ -1162,6 +1191,64 @@ it to launch at login (or boot).
 * `--all`:
   Run *`subcommand`* on all services.
 
+### `test-bot` [*`options`*] [*`formula`*]:
+
+Tests the full lifecycle of a Homebrew change to a tap (Git repository). For
+example, for a GitHub Actions pull request that changes a formula `brew
+test-bot` will ensure the system is cleaned and setup to test the formula,
+install the formula, run various tests and checks on it, bottle (package) the
+binaries and test formulae that depend on it to ensure they aren't broken by
+these changes.
+
+Only supports GitHub Actions as a CI provider. This is because Homebrew uses
+GitHub Actions and it's freely available for public and private use with macOS
+and Linux workers.
+
+* `--dry-run`:
+  print what would be done rather than doing it.
+* `--cleanup`:
+  clean all state from the Homebrew directory. Use with care!
+* `--skip-setup`:
+  don't check if the local system is set up correctly.
+* `--keep-old`:
+  run `brew bottle --keep-old` to build new bottles for a single platform.
+* `--skip-relocation`:
+  run `brew bottle --skip-relocation` to build new bottles that don't require relocation.
+* `--local`:
+  ask Homebrew to write verbose logs under `./logs/` and set `$HOME` to `./home/`
+* `--tap`:
+  use the `git` repository of the given tap. Defaults to the core tap for syntax checking.
+* `--fail-fast`:
+  immediately exit on a failing step.
+* `-v`, `--verbose`:
+  print test step output in real time. Has the side effect of passing output as raw bytes instead of re-encoding in UTF-8.
+* `--test-default-formula`:
+  use a default testing formula when not building a tap and no other formulae are specified.
+* `--bintray-org`:
+  upload to the given Bintray organisation.
+* `--root-url`:
+  use the specified *`URL`* as the root of the bottle's URL instead of Homebrew's default.
+* `--git-name`:
+  set the Git author/committer names to the given name.
+* `--git-email`:
+  set the Git author/committer email to the given email.
+* `--ci-upload`:
+  use the Homebrew CI bottle upload options.
+* `--publish`:
+  publish the uploaded bottles.
+* `--skip-recursive-dependents`:
+  only test the direct dependents.
+* `--only-cleanup-before`:
+  Only run the pre-cleanup step. Needs `--cleanup`.
+* `--only-setup`:
+  Only run the local system setup check step.
+* `--only-tap-syntax`:
+  Only run the tap syntax check step.
+* `--only-formulae`:
+  Only run the formulae steps.
+* `--only-cleanup-after`:
+  Only run the post-cleanup step. Needs `--cleanup`.
+
 ## CUSTOM EXTERNAL COMMANDS
 
 Homebrew, like `git`(1), supports external commands. These are executable

manpages/brew.1

@@ -1388,27 +1388,45 @@ Bundler for non\-Ruby dependencies from Homebrew, Homebrew Cask, Mac App Store a
 .
 .P
 \fBbrew bundle\fR [\fBinstall\fR]
-    Install or upgrade all dependencies in a \fBBrewfile\fR\.
+    Install and upgrade (by default) all dependencies from the \fBBrewfile\fR\.
+.
+.P
+You can skip the installation of dependencies by adding space\-separated values to one or more of the following environment variables: \fBHOMEBREW_BUNDLE_BREW_SKIP\fR, \fBHOMEBREW_BUNDLE_CASK_SKIP\fR, \fBHOMEBREW_BUNDLE_MAS_SKIP\fR, \fBHOMEBREW_BUNDLE_WHALEBREW_SKIP\fR, \fBHOMEBREW_BUNDLE_TAP_SKIP\fR
+.
+.P
+\fBbrew bundle\fR will output a \fBBrewfile\.lock\.json\fR in the same directory as the \fBBrewfile\fR if all dependencies are installed successfully\. This contains dependency and system status information which can be useful in debugging \fBbrew bundle\fR failures and replicating a "last known good build" state\. You can opt\-out of this behaviour by setting the \fBHOMEBREW_BUNDLE_NO_LOCK\fR environment variable or passing the \fB\-\-no\-lock\fR option\. You may wish to check this file into the same version control system as your \fBBrewfile\fR (or ensure your version control system ignores it if you\'d prefer to rely on debugging information from a local machine)\.
 .
 .P
 \fBbrew bundle dump\fR
     Write all installed casks/formulae/images/taps into a \fBBrewfile\fR\.
 .
 .P
 \fBbrew bundle cleanup\fR
-    Uninstall all dependencies not listed in a \fBBrewfile\fR\.
+    Uninstall all dependencies not listed from the \fBBrewfile\fR\.
+.
+.P
+This workflow is useful for maintainers or testers who regularly install lots of formulae\.
 .
 .P
 \fBbrew bundle check\fR
-    Check if all dependencies are installed in a \fBBrewfile\fR\.
+    Check if all dependencies are installed from the \fBBrewfile\fR \.
 .
 .P
-\fBbrew bundle exec\fR \fIcommand\fR
-    Run an external command in an isolated build environment\.
+This provides a successful exit code if everything is up\-to\-date, making it useful for scripting\.
 .
 .P
 \fBbrew bundle list\fR
-    List all dependencies present in a \fBBrewfile\fR\. By default, only Homebrew dependencies are listed\.
+    List all dependencies present in a \fBBrewfile\fR\.
+.
+.P
+By default, only Homebrew dependencies are listed\.
+.
+.P
+\fBbrew bundle exec\fR \fIcommand\fR
+    Run an external command in an isolated build environment based on the \fBBrewfile\fR dependencies\.
+.
+.P
+This sanitized build environment ignores unrequested dependencies, which makes sure that things you didn\'t specify in your \fBBrewfile\fR won\'t get picked up by commands like \fBbundle install\fR, \fBnpm install\fR, etc\. It will also add compiler flags which will help find keg\-only dependencies like \fBopenssl\fR, \fBicu4c\fR, etc\.
 .
 .TP
 \fB\-\-file\fR
@@ -1478,7 +1496,7 @@ If \fBsudo\fR is passed, operate on \fB/Library/LaunchDaemons\fR (started at boo
 .
 .P
 [\fBsudo\fR] \fBbrew services\fR [\fBlist\fR]
-    List all running services for the current user (or root)\.
+    List all managed services for the current user (or root)\.
 .
 .P
 [\fBsudo\fR] \fBbrew services run\fR (\fIformula\fR|\fB\-\-all\fR)
@@ -1504,6 +1522,100 @@ If \fBsudo\fR is passed, operate on \fB/Library/LaunchDaemons\fR (started at boo
 \fB\-\-all\fR
 Run \fIsubcommand\fR on all services\.
 .
+.SS "\fBtest\-bot\fR [\fIoptions\fR] [\fIformula\fR]:"
+Tests the full lifecycle of a Homebrew change to a tap (Git repository)\. For example, for a GitHub Actions pull request that changes a formula \fBbrew test\-bot\fR will ensure the system is cleaned and setup to test the formula, install the formula, run various tests and checks on it, bottle (package) the binaries and test formulae that depend on it to ensure they aren\'t broken by these changes\.
+.
+.P
+Only supports GitHub Actions as a CI provider\. This is because Homebrew uses GitHub Actions and it\'s freely available for public and private use with macOS and Linux workers\.
+.
+.TP
+\fB\-\-dry\-run\fR
+print what would be done rather than doing it\.
+.
+.TP
+\fB\-\-cleanup\fR
+clean all state from the Homebrew directory\. Use with care!
+.
+.TP
+\fB\-\-skip\-setup\fR
+don\'t check if the local system is set up correctly\.
+.
+.TP
+\fB\-\-keep\-old\fR
+run \fBbrew bottle \-\-keep\-old\fR to build new bottles for a single platform\.
+.
+.TP
+\fB\-\-skip\-relocation\fR
+run \fBbrew bottle \-\-skip\-relocation\fR to build new bottles that don\'t require relocation\.
+.
+.TP
+\fB\-\-local\fR
+ask Homebrew to write verbose logs under \fB\./logs/\fR and set \fB$HOME\fR to \fB\./home/\fR
+.
+.TP
+\fB\-\-tap\fR
+use the \fBgit\fR repository of the given tap\. Defaults to the core tap for syntax checking\.
+.
+.TP
+\fB\-\-fail\-fast\fR
+immediately exit on a failing step\.
+.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+print test step output in real time\. Has the side effect of passing output as raw bytes instead of re\-encoding in UTF\-8\.
+.
+.TP
+\fB\-\-test\-default\-formula\fR
+use a default testing formula when not building a tap and no other formulae are specified\.
+.
+.TP
+\fB\-\-bintray\-org\fR
+upload to the given Bintray organisation\.
+.
+.TP
+\fB\-\-root\-url\fR
+use the specified \fIURL\fR as the root of the bottle\'s URL instead of Homebrew\'s default\.
+.
+.TP
+\fB\-\-git\-name\fR
+set the Git author/committer names to the given name\.
+.
+.TP
+\fB\-\-git\-email\fR
+set the Git author/committer email to the given email\.
+.
+.TP
+\fB\-\-ci\-upload\fR
+use the Homebrew CI bottle upload options\.
+.
+.TP
+\fB\-\-publish\fR
+publish the uploaded bottles\.
+.
+.TP
+\fB\-\-skip\-recursive\-dependents\fR
+only test the direct dependents\.
+.
+.TP
+\fB\-\-only\-cleanup\-before\fR
+Only run the pre\-cleanup step\. Needs \fB\-\-cleanup\fR\.
+.
+.TP
+\fB\-\-only\-setup\fR
+Only run the local system setup check step\.
+.
+.TP
+\fB\-\-only\-tap\-syntax\fR
+Only run the tap syntax check step\.
+.
+.TP
+\fB\-\-only\-formulae\fR
+Only run the formulae steps\.
+.
+.TP
+\fB\-\-only\-cleanup\-after\fR
+Only run the post\-cleanup step\. Needs \fB\-\-cleanup\fR\.
+.
 .SH "CUSTOM EXTERNAL COMMANDS"
 Homebrew, like \fBgit\fR(1), supports external commands\. These are executable scripts that reside somewhere in the \fBPATH\fR, named \fBbrew\-\fR\fIcmdname\fR or \fBbrew\-\fR\fIcmdname\fR\fB\.rb\fR, which can be invoked like \fBbrew\fR \fIcmdname\fR\. This allows you to create your own commands without modifying Homebrew\'s internals\.
 .