From 5230ed2117a4520a1c90c90cb3e01bcba7f74c65 Mon Sep 17 00:00:00 2001 From: Andrew Janke Date: Fri, 9 Oct 2015 02:44:10 -0400 Subject: man page: finer-grained markup Closes Homebrew/homebrew#44769 Closes Homebrew/homebrew#46676. Signed-off-by: Andrew Janke --- Library/Homebrew/manpages/brew.1.md | 171 ++++++++++++++++++------------------ 1 file changed, 85 insertions(+), 86 deletions(-) (limited to 'Library') diff --git a/Library/Homebrew/manpages/brew.1.md b/Library/Homebrew/manpages/brew.1.md index b53dc9b75..b7afcd254 100644 --- a/Library/Homebrew/manpages/brew.1.md +++ b/Library/Homebrew/manpages/brew.1.md @@ -3,8 +3,8 @@ brew(1) -- The missing package manager for OS X ## SYNOPSIS -`brew` --version
-`brew` command [--verbose|-v] [options] [formula] ... +`brew` `--version`
+`brew` [`--verbose`|`-v`] [] [] ... ## DESCRIPTION @@ -13,10 +13,9 @@ didn't include with OS X. ## ESSENTIAL COMMANDS -For the full command list, see the COMMANDS section. +For the full command list, see the [COMMANDS][] section. -With `--verbose` or `-v`, many commands print extra debugging information. -Note that these flags should only appear after a command. +With `--verbose` or `-v`, many commands print extra debugging information. Note that these flags should only appear after a command. * `install` : Install . @@ -30,7 +29,7 @@ Note that these flags should only appear after a command. * `list`: List all installed formulae. - * `search` |//: + * `search` | `/``/`: Perform a substring search of formula names for . If is surrounded with slashes, then it is interpreted as a regular expression. The search for is extended online to some popular taps. @@ -38,7 +37,7 @@ Note that these flags should only appear after a command. ## COMMANDS - * `audit` [--strict] [--online] []: + * `audit` [`--strict`] [`--online`] []: Check for Homebrew coding style violations. This should be run before submitting a new formula. @@ -56,26 +55,26 @@ Note that these flags should only appear after a command. * `cat` : Display the source to . - * `cleanup [--force] [--prune=] [-ns]` []: + * `cleanup` [`--force`] [`--prune=`] [`-n`] [`-s`] []: For all installed or specific formulae, remove any older versions from the cellar. By default, does not remove out-of-date keg-only brews, as other - software may link directly to specific versions. In addition old downloads from + software may link directly to specific versions. In addition, old downloads from the Homebrew download-cache are deleted. If `--force` is passed, remove out-of-date keg-only brews as well. - If `--prune=` is specified, remove all cache files older than . + If `--prune=` is specified, remove all cache files older than . If `-n` is passed, show what would be removed, but do not actually remove anything. If `-s` is passed, scrubs the cache, removing downloads for even the latest - versions of formula. Note downloads for any installed formula will still not be + versions of formulae. Note downloads for any installed formulae will still not be deleted. If you want to delete those too: `rm -rf $(brew --cache)` * `command` : - Display the path to the file which is used when invoking `brew `. + Display the path to the file which is used when invoking `brew` . - * `commands [--quiet [--include-aliases]]`: + * `commands` [`--quiet` [`--include-aliases`]]: Show a list of built-in and external commands. If `--quiet` is passed, list only the names of commands without the header. @@ -86,10 +85,10 @@ Note that these flags should only appear after a command. a bug report, you will likely be asked for this information if you do not provide it. - * `create [--autotools|--cmake] [--no-fetch] [--set-name ] [--set-version ]`: + * `create` [`--autotools`|`--cmake`] [`--no-fetch`] [`--set-name` ] [`--set-version` ]: Generate a formula for the downloadable file at and open it in the editor. Homebrew will attempt to automatically derive the formula name - and version, but if it fails, you'll have to make your own template. The wget + and version, but if it fails, you'll have to make your own template. The `wget` formula serves as a simple example. For the complete API have a look at @@ -103,7 +102,7 @@ Note that these flags should only appear after a command. The options `--set-name` and `--set-version` each take an argument and allow you to explicitly set the name and version of the package you are creating. - * `deps [--1] [-n] [--union] [--tree] [--all] [--installed] [--skip-build] [--skip-optional]` : + * `deps` [`--1`] [`-n`] [`--union`] [`--tree`] [`--all`] [`--installed`] [`--skip-build`] [`--skip-optional`] : Show dependencies for . When given multiple formula arguments, show the intersection of dependencies for , except when passed `--tree`, `--all`, or `--installed`. @@ -129,20 +128,20 @@ Note that these flags should only appear after a command. * `desc` : Display 's name and one-line description. - * `desc [-s|-n|-d] `: + * `desc` [`-s`|`-n`|`-d`] : Search both name and description (`-s`), just the names (`-n`), or just the descriptions (`-d`) for ``. `` is by default interpreted as a literal string; if flanked by slashes, it is instead interpreted as a regular expression. Formula descriptions are cached; the cache is created on the first search, making that search slower than subsequent ones. - * `diy [--name=] [--version=]`: + * `diy` [`--name=`] [`--version=`]: Automatically determine the installation prefix for non-Homebrew software. Using the output from this command, you can install your own software into the Cellar and then link it into Homebrew's prefix with `brew link`. - The options `--name=` and `--version=` each take an argument + The options `--name=` and `--version=` each take an argument and allow you to explicitly set the name and version of the package you are installing. @@ -156,9 +155,9 @@ Note that these flags should only appear after a command. * `edit` : Open in the editor. - * `fetch [--force] [-v] [--devel|--HEAD] [--deps] [--build-from-source|--force-bottle]` : + * `fetch` [`--force`] [`-v`] [`--devel`|`--HEAD`] [`--deps`] [`--build-from-source`|`--force-bottle`] : Download the source packages for the given . - For tarballs, also print SHA1 and SHA-256 checksums. + For tarballs, also print SHA-1 and SHA-256 checksums. If `--HEAD` or `--devel` is passed, fetch that version instead of the stable version. @@ -185,12 +184,12 @@ Note that these flags should only appear after a command. * `info` : Display information about . - * `info --github` : + * `info` `--github` : Open a browser to the GitHub History page for formula . To view formula history locally: `brew log -p `. - * `info --json=` (--all|--installed|): + * `info --json=`` (`--all`|`--installed`|): Print a JSON representation of . Currently the only accepted value for is `v1`. @@ -200,7 +199,7 @@ Note that these flags should only appear after a command. See the docs for examples of using the JSON: - * `install [--debug] [--env=] [--ignore-dependencies] [--only-dependencies] [--cc=] [--build-from-source|--force-bottle] [--devel|--HEAD]` : + * `install` [`--debug`] [`--env=`|] [`--ignore-dependencies`] [`--only-dependencies`] [`--cc=`] [`--build-from-source`|`--force-bottle`] [`--devel`|`--HEAD`] : Install . is usually the name of the formula to install, but it can be specified @@ -221,7 +220,7 @@ Note that these flags should only appear after a command. If `--only-dependencies` is passed, install the dependencies with specified options but do not install the specified formula. - If `--cc=` is passed, attempt to compile using . + If `--cc=` is passed, attempt to compile using . should be the name of the compiler's executable, for instance `gcc-4.2` for Apple's GCC 4.2, or `gcc-4.9` for a Homebrew-provided GCC 4.9. @@ -240,7 +239,7 @@ Note that these flags should only appear after a command. To install a newer version of HEAD use `brew rm && brew install --HEAD `. - * `install --interactive [--git]` : + * `install --interactive` [`--git`] : Download and patch , then open a shell. This allows the user to run `./configure --help` and otherwise determine how to turn the software package into a Homebrew formula. @@ -248,7 +247,7 @@ Note that these flags should only appear after a command. If `--git` is passed, Homebrew will create a Git repository, useful for creating patches to the software. - * `irb [--examples]`: + * `irb` [`--examples`]: Enter the interactive Homebrew Ruby shell. If `--examples` is passed, several examples will be shown. @@ -256,7 +255,7 @@ Note that these flags should only appear after a command. * `leaves`: Show installed formulae that are not dependencies of another installed formula. - * `ln`, `link [--overwrite] [--dry-run] [--force]` : + * `ln`, `link` [`--overwrite`] [`--dry-run`] [`--force`] : Symlink all of 's installed files into the Homebrew prefix. This is done automatically when you install formulae but can be useful for DIY installations. @@ -270,7 +269,7 @@ Note that these flags should only appear after a command. If `--force` is passed, Homebrew will allow keg-only formulae to be linked. - * `linkapps [--local]` []: + * `linkapps` [`--local`] []: Find installed formulae that have compiled `.app`-style "application" packages for OS X, and symlink those apps into `/Applications`, allowing for easier access. @@ -280,14 +279,14 @@ Note that these flags should only appear after a command. If provided, `--local` will move them into the user's `~/Applications` directory instead of the system directory. It may need to be created, first. - * `ls`, `list [--full-name]` + * `ls`, `list` [`--full-name`] List all installed formulae. If `--full-name` is passed, print formulae with full-qualified names. * `ls`, `list --unbrewed` List all files in the Homebrew prefix not installed by Homebrew. - * `ls`, `list [--versions [--multiple]] [--pinned]` []: + * `ls`, `list` [`--versions` [`--multiple`]] [`--pinned`] []: List the installed files for . Combined with `--verbose`, recursively list the contents of all subdirectories in each 's keg. @@ -299,7 +298,7 @@ Note that these flags should only appear after a command. specified (pinned) formulae if are given. See also `pin`, `unpin`. - * `log [git-log-options]` ...: + * `log` [`git-log-options`] ...: Show the git log for the given formulae. Options that `git-log`(1) recognizes can be passed before the formula list. @@ -308,14 +307,14 @@ Note that these flags should only appear after a command. If no are given, check all installed brews. - * `migrate [--force]` : + * `migrate` [`--force`] : Migrate renamed packages to new name, where are old names of packages. If `--force` is passed, then treat installed and passed like if they are from same taps and migrate them anyway. - * `options [--compact] [--all] [--installed]` : + * `options` [`--compact`] [`--all`] [`--installed`] : Display install options specific to . If `--compact` is passed, show all options on a single line separated by @@ -325,7 +324,7 @@ Note that these flags should only appear after a command. If `--installed` is passed, show options for all installed formulae. - * `outdated [--quiet | --verbose | --json=v1 ]`: + * `outdated` [`--quiet` | `--verbose` | `--json=v1` ]: Show formulae that have an updated version available. By default, version information is displayed in interactive shells, and @@ -336,7 +335,7 @@ Note that these flags should only appear after a command. If `--verbose` is passed, display detailed version information. - If `--json=` is passed, the output will be in JSON format. The only + If `--json=` is passed, the output will be in JSON format. The only valid version is `v1`. * `pin` : @@ -350,7 +349,7 @@ Note that these flags should only appear after a command. * `reinstall` : Uninstall then install - * `rm`, `remove`, `uninstall [--force]` : + * `rm`, `remove`, `uninstall` [`--force`] : Uninstall . If `--force` is passed, and there are multiple versions of @@ -360,7 +359,7 @@ Note that these flags should only appear after a command. Display all locally available formulae for brewing (including tapped ones). No online search is performed if called without arguments. - * `search`, `-S` |//: + * `search`, `-S` |`/``/`: Perform a substring search of formula names for . If is surrounded with slashes, then it is interpreted as a regular expression. The search for is extended online to some popular taps. @@ -368,27 +367,27 @@ Note that these flags should only appear after a command. * `search --debian`|`--fedora`|`--fink`|`--macports`|`--opensuse`|`--ubuntu` : Search for in the given package manager's list. - * `sh [--env=std]`: + * `sh` [`--env=std`]: Instantiate a Homebrew build environment. Uses our years-battle-hardened Homebrew build logic to help your `./configure && make && make install` or even your `gem install` succeed. Especially handy if you run Homebrew - in a Xcode-only configuration since it adds tools like make to your PATH + in an Xcode-only configuration since it adds tools like `make` to your `PATH` which otherwise build-systems would not find. * `switch` : Symlink all of the specific of 's install to Homebrew prefix. - * `tap` [--full] [] []: + * `tap` [`--full`] `/` []: Tap a formula repository or list existing taps. This command can be invoked in three ways. + `tap` without arguments displays existing taps. - + `tap ` taps a formula repository from GitHub using HTTPS. + + `tap` `/`` taps a formula repository from GitHub using HTTPS. Since so many taps are hosted on GitHub, this command is a shortcut for - `tap user/repo https://github.com/#{user}/homebrew-#{repo}`. + `tap / https://github.com//homebrew-`. - + `tap ` taps a formula repository from anywhere, using + + `tap` `/` taps a formula repository from anywhere, using any transport protocol that `git` handles. The one-argument form of `tap` simplifies but also limits. This two-argument command makes no assumptions, so taps can be cloned from places other than GitHub and @@ -409,7 +408,7 @@ Note that these flags should only appear after a command. * `tap-info` : Display information about . - * `tap-info --json=` (--installed|): + * `tap-info` `--json=` (`--installed`|): Print a JSON representation of . Currently the only accepted value for is `v1`. @@ -425,8 +424,8 @@ Note that these flags should only appear after a command. * `tap-unpin` : Unpin so its formulae are no longer prioritized. See also `tap-pin`. - * `test` [--devel|--HEAD] [--debug] : - A few formulae provide a test method. `brew test ` runs this + * `test` [`--devel`|`--HEAD`] [`--debug`] : + A few formulae provide a test method. `brew test` runs this test method. There is no standard output or return code, but it should generally indicate to the user if something is wrong with the installed formula. @@ -439,7 +438,7 @@ Note that these flags should only appear after a command. Example: `brew install jruby && brew test jruby` - * `unlink [--dry-run]` : + * `unlink` [`--dry-run`] : Remove symlinks for from the Homebrew prefix. This can be useful for temporarily disabling a formula: `brew unlink foo && commands && brew link foo`. @@ -447,14 +446,14 @@ Note that these flags should only appear after a command. If `--dry-run` or `-n` is passed, Homebrew will list all files which would be unlinked, but will not actually unlink or delete any files. - * `unlinkapps [--local]` []: + * `unlinkapps` [`--local`] []: Removes links created by `brew linkapps`. If no are provided, all linked app will be removed. - * `unpack [--git|--patch] [--destdir=]` : + * `unpack` [`--git`|`--patch`] [`--destdir=`] : Unpack the source files for into subdirectories of the current - working directory. If `--destdir=` is given, the subdirectories will + working directory. If `--destdir=` is given, the subdirectories will be created in the directory named by `` instead. If `--patch` is passed, patches for will be applied to the @@ -470,13 +469,13 @@ Note that these flags should only appear after a command. * `untap` : Remove a tapped repository. - * `update [--rebase]`: + * `update` [`--rebase`]: Fetch the newest version of Homebrew and all formulae from GitHub using `git`(1). If `--rebase` is specified then `git pull --rebase` is used. - * `upgrade [install-options] [--cleanup]` []: + * `upgrade` [] [`--cleanup`] []: Upgrade outdated, unpinned brews. Options for the `install` command are also valid here. @@ -486,7 +485,7 @@ Note that these flags should only appear after a command. If are given, upgrade only the specified brews (but do so even if they are pinned; see `pin`, `unpin`). - * `uses [--installed] [--recursive] [--skip-build] [--skip-optional] [--devel|--HEAD]` : + * `uses` [`--installed`] [`--recursive`] [`--skip-build`] [`--skip-optional`] [`--devel`|`--HEAD`] : Show the formulae that specify as a dependency. When given multiple formula arguments, show the intersection of formulae that use . @@ -536,8 +535,8 @@ Note that these flags should only appear after a command. ## EXTERNAL COMMANDS Homebrew, like `git`(1), supports external commands. These are executable -scripts that reside somewhere in the PATH, named `brew-` or -`brew-.rb`, which can be invoked like `brew cmdname`. This allows you +scripts that reside somewhere in the `PATH`, named `brew-` or +`brew-``.rb`, which can be invoked like `brew` . This allows you to create your own commands without modifying Homebrew's internals. Instructions for creating your own commands can be found in the docs: @@ -552,7 +551,7 @@ can take several different forms: e.g. `git`, `node`, `wget`. * The fully-qualified name of a tapped formula: - Sometimes a formula from a tapped repository may conflict with one in Homebrew/homebrew. + Sometimes a formula from a tapped repository may conflict with one in `Homebrew/homebrew`. You can still access these formulae by using a special syntax, e.g. `homebrew/dupes/vim` or `homebrew/versions/node4`. @@ -563,65 +562,65 @@ can take several different forms: ## ENVIRONMENT - * AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY: - When using the S3 download strategy, Homebrew will look in + * `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`: + When using the `S3` download strategy, Homebrew will look in these variables for access credentials (see to retrieve these access credentials from AWS). If they are not set, - the S3 download strategy will download with a public + the `S3` download strategy will download with a public (unsigned) URL. - * BROWSER: + * `BROWSER`: If set, and `HOMEBREW_BROWSER` is not, use `BROWSER` as the web browser when opening project homepages. - * EDITOR: + * `EDITOR`: If set, and `HOMEBREW_EDITOR` and `VISUAL` are not, use `EDITOR` as the text editor. - * GIT: + * `GIT`: When using Git, Homebrew will use `GIT` if set, a Homebrew-built Git if installed, or the system-provided binary. Set this to force Homebrew to use a particular git binary. - * HOMEBREW\_BOTTLE\_DOMAIN: + * `HOMEBREW_BOTTLE_DOMAIN`: If set, instructs Homebrew to use the given URL as a download mirror for bottles. - * HOMEBREW\_BROWSER: + * `HOMEBREW_BROWSER`: If set, uses this setting as the browser when opening project homepages, instead of the OS default browser. - * HOMEBREW\_BUILD\_FROM\_SOURCE: + * `HOMEBREW_BUILD_FROM_SOURCE`: If set, instructs Homebrew to compile from source even when a formula provides a bottle. - * HOMEBREW\_CACHE: + * `HOMEBREW_CACHE`: If set, instructs Homebrew to use the given directory as the download cache. *Default:* `~/Library/Caches/Homebrew` if it exists; otherwise, `/Library/Caches/Homebrew`. - * HOMEBREW\_CURL\_VERBOSE: + * `HOMEBREW_CURL_VERBOSE`: If set, Homebrew will pass `--verbose` when invoking `curl`(1). - * HOMEBREW\_DEBUG: + * `HOMEBREW_DEBUG`: If set, any commands that can emit debugging information will do so. - * HOMEBREW\_DEBUG\_INSTALL: + * `HOMEBREW_DEBUG_INSTALL`: When `brew install -d` or `brew install -i` drops into a shell, `HOMEBREW_DEBUG_INSTALL` will be set to the name of the formula being brewed. - * HOMEBREW\_DEBUG\_PREFIX: + * `HOMEBREW_DEBUG_PREFIX`: When `brew install -d` or `brew install -i` drops into a shell, `HOMEBREW_DEBUG_PREFIX` will be set to the target prefix in the Cellar of the formula being brewed. - * HOMEBREW\_DEVELOPER: + * `HOMEBREW_DEVELOPER`: If set, Homebrew will print warnings that are only relevant to Homebrew developers (active or budding). - * HOMEBREW\_EDITOR: + * `HOMEBREW_EDITOR`: If set, Homebrew will use this editor when editing a single formula, or several formulae in the same directory. @@ -629,7 +628,7 @@ can take several different forms: directories. TextMate can handle this correctly in project mode, but many editors will do strange things in this case. - * HOMEBREW\_GITHUB\_API\_TOKEN: + * `HOMEBREW_GITHUB_API_TOKEN`: A personal access token for the GitHub API, which you can create at . If set, GitHub will allow you a greater number of API requests. See @@ -638,22 +637,22 @@ can take several different forms: *NOTE*: Homebrew doesn't require permissions for any of the scopes. - * HOMEBREW\_LOGS: + * `HOMEBREW_LOGS`: If set, Homebrew will use the given directory to store log files. - * HOMEBREW\_MAKE\_JOBS: + * `HOMEBREW_MAKE_JOBS`: If set, instructs Homebrew to use the value of `HOMEBREW_MAKE_JOBS` as the number of parallel jobs to run when building with `make`(1). *Default:* the number of available CPU cores. - * HOMEBREW\_NO\_EMOJI: + * `HOMEBREW_NO_EMOJI`: If set, Homebrew will not print the `HOMEBREW_INSTALL_BADGE` on a successful build. *Note:* Homebrew will only try to print emoji on Lion or newer. - * HOMEBREW\_NO\_INSECURE\_REDIRECT: + * `HOMEBREW_NO_INSECURE_REDIRECT`: If set, Homebrew will not permit redirects from secure HTTPS to insecure HTTP. @@ -664,21 +663,21 @@ can take several different forms: Apache formulae are currently unaffected by this variable and can redirect to plaintext. - * HOMEBREW\_NO\_GITHUB\_API: + * `HOMEBREW_NO_GITHUB_API`: If set, Homebrew will not use the GitHub API for e.g searches or fetching relevant issues on a failed install. - * HOMEBREW\_INSTALL\_BADGE: + * `HOMEBREW_INSTALL_BADGE`: Text printed before the installation summary of each successful build. Defaults to the beer emoji. - * HOMEBREW\_SVN: + * `HOMEBREW_SVN`: When exporting from Subversion, Homebrew will use `HOMEBREW_SVN` if set, a Homebrew-built Subversion if installed, or the system-provided binary. - Set this to force Homebrew to use a particular svn binary. + Set this to force Homebrew to use a particular `svn` binary. - * HOMEBREW\_TEMP: + * `HOMEBREW_TEMP`: If set, instructs Homebrew to use `HOMEBREW_TEMP` as the temporary directory for building packages. This may be needed if your system temp directory and Homebrew Prefix are on different volumes, as OS X has trouble moving @@ -687,15 +686,15 @@ can take several different forms: This issue typically occurs when using FileVault or custom SSD configurations. - * HOMEBREW\_VERBOSE: + * `HOMEBREW_VERBOSE`: If set, Homebrew always assumes `--verbose` when running commands. - * VISUAL: + * `VISUAL`: If set, and `HOMEBREW_EDITOR` is not, use `VISUAL` as the text editor. ## USING HOMEBREW BEHIND A PROXY -Homebrew uses several commands for downloading files (e.g. curl, git, svn). +Homebrew uses several commands for downloading files (e.g. `curl`, `git`, `svn`). Many of these tools can download via a proxy. It's common for these tools to read proxy parameters from environment variables. -- cgit v1.2.3