mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity
brew/docs/Querying-Brew.md

72 lines
3.3 KiB
Markdown
Raw Normal View History

Cleanup documentation site GitHub now nicely generates a documentation site for us at http://brew.sh/brew based on our docs folder. Optimise the output of this and the GitHub docs directory for readability and the various user groupings.
2017-01-04 10:53:21 +00:00
# Querying `brew`
docs: fix titles on docs.brew.sh
2017-01-04 16:16:00 -06:00
update docs to use https urls Closes Homebrew/homebrew#40446. Signed-off-by: Xu Cheng <xucheng@me.com>
2015-06-06 00:25:48 +02:00
_In this document we will be using [jq](https://stedolan.github.io/jq/) to parse JSON, available from Homebrew using `brew install jq`._
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
## Overview
docs: grammar edits, sentence-case secondary headings Also changes some heading levels so only one primary heading appears per page.
2017-03-18 17:45:12 -04:00
`brew` provides commands for getting common types of information out of the system. `brew list` shows installed formulae. `brew deps foo` shows the dependencies that `foo` needs.
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
Additional commands, including external commands, can of course be written to provide more detailed information. There are a couple of disadvantages here. First, it means writing Ruby against a possibly changing Homebrew codebase. There will be more code to touch during refactors, and Homebrew can't guarantee that external commands will continue to work. Second, it means designing the commands themselves, specifying input parameters and output formats.
To enable users to do rich queries without the problems above, Homebrew provides the `brew info` command.
## `brew info --json`
docs/querying-brew: point to `brew info --help`.
2019-01-30 21:35:50 +00:00
`brew info` outputs JSON-formatted information about formulae. This JSON can then be parsed using your tools of choice. See more details in `brew info --help`.
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
The current schema version is `v1`. Note that fields may be added to the schema as needed without incrementing the schema. Any significant breaking changes will cause a change to the schema version.
Various documentation edits Mostly edits to formatting, grammar, wording for consistency & readability.
2018-10-05 17:23:22 -04:00
The schema itself is not currently documented outside of the code in [`formula.rb`](https://github.com/Homebrew/brew/blob/e9b9ea49a16b7879731d01ff2842460d33257a06/Library/Homebrew/formula.rb#L1594-L1680) that generates it.
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
## Examples
Grammar fixes for docs Fixes to spelling and punctuation for consistency and readability.
2017-02-23 12:20:07 -05:00
_The top-level element of the JSON output is always an array, so the `map` operator is used to act on the data._
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
Grammar fixes for docs Fixes to spelling and punctuation for consistency and readability.
2017-02-23 12:20:07 -05:00
### Pretty-print a single formula's info
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
```sh
brew info --json=v1 tig | jq .
```
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
### Installed formulae
To show full JSON information about all installed formulae:
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
```sh
brew info --json=v1 --all | jq "map(select(.installed != []))"
```
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
You'll note that processing all formulae can be slow; it's quicker to let `brew` do this:
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
```sh
brew info --json=v1 --installed
```
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
### Linked keg-only formulae
Querying-Brew.md: directors => directories
2017-03-14 09:59:14 +01:00
Some formulae are marked as "keg-only", meaning that installed files are not linked to the shared `bin`, `lib`, etc. directories, as doing so can cause conflicts. Such formulae can be forced to link to the shared directories, but doing so is not recommended (and will cause `brew doctor` to complain.)
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
To find the names of linked keg-only formulae:
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
```sh
brew info --json=v1 --installed | jq "map(select(.keg_only == true and .linked_keg != null) | .name)"
```
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
### Unlinked normal formulae
To find the names of normal (not keg-only) formulae that are installed, but not linked to the shared directories:
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
```sh
brew info --json=v1 --installed | jq "map(select(.keg_only == false and .linked_keg == null) | .name)"
```
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
cmd/info: display analytics data. When users don't have `HOMEBREW_NO_ANALYTICS` or `HOMEBREW_NO_GITHUB_API` set let's display some analytics data in `brew info`. This should be useful for both maintainers and for users of Homebrew. Note this by default combines all installs across options for a single number; for formulae with lots of options it's a bit overwhelming to print the installs per-option. However, for `HOMEBREW_DEVELOPER`s print the full output. Sample non-developer output: ```console $ brew info wget wget: stable 1.19.5 (bottled), HEAD Internet file retriever https://www.gnu.org/software/wget/ /usr/local/Cellar/wget/1.19.5 (49 files, 3.7MB) * Built from source on 2018-09-03 at 20:46:32 From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/wget.rb ==> Dependencies Build: pkg-config ✔ Required: libidn2 ✔, openssl ✔ Optional: pcre ✔, libmetalink ✘, gpgme ✘ ==> Options --with-debug Build with debug support --with-gpgme Build with gpgme support --with-libmetalink Build with libmetalink support --with-pcre Build with pcre support --HEAD Install HEAD version ==> Analytics install: 84638 (30d), 353800 (90d), 1372775 (365d) install_on_request: 77926 (30d), 291305 (90d), 1044898 (365d) build_error: 11 (30d) ``` Sample developer output: ```console $ brew info wget wget: stable 1.19.5 (bottled), HEAD Internet file retriever https://www.gnu.org/software/wget/ /usr/local/Cellar/wget/1.19.5 (49 files, 3.7MB) * Built from source on 2018-09-03 at 20:46:32 From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/wget.rb ==> Dependencies Build: pkg-config ✔ Required: libidn2 ✔, openssl ✔ Optional: pcre ✔, libmetalink ✘, gpgme ✘ ==> Options --with-debug Build with debug support --with-gpgme Build with gpgme support --with-libmetalink Build with libmetalink support --with-pcre Build with pcre support --HEAD Install HEAD version ==> Analytics ==> install (30d) wget: 84516 wget --with-debug: 51 wget --with-libressl: 16 wget --with-pcre: 14 wget --with-pcre --with-libmetalink --with-gpgme: 12 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 8 wget --HEAD: 3 wget --HEAD --with-debug --with-libmetalink --with-gpgme: 3 wget --with-gpgme: 3 wget --with-libmetalink: 3 wget --with-pcre --with-libmetalink: 3 wget --with-debug --with-pcre: 2 wget --with-libmetalink --with-gpgme: 2 wget --with-pcre --with-gpgme: 2 ==> install (90d) wget: 353131 wget --with-debug: 188 wget --with-pcre: 138 wget --with-pcre --with-libmetalink --with-gpgme: 118 wget --with-libressl: 81 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 47 wget --with-pcre --with-libmetalink: 31 wget --HEAD: 13 wget --with-pcre --with-gpgme: 12 wget --with-gpgme: 11 wget --with-debug --with-pcre: 10 wget --with-libmetalink: 8 wget --HEAD --with-pcre --with-libmetalink --with-gpgme: 4 wget --with-debug --with-pcre --with-libmetalink: 4 wget --with-libmetalink --with-gpgme: 4 ==> install (365d) wget: 1369530 wget --with-pcre: 810 wget --with-debug: 649 wget --with-pcre --with-libmetalink --with-gpgme: 554 wget --with-libressl: 479 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 235 wget --with-pcre --with-libmetalink: 184 wget --with-gpgme: 67 wget --with-pcre --with-gpgme: 67 wget --with-debug --with-pcre: 65 wget --HEAD: 54 wget --with-libmetalink: 30 wget --with-libmetalink --with-gpgme: 27 wget --with-debug --with-pcre --with-libmetalink: 24 ==> install_on_request (30d) wget: 77827 wget --with-debug: 48 wget --with-pcre: 12 wget --with-pcre --with-libmetalink --with-gpgme: 11 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 8 wget --HEAD: 3 wget --HEAD --with-debug --with-libmetalink --with-gpgme: 3 wget --with-gpgme: 3 wget --with-libmetalink: 3 wget --with-debug --with-pcre: 2 wget --with-libmetalink --with-gpgme: 2 wget --with-pcre --with-gpgme: 2 wget --with-pcre --with-libmetalink: 2 ==> install_on_request (90d) wget: 290818 wget --with-debug: 157 wget --with-pcre --with-libmetalink --with-gpgme: 101 wget --with-pcre: 100 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 42 wget --with-pcre --with-libmetalink: 30 wget --HEAD: 13 wget --with-pcre --with-gpgme: 11 wget --with-gpgme: 10 wget --with-debug --with-pcre: 8 wget --with-libmetalink: 7 wget --HEAD --with-pcre --with-libmetalink --with-gpgme: 4 wget --with-debug --with-pcre --with-libmetalink: 4 ==> install_on_request (365d) wget: 1042845 wget --with-pcre: 504 wget --with-debug: 458 wget --with-pcre --with-libmetalink --with-gpgme: 432 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 201 wget --with-pcre --with-libmetalink: 158 wget --with-gpgme: 61 wget --HEAD: 54 wget --with-pcre --with-gpgme: 49 wget --with-debug --with-pcre: 47 wget --with-debug --with-pcre --with-libmetalink: 24 wget --with-libressl: 23 wget --with-libmetalink: 22 wget --with-libmetalink --with-gpgme: 20 ==> build_error (30d) wget: 9 wget --HEAD: 1 wget --with-debug: 1 ```
2018-09-06 14:18:30 +01:00
## formulae.brew.sh
Various documentation edits Mostly edits to formatting, grammar, wording for consistency & readability.
2018-10-05 17:23:22 -04:00
[formulae.brew.sh](https://formulae.brew.sh) has a [documented JSON API](https://formulae.brew.sh/docs/api/) which provides access to the `brew info --json=v1` output without needing access to Homebrew.
cmd/info: display analytics data. When users don't have `HOMEBREW_NO_ANALYTICS` or `HOMEBREW_NO_GITHUB_API` set let's display some analytics data in `brew info`. This should be useful for both maintainers and for users of Homebrew. Note this by default combines all installs across options for a single number; for formulae with lots of options it's a bit overwhelming to print the installs per-option. However, for `HOMEBREW_DEVELOPER`s print the full output. Sample non-developer output: ```console $ brew info wget wget: stable 1.19.5 (bottled), HEAD Internet file retriever https://www.gnu.org/software/wget/ /usr/local/Cellar/wget/1.19.5 (49 files, 3.7MB) * Built from source on 2018-09-03 at 20:46:32 From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/wget.rb ==> Dependencies Build: pkg-config ✔ Required: libidn2 ✔, openssl ✔ Optional: pcre ✔, libmetalink ✘, gpgme ✘ ==> Options --with-debug Build with debug support --with-gpgme Build with gpgme support --with-libmetalink Build with libmetalink support --with-pcre Build with pcre support --HEAD Install HEAD version ==> Analytics install: 84638 (30d), 353800 (90d), 1372775 (365d) install_on_request: 77926 (30d), 291305 (90d), 1044898 (365d) build_error: 11 (30d) ``` Sample developer output: ```console $ brew info wget wget: stable 1.19.5 (bottled), HEAD Internet file retriever https://www.gnu.org/software/wget/ /usr/local/Cellar/wget/1.19.5 (49 files, 3.7MB) * Built from source on 2018-09-03 at 20:46:32 From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/wget.rb ==> Dependencies Build: pkg-config ✔ Required: libidn2 ✔, openssl ✔ Optional: pcre ✔, libmetalink ✘, gpgme ✘ ==> Options --with-debug Build with debug support --with-gpgme Build with gpgme support --with-libmetalink Build with libmetalink support --with-pcre Build with pcre support --HEAD Install HEAD version ==> Analytics ==> install (30d) wget: 84516 wget --with-debug: 51 wget --with-libressl: 16 wget --with-pcre: 14 wget --with-pcre --with-libmetalink --with-gpgme: 12 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 8 wget --HEAD: 3 wget --HEAD --with-debug --with-libmetalink --with-gpgme: 3 wget --with-gpgme: 3 wget --with-libmetalink: 3 wget --with-pcre --with-libmetalink: 3 wget --with-debug --with-pcre: 2 wget --with-libmetalink --with-gpgme: 2 wget --with-pcre --with-gpgme: 2 ==> install (90d) wget: 353131 wget --with-debug: 188 wget --with-pcre: 138 wget --with-pcre --with-libmetalink --with-gpgme: 118 wget --with-libressl: 81 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 47 wget --with-pcre --with-libmetalink: 31 wget --HEAD: 13 wget --with-pcre --with-gpgme: 12 wget --with-gpgme: 11 wget --with-debug --with-pcre: 10 wget --with-libmetalink: 8 wget --HEAD --with-pcre --with-libmetalink --with-gpgme: 4 wget --with-debug --with-pcre --with-libmetalink: 4 wget --with-libmetalink --with-gpgme: 4 ==> install (365d) wget: 1369530 wget --with-pcre: 810 wget --with-debug: 649 wget --with-pcre --with-libmetalink --with-gpgme: 554 wget --with-libressl: 479 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 235 wget --with-pcre --with-libmetalink: 184 wget --with-gpgme: 67 wget --with-pcre --with-gpgme: 67 wget --with-debug --with-pcre: 65 wget --HEAD: 54 wget --with-libmetalink: 30 wget --with-libmetalink --with-gpgme: 27 wget --with-debug --with-pcre --with-libmetalink: 24 ==> install_on_request (30d) wget: 77827 wget --with-debug: 48 wget --with-pcre: 12 wget --with-pcre --with-libmetalink --with-gpgme: 11 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 8 wget --HEAD: 3 wget --HEAD --with-debug --with-libmetalink --with-gpgme: 3 wget --with-gpgme: 3 wget --with-libmetalink: 3 wget --with-debug --with-pcre: 2 wget --with-libmetalink --with-gpgme: 2 wget --with-pcre --with-gpgme: 2 wget --with-pcre --with-libmetalink: 2 ==> install_on_request (90d) wget: 290818 wget --with-debug: 157 wget --with-pcre --with-libmetalink --with-gpgme: 101 wget --with-pcre: 100 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 42 wget --with-pcre --with-libmetalink: 30 wget --HEAD: 13 wget --with-pcre --with-gpgme: 11 wget --with-gpgme: 10 wget --with-debug --with-pcre: 8 wget --with-libmetalink: 7 wget --HEAD --with-pcre --with-libmetalink --with-gpgme: 4 wget --with-debug --with-pcre --with-libmetalink: 4 ==> install_on_request (365d) wget: 1042845 wget --with-pcre: 504 wget --with-debug: 458 wget --with-pcre --with-libmetalink --with-gpgme: 432 wget --with-debug --with-pcre --with-libmetalink --with-gpgme: 201 wget --with-pcre --with-libmetalink: 158 wget --with-gpgme: 61 wget --HEAD: 54 wget --with-pcre --with-gpgme: 49 wget --with-debug --with-pcre: 47 wget --with-debug --with-pcre --with-libmetalink: 24 wget --with-libressl: 23 wget --with-libmetalink: 22 wget --with-libmetalink --with-gpgme: 20 ==> build_error (30d) wget: 9 wget --HEAD: 1 wget --with-debug: 1 ```
2018-09-06 14:18:30 +01:00
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
## Concluding remarks
Grammar fixes for docs Fixes to spelling and punctuation for consistency and readability.
2017-02-23 12:20:07 -05:00
Using the JSON output, queries can be made against Homebrew with less risk of being broken due to Homebrew code changes, and without needing to understand Homebrew's Ruby internals.
Import docs from wiki. Closes Homebrew/homebrew#33211.
2014-10-26 14:54:36 +00:00
Grammar fixes for docs Fixes to spelling and punctuation for consistency and readability.
2017-02-23 12:20:07 -05:00
If the JSON output does not provide some information that it ought to, please submit a request, preferably with a patch to add the desired information.
Reference in New Issue Copy Permalink