From f63d2d78877bdab76e3b8c425dbbd1586b23ea9e Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Wed, 11 Mar 2020 12:16:47 +0000 Subject: [PATCH 1/3] man: be more exact about global options. Make clear these don't necessarily apply to all subcommands (see https://github.com/Homebrew/brew/issues/7121). --- Library/Homebrew/dev-cmd/man.rb | 2 +- docs/Manpage.md | 2 +- manpages/brew.1 | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb index 8560f58f21..2af8e96564 100644 --- a/Library/Homebrew/dev-cmd/man.rb +++ b/Library/Homebrew/dev-cmd/man.rb @@ -198,7 +198,7 @@ module Homebrew end def global_options_manpage - lines = ["These options are applicable across all sub-commands.\n"] + lines = ["These options are applicable across multiple subcommands.\n"] lines += Homebrew::CLI::Parser.global_options.values.map do |names, _, desc| short, long = names generate_option_doc(short, long, desc) diff --git a/docs/Manpage.md b/docs/Manpage.md index 6553ccf42c..235f366f33 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -991,7 +991,7 @@ Install and commit Homebrew's vendored gems. ## GLOBAL OPTIONS -These options are applicable across all sub-commands. +These options are applicable across multiple subcommands. * `-q`, `--quiet`: Suppress any warnings. diff --git a/manpages/brew.1 b/manpages/brew.1 index e3d8cbf9b8..a2d79f4cf5 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -1262,7 +1262,7 @@ Use the commit at the specified \fIdate\fR as the start commit\. Install and commit Homebrew\'s vendored gems\. . .SH "GLOBAL OPTIONS" -These options are applicable across all sub\-commands\. +These options are applicable across multiple subcommands\. . .TP \fB\-q\fR, \fB\-\-quiet\fR From 7a086911003eeb99b1f6bb2a493fb9aada18e58c Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Wed, 11 Mar 2020 12:17:25 +0000 Subject: [PATCH 2/3] commands: helper for official external commands. --- Library/Homebrew/commands.rb | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Library/Homebrew/commands.rb b/Library/Homebrew/commands.rb index a24859faf6..fae9376cb4 100644 --- a/Library/Homebrew/commands.rb +++ b/Library/Homebrew/commands.rb @@ -100,6 +100,14 @@ module Commands find_commands HOMEBREW_DEV_CMD_PATH end + def official_external_commands_paths + %w[bundle services].map do |cmd| + tap = Tap.fetch("Homebrew/#{cmd}") + tap.install unless tap.installed? + external_ruby_v2_cmd_path(cmd) + end + end + def internal_commands find_internal_commands(HOMEBREW_CMD_PATH).map(&:to_s) end From 2afeffc91ba335483146a4a17feaa3bbce5ae791 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Wed, 11 Mar 2020 12:22:46 +0000 Subject: [PATCH 3/3] man: include full help from external commands. Inspired by https://github.com/Homebrew/brew/issues/7148 --- Library/Homebrew/dev-cmd/man.rb | 1 + Library/Homebrew/manpages/brew.1.md.erb | 14 +-- docs/Manpage.md | 96 +++++++++++++++-- manpages/brew.1 | 131 ++++++++++++++++++++++-- 4 files changed, 208 insertions(+), 34 deletions(-) diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb index 2af8e96564..6747996bd9 100644 --- a/Library/Homebrew/dev-cmd/man.rb +++ b/Library/Homebrew/dev-cmd/man.rb @@ -61,6 +61,7 @@ module Homebrew variables[:commands] = generate_cmd_manpages(Commands.internal_commands_paths) variables[:developer_commands] = generate_cmd_manpages(Commands.internal_developer_commands_paths) + variables[:official_external_commands] = generate_cmd_manpages(Commands.official_external_commands_paths) variables[:global_options] = global_options_manpage readme = HOMEBREW_REPOSITORY/"README.md" diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb index 2feb5b6f0f..7dcf471164 100644 --- a/Library/Homebrew/manpages/brew.1.md.erb +++ b/Library/Homebrew/manpages/brew.1.md.erb @@ -65,25 +65,13 @@ If no search term is provided, all locally available formulae are listed. ## OFFICIAL EXTERNAL COMMANDS -### `bundle` : - -Bundler for non-Ruby dependencies from Homebrew, Homebrew Cask and the Mac App Store. -See `brew bundle --help`. - -**Homebrew/homebrew-bundle**: - ### `cask` : Install macOS applications distributed as binaries. See `brew-cask`(1). **Homebrew/homebrew-cask**: -### `services` : - -Manage background services with macOS' `launchctl`(1) daemon manager. -See `brew services --help`. - -**Homebrew/homebrew-services**: +<%= official_external_commands %> ## CUSTOM EXTERNAL COMMANDS diff --git a/docs/Manpage.md b/docs/Manpage.md index 235f366f33..44dd2750cb 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -1007,25 +1007,101 @@ These options are applicable across multiple subcommands. ## OFFICIAL EXTERNAL COMMANDS -### `bundle` *`subcommand`*: - -Bundler for non-Ruby dependencies from Homebrew, Homebrew Cask and the Mac App Store. -See `brew bundle --help`. - -**Homebrew/homebrew-bundle**: - ### `cask` *`subcommand`*: Install macOS applications distributed as binaries. See `brew-cask`(1). **Homebrew/homebrew-cask**: -### `services` *`subcommand`*: +### `bundle` *`subcommand`* + +Bundler for non-Ruby dependencies from Homebrew, Homebrew Cask and the Mac App +Store. + +`brew bundle` [`install`] + +Install or upgrade all dependencies in a `Brewfile`. + +`brew bundle dump` + +Write all installed casks/formulae/taps into a `Brewfile`. + +`brew bundle cleanup` + +Uninstall all dependencies not listed in a `Brewfile`. + +`brew bundle check` + +Check if all dependencies are installed in a `Brewfile`. + +`brew bundle exec` *`command`* + +Run an external command in an isolated build environment. + +`brew bundle list` + +List all dependencies present in a Brewfile. By default, only Homebrew +dependencies are listed. + +* `--file`: + Read the `Brewfile` from this file. Use `--file=-` to pipe to stdin/stdout. +* `--global`: + Read the `Brewfile` from `~/.Brewfile`. +* `-v`, `--verbose`: + `install` output is printed from commands as they are run. `check` prints all missing dependencies. +* `--no-upgrade`: + `install` won't run `brew upgrade` on outdated dependencies. Note they may still be upgraded by `brew install` if needed. +* `-f`, `--force`: + `dump` overwrites an existing `Brewfile`. `cleanup` actually perform the cleanup operations. +* `--no-lock`: + `install` won't output a `Brewfile.lock.json`. +* `--all`: + `list` all dependencies. +* `--brews`: + `list` Homebrew dependencies. +* `--casks`: + `list` Homebrew Cask dependencies. +* `--taps`: + `list` tap dependencies. +* `--mas`: + `list` Mac App Store dependencies. +* `--describe`: + `dump` a description comment above each line, unless the dependency does not have a description. +* `--no-restart`: + `dump` does not add `restart_service` to formula lines. +* `--zap`: + `cleanup` casks using the `zap` command instead of `uninstall`. + +### `services` *`subcommand`* Manage background services with macOS' `launchctl`(1) daemon manager. -See `brew services --help`. -**Homebrew/homebrew-services**: +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). + +[`sudo`] `brew services run` (*`formula`*|`--all`) + Run the service *`formula`* without registering to launch at login (or boot). + +[`sudo`] `brew services start` (*`formula`*|`--all`) + Start the service *`formula`* immediately and register it to launch at login (or +boot). + +[`sudo`] `brew services stop` (*`formula`*|`--all`) + Stop the service *`formula`* immediately and unregister it from launching at +login (or boot). + +[`sudo`] `brew services restart` (*`formula`*|`--all`) + Stop (if necessary) and start the service *`formula`* immediately and register +it to launch at login (or boot). + +[`sudo`] `brew services cleanup` + Remove all unused services. + +* `--all`: + Run *`subcommand`* on all services. ## CUSTOM EXTERNAL COMMANDS diff --git a/manpages/brew.1 b/manpages/brew.1 index a2d79f4cf5..d5f724b0f3 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -1282,13 +1282,6 @@ Override warnings and enable potentially unsafe operations\. . .SH "OFFICIAL EXTERNAL COMMANDS" . -.SS "\fBbundle\fR \fIsubcommand\fR:" -Bundler for non\-Ruby dependencies from Homebrew, Homebrew Cask and the Mac App Store\. See \fBbrew bundle \-\-help\fR\. -. -.P -\fBHomebrew/homebrew\-bundle\fR - \fIhttps://github\.com/Homebrew/homebrew\-bundle\fR -. .SS "\fBcask\fR \fIsubcommand\fR:" Install macOS applications distributed as binaries\. See \fBbrew\-cask\fR(1)\. . @@ -1296,12 +1289,128 @@ Install macOS applications distributed as binaries\. See \fBbrew\-cask\fR(1)\. \fBHomebrew/homebrew\-cask\fR \fIhttps://github\.com/Homebrew/homebrew\-cask\fR . -.SS "\fBservices\fR \fIsubcommand\fR:" -Manage background services with macOS\' \fBlaunchctl\fR(1) daemon manager\. See \fBbrew services \-\-help\fR\. +.SS "\fBbundle\fR \fIsubcommand\fR" +Bundler for non\-Ruby dependencies from Homebrew, Homebrew Cask and the Mac App Store\. . .P -\fBHomebrew/homebrew\-services\fR - \fIhttps://github\.com/Homebrew/homebrew\-services\fR +\fBbrew bundle\fR [\fBinstall\fR] +. +.P +Install or upgrade all dependencies in a \fBBrewfile\fR\. +. +.P +\fBbrew bundle dump\fR +. +.P +Write all installed casks/formulae/taps into a \fBBrewfile\fR\. +. +.P +\fBbrew bundle cleanup\fR +. +.P +Uninstall all dependencies not listed in a \fBBrewfile\fR\. +. +.P +\fBbrew bundle check\fR +. +.P +Check if all dependencies are installed in a \fBBrewfile\fR\. +. +.P +\fBbrew bundle exec\fR \fIcommand\fR +. +.P +Run an external command in an isolated build environment\. +. +.P +\fBbrew bundle list\fR +. +.P +List all dependencies present in a Brewfile\. By default, only Homebrew dependencies are listed\. +. +.TP +\fB\-\-file\fR +Read the \fBBrewfile\fR from this file\. Use \fB\-\-file=\-\fR to pipe to stdin/stdout\. +. +.TP +\fB\-\-global\fR +Read the \fBBrewfile\fR from \fB~/\.Brewfile\fR\. +. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +\fBinstall\fR output is printed from commands as they are run\. \fBcheck\fR prints all missing dependencies\. +. +.TP +\fB\-\-no\-upgrade\fR +\fBinstall\fR won\'t run \fBbrew upgrade\fR on outdated dependencies\. Note they may still be upgraded by \fBbrew install\fR if needed\. +. +.TP +\fB\-f\fR, \fB\-\-force\fR +\fBdump\fR overwrites an existing \fBBrewfile\fR\. \fBcleanup\fR actually perform the cleanup operations\. +. +.TP +\fB\-\-no\-lock\fR +\fBinstall\fR won\'t output a \fBBrewfile\.lock\.json\fR\. +. +.TP +\fB\-\-all\fR +\fBlist\fR all dependencies\. +. +.TP +\fB\-\-brews\fR +\fBlist\fR Homebrew dependencies\. +. +.TP +\fB\-\-casks\fR +\fBlist\fR Homebrew Cask dependencies\. +. +.TP +\fB\-\-taps\fR +\fBlist\fR tap dependencies\. +. +.TP +\fB\-\-mas\fR +\fBlist\fR Mac App Store dependencies\. +. +.TP +\fB\-\-describe\fR +\fBdump\fR a description comment above each line, unless the dependency does not have a description\. +. +.TP +\fB\-\-no\-restart\fR +\fBdump\fR does not add \fBrestart_service\fR to formula lines\. +. +.TP +\fB\-\-zap\fR +\fBcleanup\fR casks using the \fBzap\fR command instead of \fBuninstall\fR\. +. +.SS "\fBservices\fR \fIsubcommand\fR" +Manage background services with macOS\' \fBlaunchctl\fR(1) daemon manager\. +. +.P +If \fBsudo\fR is passed, operate on \fB/Library/LaunchDaemons\fR (started at boot)\. Otherwise, operate on \fB~/Library/LaunchAgents\fR (started at login)\. +. +.P +[\fBsudo\fR] \fBbrew services\fR [\fBlist\fR] List all running services for the current user (or root)\. +. +.P +[\fBsudo\fR] \fBbrew services run\fR (\fIformula\fR|\fB\-\-all\fR) Run the service \fIformula\fR without registering to launch at login (or boot)\. +. +.P +[\fBsudo\fR] \fBbrew services start\fR (\fIformula\fR|\fB\-\-all\fR) Start the service \fIformula\fR immediately and register it to launch at login (or boot)\. +. +.P +[\fBsudo\fR] \fBbrew services stop\fR (\fIformula\fR|\fB\-\-all\fR) Stop the service \fIformula\fR immediately and unregister it from launching at login (or boot)\. +. +.P +[\fBsudo\fR] \fBbrew services restart\fR (\fIformula\fR|\fB\-\-all\fR) Stop (if necessary) and start the service \fIformula\fR immediately and register it to launch at login (or boot)\. +. +.P +[\fBsudo\fR] \fBbrew services cleanup\fR Remove all unused services\. +. +.TP +\fB\-\-all\fR +Run \fIsubcommand\fR on all services\. . .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\.