2014-01-15 22:55:30 +08:00
# How to Use Homebrew-cask
2013-04-29 03:20:03 +08:00
2013-12-08 02:16:58 +08:00
## Getting Started
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
First ensure you have Homebrew version '0.9.5' or higher:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew --version
0.9.5
```
2013-04-29 03:20:03 +08:00
2014-01-18 09:14:48 +08:00
Install the homebrew-cask tool:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
2014-05-03 23:16:12 +08:00
$ brew install caskroom/cask/brew-cask
2014-01-15 22:55:30 +08:00
```
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
## Frequently Used Commands
2013-11-10 21:36:03 +08:00
2014-01-18 09:14:48 +08:00
Homebrew-cask is implemented as a subcommand of Homebrew. All homebrew-cask
2014-01-15 22:55:30 +08:00
commands begin with `brew cask` . Homebrew-cask has its own set of command
verbs many of which are similar to Homebrew's. The most frequently-used
commands are:
2013-12-16 05:08:27 +08:00
2014-01-15 22:55:30 +08:00
* `search` -- searches all known Casks
* `install` -- installs the given Cask
* `uninstall` -- uninstalls the given Cask
2013-12-16 05:08:27 +08:00
2014-01-15 22:55:30 +08:00
## Searching for Casks
2013-12-16 05:08:27 +08:00
2014-11-29 03:36:16 +08:00
The `brew cask search` command accepts a series of substring arguments,
and returns tokens representing matching Casks. Let's see if there's a
Cask for Google Chrome:
2013-12-16 05:08:27 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew cask search chrome
google-chrome
```
2013-11-10 21:36:03 +08:00
2014-01-15 22:55:30 +08:00
A `search` command with no search term will list all available Casks:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew cask search
# <list of all available Casks>
```
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
## Installing Casks
2013-04-29 03:20:03 +08:00
2014-11-29 03:36:16 +08:00
The command `brew cask install` accepts a Cask token as returned by `brew cask search` .
2014-01-15 22:55:30 +08:00
Let's try to install Google Chrome:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew cask install google-chrome
==> Downloading https://dl.google.com/chrome/mac/stable/GGRO/googlechrome.dmg
==> Success! google-chrome installed to /opt/homebrew-cask/Caskroom/google-chrome/stable-channel
==> Linking Google Chrome.app to /Users/paulh/Applications/Google Chrome.app
```
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
## Uninstalling Casks
Easy peasy:
```bash
$ brew cask uninstall google-chrome
```
This will both uninstall the Cask and remove symlinks which were created in
`~/Applications` .
2014-09-16 01:50:09 +08:00
To uninstall all versions of a Cask, use `--force` :
```bash
$ brew cask uninstall --force google-chrome
```
Note that `uninstall --force` is currently imperfect. See the man page for
more information.
2014-01-15 22:55:30 +08:00
## Other Commands
* `info` -- displays information about the given Cask
2014-10-20 23:18:17 +08:00
* `list` -- with no args, lists installed Casks; given installed Casks, lists staged files
2014-02-16 06:10:46 +08:00
* `fetch` -- downloads Cask resources to local cache (with `--force` , re-download even if already cached)
2014-01-15 22:55:30 +08:00
* `doctor` -- checks for configuration issues
2014-02-05 22:42:36 +08:00
* `cleanup` -- cleans up cached downloads (with `--outdated` , only cleans old downloads)
2014-01-24 06:17:33 +08:00
* `home` -- opens the homepage of the given Cask; or with no arguments, the homebrew-cask project page
2014-02-21 23:23:16 +08:00
* `update` -- a synonym for `brew update`
2014-09-09 22:47:18 +08:00
* `zap` -- try to remove *all* files associated with a Cask (including resources which may be shared with other applications)
2014-01-15 22:55:30 +08:00
The following commands are for Cask authors:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
* `audit` -- verifies installability of Casks
2014-05-07 21:29:37 +08:00
* `cat` -- dumps the given Cask to the standard output
2014-01-15 22:55:30 +08:00
* `create` -- creates a Cask and opens it in an editor
* `edit` -- edits the given Cask
2013-04-29 03:20:03 +08:00
2014-02-24 21:06:46 +08:00
The following aliases and abbreviations are provided for convenience:
* `ls` -- `list`
* `-S` -- `search`
* `rm` , `remove` -- `uninstall`
* `up` -- `update`
* `dr` -- `doctor`
2013-04-29 03:20:03 +08:00
## Inspecting Installed Casks
List all installed Casks
2014-01-15 22:55:30 +08:00
```bash
$ brew cask list
adium google-chrome onepassword
```
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
Show details about a specific Cask:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```bash
$ brew cask info caffeine
caffeine: 1.1.1
http://lightheadsw.com/caffeine/
Not installed
2014-06-21 07:19:07 +08:00
https://github.com/caskroom/homebrew-cask/blob/master/Casks/caffeine.rb
2014-01-15 22:55:30 +08:00
```
2013-04-29 03:20:03 +08:00
## Updating/Upgrading Casks
2014-01-18 09:14:48 +08:00
Since the homebrew-cask repository is a Homebrew Tap, you'll pull down the latest
2014-01-15 22:55:30 +08:00
Casks every time you issue the regular Homebrew command `brew update` . Currently,
2014-01-18 09:14:48 +08:00
homebrew-cask cannot always detect if an Application has been updated. You
2014-01-15 22:55:30 +08:00
can force an update via the command `brew cask install --force` . We are working
on improving this.
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
It is generally safe to run updates from within an Application.
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
## Updating/Upgrading the Homebrew-cask Tool
2014-01-18 09:14:48 +08:00
When a new version homebrew-cask is released, it will appear in the output of
2014-01-15 22:55:30 +08:00
`brew outdated` after running `brew update` . You can upgrade it via the normal
2014-06-18 23:48:51 +08:00
Homebrew `brew upgrade` workflow:
```bash
$ brew update & & brew upgrade brew-cask & & brew cleanup & & brew cask cleanup
```
2014-01-15 22:55:30 +08:00
## Additional Taps (optional)
2014-01-18 09:14:48 +08:00
The primary homebrew-cask Tap includes most of the Casks that a typical user will
2014-01-15 22:55:30 +08:00
be interested in. There are a few additional Taps where we store different kinds
of Casks.
| Tap name | description |
| -------- | ----------- |
2014-09-28 01:35:49 +08:00
| [caskroom/versions ](https://github.com/caskroom/homebrew-versions ) | contains alternate versions of Casks (e.g. betas, nightly releases, old versions)
| [caskroom/fonts ](https://github.com/caskroom/homebrew-fonts ) | contains Casks that install fonts, which are kept separate so we can educate users about the different licensing landscape around font installation/usage
2014-06-03 23:57:11 +08:00
| [caskroom/unofficial ](https://github.com/caskroom/homebrew-unofficial ) | contains Casks that install unofficial builds or forks
2013-04-29 03:20:03 +08:00
2014-12-03 01:20:13 +08:00
There are also [alternate Cask Taps ](doc/alternate_cask_taps.md#alternate-cask-taps-maintained-by-users ) maintained by users.
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
You can tap any of the above with a `brew tap` command:
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
```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.
2014-11-29 03:36:16 +08:00
You may also specify a fully-qualified Cask token (which includes the Tap) for any `brew cask` command. This will implicitly add the Tap if you have not previously added it with `brew tap` :
2014-01-15 22:55:30 +08:00
```bash
$ brew cask install caskroom/fonts/font-symbola
```
2013-04-29 03:20:03 +08:00
## Options
2014-01-06 04:30:53 +08:00
`brew cask` accepts a number of options:
* `--version` : print version and exit
* `--debug` : output debug information
2014-01-15 22:55:30 +08:00
* `--no-binaries` : skip symlinking executable binaries into `/usr/local/bin`
2014-01-06 04:30:53 +08:00
2014-05-13 22:46:32 +08:00
You can also modify the default installation locations used when issuing `brew cask install` :
2013-12-14 17:07:26 +08:00
2013-12-14 17:10:50 +08:00
* `--caskroom=/my/path` determines where the actual applications will be located.
2015-03-17 08:51:34 +08:00
Should be handled with care — setting it outside `/opt` or your home directory might mess up your system.
Default is `/opt/homebrew-cask/Caskroom` .
2013-12-14 17:10:50 +08:00
* `--appdir=/my/path` changes the path where the symlinks to the applications (above)
will be generated. This is commonly used to create the links in the _root_ Applications directory
instead of the _home_ Applications directory by specifying `--appdir=/Applications` . Default is `~/Applications` .
* `--prefpanedir=/my/path` changes the path for PreferencePane symlinks.
2013-12-14 17:07:26 +08:00
Default is `~/Library/PreferencePanes`
2013-12-14 17:10:50 +08:00
* `--qlplugindir=/my/path` changes the path for Quicklook Plugin symlinks.
2013-12-14 17:07:26 +08:00
Default is `~/Library/QuickLook`
2013-12-14 17:10:50 +08:00
* `--fontdir=/my/path` changes the path for Fonts symlinks.
2013-12-14 17:07:26 +08:00
Default is `~/Library/Fonts`
2014-01-06 04:30:53 +08:00
* `--binarydir=/my/path` changes the path for binary symlinks.
Default is `/usr/local/bin`
2014-01-14 01:21:44 +08:00
* `--input_methoddir=/my/path` changes the path for Input Methods symlinks.
Default is `~/Library/Input Methods`
2014-01-30 00:27:44 +08:00
* `--screen_saverdir=/my/path` changes the path for Screen Saver symlinks.
2014-01-28 23:17:50 +08:00
Default is `~/Library/Screen Savers`
2013-12-14 17:07:26 +08:00
2014-01-15 22:55:30 +08:00
To make these settings persistent, you might want to add the following line to your `.bash_profile` or `.zshenv` :
2013-04-29 03:20:03 +08:00
```bash
2013-12-14 17:10:50 +08:00
# Specify your defaults in this environment variable
2013-12-14 17:07:26 +08:00
export HOMEBREW_CASK_OPTS="--appdir=/Applications --caskroom=/etc/Caskroom"
```
2013-04-29 03:20:03 +08:00
2013-12-14 17:10:50 +08:00
Note that you still can override the environment variable `HOMEBREW_CASK_OPTS` by _explicitly_ providing
2014-01-15 22:55:30 +08:00
options in the command line:
2013-04-29 03:20:03 +08:00
2013-12-14 17:07:26 +08:00
```bash
# Will force the Chrome app to be linked to ~/Applications
2013-12-14 17:10:50 +08:00
# even though HOMEBREW_CASK_OPTS specified /Applications
2013-04-29 03:20:03 +08:00
$ brew cask install --appdir="~/Applications" google-chrome
```
2014-01-23 01:56:37 +08:00
## Advanced searching
The default search algorithm is a lax substring approach, which does not
use the command-line arguments exactly as given. If you need to specify
a search more precisely, a single search argument enclosed in `/` characters
will be taken as a Ruby regular expression:
```bash
$ brew cask search '/^google.c[a-z]rome$/'
google-chrome
```
2014-01-15 22:55:30 +08:00
## Other Ways to Specify a Cask
2014-11-29 03:36:16 +08:00
Most `brew cask` commands can accept a Cask token as an argument. As described
above, the token on the command line can take the form of:
2014-01-15 22:55:30 +08:00
2014-11-29 03:36:16 +08:00
* a token as returned by `brew cask search` , _eg_ : `google-chrome`
* a fully-qualified token which includes the Tap, _eg_ : `caskroom/fonts/font-symbola`
2014-01-15 22:55:30 +08:00
2014-11-29 03:36:16 +08:00
`brew cask` also accepts three other forms as arguments
2014-01-15 22:55:30 +08:00
2014-11-29 03:36:16 +08:00
* a path to a Cask file, _eg_ : `/usr/local/Cellar/brew-cask/0.25.0/Casks/google-chrome.rb`
* a `curl` -retrievable URI to a Cask file, _eg_ : `https://raw.github.com/caskroom/homebrew-cask/f54bbfaae0f2fa7210484f46313a459cb8a14d2f/Casks/google-chrome.rb`
* a file in the current working directory, _eg_ : `my-modfied-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, _eg_ : `./google-chrome.rb` .
2014-01-15 22:55:30 +08:00
2014-06-03 22:21:42 +08:00
The last three forms are intended for users who wish to maintain private Casks.
2014-01-15 22:55:30 +08:00
## Taps
2013-04-29 03:20:03 +08:00
2014-01-15 22:55:30 +08:00
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.