diff --git a/Library/Homebrew/cmd/help.rb b/Library/Homebrew/cmd/help.rb index c85b92124a..2b1e7c5049 100644 --- a/Library/Homebrew/cmd/help.rb +++ b/Library/Homebrew/cmd/help.rb @@ -74,14 +74,13 @@ module Homebrew end def command_help(path) - help_lines = path.read.lines.grep(/^#:/) + help_lines = command_help_lines(path) if help_lines.empty? opoo "No help text in: #{path}" if ARGV.homebrew_developer? HOMEBREW_HELP else help_lines.map do |line| - line.slice(2..-1) - .sub(/^ \* /, "#{Tty.bold}brew#{Tty.reset} ") + line.sub(/^ \* /, "#{Tty.bold}brew#{Tty.reset} ") .gsub(/`(.*?)`/, "#{Tty.bold}\\1#{Tty.reset}") .gsub(%r{<([^\s]+?://[^\s]+?)>}) { |url| Formatter.url(url) } .gsub(/<(.*?)>/, "#{Tty.underline}\\1#{Tty.reset}") diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb index f06c89863d..109037d8eb 100644 --- a/Library/Homebrew/dev-cmd/man.rb +++ b/Library/Homebrew/dev-cmd/man.rb @@ -71,6 +71,9 @@ module Homebrew variables[:former_maintainers] = readme.read[/(Former maintainers .*\.)/, 1] .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1') + variables[:homebrew_bundle] = help_output(:bundle) + variables[:homebrew_services] = help_output(:services) + ERB.new(template, nil, ">").result(variables.instance_eval { binding }) end @@ -113,6 +116,12 @@ module Homebrew end end + def help_output(command) + tap = Tap.fetch("Homebrew/homebrew-#{command}") + tap.install unless tap.installed? + command_help_lines(which("brew-#{command}.rb", Tap.cmd_directories)) + end + def target_path_to_format(target) case target.basename when /\.md$/ then ["--markdown", "markdown"] diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb index e3d3faf09e..a4854cc67c 100644 --- a/Library/Homebrew/manpages/brew.1.md.erb +++ b/Library/Homebrew/manpages/brew.1.md.erb @@ -56,17 +56,21 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note ## OFFICIAL EXTERNAL COMMANDS - * `bundle`: - Bundler for non-Ruby dependencies from Homebrew: - + <%= homebrew_bundle.join("\n ").strip %> - * `cask`: - Install macOS applications distributed as binaries: - - * `services`: - Integrates Homebrew formulae with macOS's `launchctl`(1) manager: - + Homebrew/homebrew-bundle + + * `cask` [`--version` | `audit` | `cat` | `cleanup` | `create` | `doctor` | `edit` | `fetch` | `home` | `info`]: + Install macOS applications distributed as binaries. + + + Caskroom/homebrew-cask + + <%= homebrew_services.join("\n ").strip %> + + + Homebrew/homebrew-services ## CUSTOM EXTERNAL COMMANDS diff --git a/Library/Homebrew/utils.rb b/Library/Homebrew/utils.rb index 8d57c12d60..5821535f40 100644 --- a/Library/Homebrew/utils.rb +++ b/Library/Homebrew/utils.rb @@ -572,3 +572,7 @@ def tap_and_name_comparison end end end + +def command_help_lines(path) + path.read.lines.grep(/^#:/).map { |line| line.slice(2..-1) } +end diff --git a/docs/Manpage.md b/docs/Manpage.md index 4c523c435c..ba09bbfb4c 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -907,17 +907,137 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note ## OFFICIAL EXTERNAL COMMANDS - * `bundle`: - Bundler for non-Ruby dependencies from Homebrew: - + * `bundle` `command`: - * `cask`: - Install macOS applications distributed as binaries: - + Bundler for non-Ruby dependencies from Homebrew. - * `services`: - Integrates Homebrew formulae with macOS's `launchctl`(1) manager: - + + + `bundle` [`install`] [`-v`|`--verbose`] [`--no-upgrade`] [`--file=``path`|`--global`]: + + Install or upgrade all dependencies in a Brewfile. + + + + `brew bundle dump` [`--force`] [`--describe`] [`--file=``path`|`--global`] + + Write all installed casks/formulae/taps into a Brewfile. + + + + `brew bundle cleanup` [`--force`] [`--zap`] [`--file=``path`|`--global`] + + Uninstall all dependencies not listed in a Brewfile. + + + + `brew bundle check` [`--no-upgrade`] [`--file`=`path`|`--global`] + + 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` [`--all`|`--brews`|`--casks`|`--taps`|`--mas`] [`--file=``path`|`--global`] + + List all dependencies present in a Brewfile, optionally limiting by types. + + By default, only brew dependencies are output. + + + + If `-v` or `--verbose` are passed, print verbose output. + + + + If `--no-upgrade` is passed, don't run `brew upgrade` outdated dependencies. + + Note they may still be upgraded by `brew install` if needed. + + + + If `--force` is passed, uninstall dependencies or overwrite an existing Brewfile. + + + + If `--file=`path is passed, the Brewfile path is set accordingly + + Use `--file=-` to output to console. + + + + If `--global` is passed, set Brewfile path to `$HOME/.Brewfile`. + + + + If `--describe` is passed, output a description comment above each line. + + This comment will not be output if the dependency does not have a description. + + + + If `-h` or `--help` are passed, print this help message and exit. + + Homebrew/homebrew-bundle + + * `cask` [`--version` | `audit` | `cat` | `cleanup` | `create` | `doctor` | `edit` | `fetch` | `home` | `info`]: + Install macOS applications distributed as binaries. + + + Caskroom/homebrew-cask + + * `services` `command`: + + Integrates Homebrew formulae with macOS' `launchctl` manager. + + + + [`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 starting 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 immediately and register it to launch at login (or `boot`). + + + + [`sudo`] `brew services` `cleanup` + + Remove all unused services. + + + + If `sudo` is passed, operate on `/Library/LaunchDaemons` (started at boot). + + Otherwise, operate on `~/Library/LaunchAgents (started at login)`. + + Homebrew/homebrew-services ## CUSTOM EXTERNAL COMMANDS diff --git a/manpages/brew.1 b/manpages/brew.1 index 536049a33b..b891cd6436 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -930,16 +930,140 @@ If \fB\-\-keep\-tmp\fR is passed, retain the temporary directory containing the .SH "OFFICIAL EXTERNAL COMMANDS" . .TP -\fBbundle\fR -Bundler for non\-Ruby dependencies from Homebrew: \fIhttps://github\.com/Homebrew/homebrew\-bundle\fR +\fBbundle\fR \fIcommand\fR: +. +.IP +Bundler for non\-Ruby dependencies from Homebrew\. +. +.IP +\fBbundle\fR [\fBinstall\fR] [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-\-no\-upgrade\fR] [\fB\-\-file=\fR\fIpath\fR|\fB\-\-global\fR]: +. +.IP +Install or upgrade all dependencies in a Brewfile\. +. +.IP +\fBbrew bundle dump\fR [\fB\-\-force\fR] [\fB\-\-describe\fR] [\fB\-\-file=\fR\fIpath\fR|\fB\-\-global\fR] +. +.IP +Write all installed casks/formulae/taps into a Brewfile\. +. +.IP +\fBbrew bundle cleanup\fR [\fB\-\-force\fR] [\fB\-\-zap\fR] [\fB\-\-file=\fR\fIpath\fR|\fB\-\-global\fR] +. +.IP +Uninstall all dependencies not listed in a Brewfile\. +. +.IP +\fBbrew bundle check\fR [\fB\-\-no\-upgrade\fR] [\fB\-\-file\fR=\fIpath\fR|\fB\-\-global\fR] +. +.IP +Check if all dependencies are installed in a Brewfile\. +. +.IP +\fBbrew bundle exec\fR \fIcommand\fR +. +.IP +Run an external command in an isolated build environment\. +. +.IP +\fBbrew bundle list\fR [\fB\-\-all\fR|\fB\-\-brews\fR|\fB\-\-casks\fR|\fB\-\-taps\fR|\fB\-\-mas\fR] [\fB\-\-file=\fR\fIpath\fR|\fB\-\-global\fR] +. +.IP +List all dependencies present in a Brewfile, optionally limiting by types\. +. +.IP +By default, only brew dependencies are output\. +. +.IP +If \fB\-v\fR or \fB\-\-verbose\fR are passed, print verbose output\. +. +.IP +If \fB\-\-no\-upgrade\fR is passed, don\'t run \fBbrew upgrade\fR outdated dependencies\. +. +.IP +Note they may still be upgraded by \fBbrew install\fR if needed\. +. +.IP +If \fB\-\-force\fR is passed, uninstall dependencies or overwrite an existing Brewfile\. +. +.IP +If \fB\-\-file=\fR is passed, the Brewfile path is set accordingly +. +.IP +Use \fB\-\-file=\-\fR to output to console\. +. +.IP +If \fB\-\-global\fR is passed, set Brewfile path to \fB$HOME/\.Brewfile\fR\. +. +.IP +If \fB\-\-describe\fR is passed, output a description comment above each line\. +. +.IP +This comment will not be output if the dependency does not have a description\. +. +.IP +If \fB\-h\fR or \fB\-\-help\fR are passed, print this help message and exit\. +. +.P +Homebrew/homebrew\-bundle \fIhttps://github\.com/Homebrew/homebrew\-bundle\fR . .TP -\fBcask\fR -Install macOS applications distributed as binaries: \fIhttps://github\.com/caskroom/homebrew\-cask\fR +\fBcask\fR [\fB\-\-version\fR | \fBaudit\fR | \fBcat\fR | \fBcleanup\fR | \fBcreate\fR | \fBdoctor\fR | \fBedit\fR | \fBfetch\fR | \fBhome\fR | \fBinfo\fR] +Install macOS applications distributed as binaries\. +. +.P +Caskroom/homebrew\-cask \fIhttps://github\.com/caskroom/homebrew\-cask\fR . .TP -\fBservices\fR -Integrates Homebrew formulae with macOS\'s \fBlaunchctl\fR(1) manager: \fIhttps://github\.com/Homebrew/homebrew\-services\fR +\fBservices\fR \fIcommand\fR: +. +.IP +Integrates Homebrew formulae with macOS\' \fBlaunchctl\fR manager\. +. +.IP +[\fIsudo\fR] \fBbrew services list\fR +. +.IP +List all running services for the current user (or \fIroot\fR) +. +.IP +[\fIsudo\fR] \fBbrew services run\fR \fIformula|\-\-all\fR +. +.IP +Run the service \fIformula\fR without starting at login (or boot)\. +. +.IP +[\fIsudo\fR] \fBbrew services\fR \fBstart\fR \fIformula|\-\-all\fR +. +.IP +Start the service \fIformula\fR immediately and register it to launch at login (or \fIboot\fR)\. +. +.IP +[\fIsudo\fR] \fBbrew services\fR \fBstop\fR \fIformula|\-\-all\fR +. +.IP +Stop the service \fIformula\fR immediately and unregister it from launching at login (or \fIboot\fR)\. +. +.IP +[\fIsudo\fR] \fBbrew services\fR \fBrestart\fR \fIformula|\-\-all\fR +. +.IP +Stop (if necessary) and start the service immediately and register it to launch at login (or \fIboot\fR)\. +. +.IP +[\fIsudo\fR] \fBbrew services\fR \fBcleanup\fR +. +.IP +Remove all unused services\. +. +.IP +If \fBsudo\fR is passed, operate on \fB/Library/LaunchDaemons\fR (started at boot)\. +. +.IP +Otherwise, operate on \fB~/Library/LaunchAgents (started at login)\fR\. +. +.P +Homebrew/homebrew\-services \fIhttps://github\.com/Homebrew/homebrew\-services\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\.