Improve external command documentation
Extract `brew bundle` and `brew services` docs from their help. Add a little for `brew cask` until we can think about e.g. merging the manpages.
This commit is contained in:
Mike McQuaid
parent
cb6828dbe6
commit
b23f66982f
@ -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}")
|
||||
|
||||
@ -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"]
|
||||
|
||||
@ -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:
|
||||
<https://github.com/Homebrew/homebrew-bundle>
|
||||
<%= homebrew_bundle.join("\n ").strip %>
|
||||
|
||||
* `cask`:
|
||||
Install macOS applications distributed as binaries:
|
||||
<https://github.com/caskroom/homebrew-cask>
|
||||
|
||||
* `services`:
|
||||
Integrates Homebrew formulae with macOS's `launchctl`(1) manager:
|
||||
<https://github.com/Homebrew/homebrew-services>
|
||||
Homebrew/homebrew-bundle <https://github.com/Homebrew/homebrew-bundle>
|
||||
|
||||
* `cask` [`--version` | `audit` | `cat` | `cleanup` | `create` | `doctor` | `edit` | `fetch` | `home` | `info`]:
|
||||
Install macOS applications distributed as binaries.
|
||||
|
||||
|
||||
Caskroom/homebrew-cask <https://github.com/caskroom/homebrew-cask>
|
||||
|
||||
<%= homebrew_services.join("\n ").strip %>
|
||||
|
||||
|
||||
Homebrew/homebrew-services <https://github.com/Homebrew/homebrew-services>
|
||||
|
||||
## CUSTOM EXTERNAL COMMANDS
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
138
docs/Manpage.md
138
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:
|
||||
<https://github.com/Homebrew/homebrew-bundle>
|
||||
* `bundle` `command`:
|
||||
|
||||
* `cask`:
|
||||
Install macOS applications distributed as binaries:
|
||||
<https://github.com/caskroom/homebrew-cask>
|
||||
Bundler for non-Ruby dependencies from Homebrew.
|
||||
|
||||
* `services`:
|
||||
Integrates Homebrew formulae with macOS's `launchctl`(1) manager:
|
||||
<https://github.com/Homebrew/homebrew-services>
|
||||
|
||||
|
||||
`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 <https://github.com/Homebrew/homebrew-bundle>
|
||||
|
||||
* `cask` [`--version` | `audit` | `cat` | `cleanup` | `create` | `doctor` | `edit` | `fetch` | `home` | `info`]:
|
||||
Install macOS applications distributed as binaries.
|
||||
|
||||
|
||||
Caskroom/homebrew-cask <https://github.com/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 <https://github.com/Homebrew/homebrew-services>
|
||||
|
||||
## CUSTOM EXTERNAL COMMANDS
|
||||
|
||||
|
||||
136
manpages/brew.1
136
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=<path>\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\.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user