Skip to content

Commit

Permalink
README & docs: update wording/style
Browse files Browse the repository at this point in the history
  • Loading branch information
@EricFromCanada
EricFromCanada committed Sep 11, 2023
1 parent c80af08 commit e1f76fe
Show file tree
Hide file tree
Showing 4 changed files with 37 additions and 37 deletions.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/config.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 9 additions & 10 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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 changes: 7 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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)
Expand All @@ -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 changes: 20 additions & 20 deletions USAGE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -114,30 +114,30 @@ 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

Homebrew [automatically taps and keeps Homebrew Cask updated](https://github.com/Homebrew/homebrew-cask/pull/15381). `brew update` is all that is required.

## 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
Expand All @@ -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.

Expand All @@ -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.

0 comments on commit e1f76fe

Please sign in to comment.