homebrew-bigsur/homebrew-cask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README & docs: update wording/style

Browse Source
This commit is contained in:
Eric Knibbe
2023-09-11 14:11:36 -04:00
parent c80af0887c
commit e1f76fe7a3
4 changed files with 37 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/ISSUE_TEMPLATE/config.yml vendored
View File

@@ -12,4 +12,4 @@ contact_links:
about: Having a Homebrew formula problem? Report it to Homebrew/homebrew-core (the formula tap/repository)
- name: Ideas for a new feature
url: https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request
about: If you have an idea for a new feature here's how to add it to Brew
about: If you have an idea for a new feature, here's how to add it to Homebrew

19
CONTRIBUTING.md
View File

@@ -5,13 +5,12 @@
* [Updating a Cask](#updating-a-cask)
* [Getting Set Up To Contribute](#getting-set-up-to-contribute)
* [Adding a Cask](#adding-a-cask)
* [Style guide](#style-guide)
* [Style Guide](#style-guide)
* [Reporting Bugs](README.md#reporting-bugs)
## Updating a Cask
Notice an application that's out-of-date in Homebrew Cask? In most cases, it's very simple to update it. We have a command that will take care of updating the Cask file and submitting a pull request to us:
Notice an application that's out-of-date in Homebrew Cask? In most cases, it's very simple to update it. We have a command that will take care of updating the cask file and submitting a pull request to us:
```bash
brew bump --open-pr <outdated_cask>
@@ -29,15 +28,15 @@ Notice an application that's not in Homebrew Cask yet? Make sure it's not yet in
With a bit of work, you can create a cask for it. The documentation on [adding a cask](https://docs.brew.sh/Adding-Software-to-Homebrew#casks) will help you create, test, and submit a new cask to us.
## Style guide
## Style Guide
Some style guidelines:
* All Casks and code should be indented using two spaces (never tabs). When `brew style` contradicts this, `style` must be followed.
* All casks and code should be indented using two spaces (never tabs). When `brew style` contradicts this, `style` must be followed.
* There should not be any extraneous comments - the only comments that should be used are the ones explicitly defined in the [Cask Cookbook](https://docs.brew.sh/Cask-Cookbook).
* The stanza order and position of newlines is important to make things easier (See [Stanza order](https://docs.brew.sh/Cask-Cookbook#stanza-order)).
* Use string manipulations to improve the maintainability of your Cask (See [`version` methods](https://docs.brew.sh/Cask-Cookbook#version-methods)).
* Test your cask using `brew audit/style` (See [testing](https://docs.brew.sh/Adding-Software-to-Homebrew#testing-your-new-cask)).
* Make one Pull Request per Cask change.
* Do not squash commits after updating a Pull Request.
* The stanza order and position of newlines is important to make things easier (see [Stanza order](https://docs.brew.sh/Cask-Cookbook#stanza-order)).
* Use string manipulations to improve the maintainability of your cask (see [`version` methods](https://docs.brew.sh/Cask-Cookbook#version-methods)).
* Test your cask using `brew audit` and `brew style` (see the documentation on [testing and auditing](https://docs.brew.sh/Adding-Software-to-Homebrew#testing-and-auditing-the-cask)).
* Make one pull request per cask change.
* Do not squash commits after updating a pull request.
* Use descriptive commit messages - mention cask name and version/change (ie. `transmission 2.82`, `google-chrome: update zap`).

13
README.md
View File

@@ -34,7 +34,7 @@ And there we have it. An application installed with one quick command: no clicki
* Want to contribute a cask? Awesome! See [CONTRIBUTING.md](CONTRIBUTING.md).
* More project-related details and discussion are available in the [documentation](https://docs.brew.sh/Adding-Software-to-Homebrew#casks).
## Reporting bugs
## Reporting Bugs
[**If you ignore this guide, your issue may be closed without review**](doc/faq/closing_issues_without_review.md)
@@ -45,11 +45,11 @@ If your issue persists, [search for it](https://github.com/Homebrew/homebrew-cas
If the issue is still not solved, see the guides for common problems:
* [Examples of common errors and their solutions](doc/reporting_bugs/error_examples.md)
* [`curl` error](doc/reporting_bugs/error_examples.md#curl-error)
* [`Permission denied` error](doc/reporting_bugs/error_examples.md#permission-denied-error)
* [`Checksum does not match` error](doc/reporting_bugs/error_examples.md#checksum-does-not-match-error)
* [`source is not there` error](doc/reporting_bugs/error_examples.md#source-is-not-there-error)
* [`wrong number of arguments` error](doc/reporting_bugs/error_examples.md#wrong-number-of-arguments-error)
* [`curl` error](doc/reporting_bugs/error_examples.md#curl-error)
* [`Permission denied` error](doc/reporting_bugs/error_examples.md#permission-denied-error)
* [`Checksum does not match` error](doc/reporting_bugs/error_examples.md#checksum-does-not-match-error)
* [`source is not there` error](doc/reporting_bugs/error_examples.md#source-is-not-there-error)
* [`wrong number of arguments` error](doc/reporting_bugs/error_examples.md#wrong-number-of-arguments-error)
* [App isn’t included in `upgrade`](https://docs.brew.sh/FAQ#why-arent-some-apps-included-during-brew-upgrade)
* [The app can’t be opened because it is from an unidentified developer](https://docs.brew.sh/FAQ#why-cant-i-open-a-mac-app-from-an-unidentified-developer)
* [My problem isn’t listed](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.yml)
@@ -67,4 +67,5 @@ We’re really rather friendly! Here are the best places to talk about the proje
* Join us on [GitHub discussions (forum)](https://github.com/orgs/Homebrew/discussions/categories/casks).
## License
Code is under the [BSD 2 Clause (NetBSD) license](LICENSE).

40
USAGE.md
View File

@@ -11,7 +11,7 @@ Homebrew Cask is implemented as part of [Homebrew](https://brew.sh). All Homebre
## Searching for Casks
To search for Casks, use `brew search`. Let’s see if there’s a Cask for Google Chrome:
To search for casks, use `brew search`. Let’s see if there’s a cask for Google Chrome:
```console
$ brew search --cask google-chrome
@@ -41,7 +41,7 @@ Easy peasy:
$ brew uninstall --cask google-chrome
```
This will both uninstall the Cask and remove applications which were moved to `/Applications`.
This will both uninstall the cask and remove the applications that were moved to `/Applications`.
## Other Commands
@@ -114,7 +114,7 @@ KeepingYouAwake.app (App)
## Updating/Upgrading Casks
Since the Homebrew Cask repository is a Homebrew Tap, you’ll pull down the latest Casks every time you issue the regular Homebrew command `brew update`. You can check for outdated Casks with `brew outdated` and install the outdated Casks with `brew upgrade`. Many applications update themselves, so their Casks are ignored by `brew outdated` and `brew upgrade`. This behaviour can be overridden by adding `--greedy` to the command.
Since the Homebrew Cask repository is a Homebrew tap, you’ll pull down the latest casks every time you issue the regular Homebrew command `brew update`. You can check for outdated casks with `brew outdated` and install the outdated casks with `brew upgrade`. Many applications update themselves, so their casks are ignored by `brew outdated` and `brew upgrade`. This behaviour can be overridden by adding `--greedy` to either command.
## Updating/Upgrading the Homebrew Cask Tool
@@ -122,22 +122,22 @@ Homebrew [automatically taps and keeps Homebrew Cask updated](https://github.com
## Additional Taps (optional)
The primary Homebrew Cask Tap includes most of the Casks that a typical user will be interested in. There are a few additional Taps where we store different kinds of Casks.
The primary Homebrew Cask tap includes most of the casks that a typical user will be interested in. There are a few additional taps where we store different kinds of casks.
| Tap name | description |
| tap name | description |
| -------- | ----------- |
| [Homebrew/cask-versions](https://github.com/Homebrew/homebrew-cask-versions) | contains alternate versions of Casks (_e.g._ betas, nightly releases, old versions)
| [Homebrew/cask-fonts](https://github.com/Homebrew/homebrew-cask-fonts) | contains Casks that install fonts
| [homebrew/cask-versions](https://github.com/Homebrew/homebrew-cask-versions) | contains alternate versions of casks (_e.g._ betas, nightly releases, old versions)
| [homebrew/cask-fonts](https://github.com/Homebrew/homebrew-cask-fonts) | contains casks that install fonts
You can tap any of the above with a `brew tap` command:
You can tap any of the above with the `brew tap` command:
```bash
brew tap <tap_name>
```
after which, Casks from the new Tap will be available to `search` or `install` just like Casks from the main Tap. `brew update` will automatically keep your new Tap up to date.
after which casks from the new tap will be available to `search` or `install` just like casks from the main tap. `brew update` will automatically keep your new tap up to date.
You may also specify a fully-qualified Cask token (which includes the Tap) for any `brew` command. This will implicitly add the Tap if you have not previously added it with `brew tap`:
You may also specify a fully-qualified cask token (which includes the tap) for any `brew` command. This will implicitly add the tap if you have not previously added it with `brew tap`:
```bash
brew install homebrew/cask-fonts/font-symbola
@@ -150,14 +150,14 @@ brew install homebrew/cask-fonts/font-symbola
* `--version`: print version and exit.
* `--debug`: output debug information.
* `--no-binaries`: skip symlinking executable binaries into `/usr/local/bin`.
* `--require-sha`: abort installation of Cask if no checksum is defined.
* `--require-sha`: abort installation of cask if no checksum is defined.
* `--no-quarantine`: [disable Apple’s quarantining](https://docs.brew.sh/FAQ#why-cant-i-open-a-mac-app-from-an-unidentified-developer) for the specific app.
* `--language=<iso-language>[,<iso-language> ... ]`: changes the language of the Cask to be installed. The first matching language is used, otherwise it uses the default language of the Cask.
* `--language=<iso-language>[,<iso-language> ... ]`: changes the language of the cask to be installed. The first matching language is used, otherwise it uses the default language of the cask.
You can also modify the default installation locations used when issuing `brew install`:
* `--appdir=/my/path` changes the path where the applications will be moved. Default is `/Applications`.
* `--fontdir=/my/path` changes the path for Fonts. Default is `~/Library/Fonts`.
* `--fontdir=/my/path` changes the path for fonts. Default is `~/Library/Fonts`.
See `man brew` for the other default installation locations and the flags to change them.
@@ -178,19 +178,19 @@ brew install --appdir="/Applications" google-chrome
## Other Ways to Specify a Cask
Most `brew` commands can accept a Cask token as an argument. As described above, the token on the command line can take the form of:
Most `brew` commands can accept a cask token as an argument. As described above, the token on the command line can take the form of:
* A simple token, _e.g._: `google-chrome`.
* A fully-qualified token which includes the Tap, _e.g._: `homebrew/cask/google-chrome`.
* A fully-qualified token which includes the tap, _e.g._: `homebrew/cask/google-chrome`.
`brew` also accepts three other forms as arguments:
* A path to a Cask file, _e.g._: `/usr/local/Library/Taps/homebrew/homebrew-cask/Casks/google-chrome.rb`.
* A `curl`-retrievable URI to a Cask file, _e.g._: `https://raw.githubusercontent.com/Homebrew/homebrew-cask/f25b6babcd398abf48e33af3d887b2d00de1d661/Casks/google-chrome.rb`.
* A file in the current working directory, _e.g._: `my-modified-google-chrome.rb`. Note that matching Tapped Cask tokens will be preferred over this form when there is a conflict. To force the use of a Cask file in the current directory, specify a pathname with slashes, _e.g._: `./google-chrome.rb`.
* A path to a cask file, _e.g._: `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/g/google-chrome.rb`.
* A `curl`-retrievable URI to a cask file, _e.g._: `https://raw.githubusercontent.com/Homebrew/homebrew-cask/HEAD/Casks/g/google-chrome.rb`.
* A file in the current working directory, _e.g._: `my-modified-google-chrome.rb`. Note that matching tapped cask tokens will be preferred over this form when there is a conflict. To force the use of a cask file in the current directory, specify a pathname with slashes, _e.g._: `./google-chrome.rb`.
The last three forms are intended for users who wish to maintain private Casks.
The last three forms are intended for users who wish to maintain private casks.
## Taps
You can add Casks to your existing (or new) Taps: just create a directory named `Casks` inside your Tap, put your Cask files there, and everything will just work.
You can add casks to your existing (or new) taps: just create a directory named `Casks` inside your tap, put your cask files there, and everything will just work.