168 lines
4.6 KiB
Markdown
168 lines
4.6 KiB
Markdown
# Tap Migration
|
|
|
|
* [Overview](#overview)
|
|
* [What Users Should Do](#what-users-should-do)
|
|
* [Uncommitted Casks May Be Deleted](#uncommitted-casks-may-be-deleted)
|
|
* [If Something Goes Wrong](#if-something-goes-wrong)
|
|
* [Technical Background - Parent Project (Homebrew)](#parent-project-homebrew)
|
|
* [Technical Background - Our Project (Homebrew-cask)](#our-project-homebrew-cask)
|
|
|
|
## Overview
|
|
|
|
During April-May 2014, the default location of the Homebrew-cask Tap was
|
|
moved to a new location on disk, from
|
|
|
|
"$(brew --repository)"/Library/Taps/phinze-cask
|
|
|
|
to
|
|
|
|
"$(brew --repository)"/Library/Taps/caskroom/homebrew-cask
|
|
|
|
(where `"$(brew --repository)"` typically evaluates to `/usr/local`).
|
|
|
|
The migration should be seamless, but some users have experienced glitches.
|
|
We are still [making improvements](https://github.com/caskroom/homebrew-cask/pull/4169) to aid in the transition.
|
|
|
|
## What Users Should Do
|
|
|
|
All users should upgrade to the latest Homebrew (0.9.5 or better), and the
|
|
latest Homebrew-cask (0.34.0 or better):
|
|
|
|
```bash
|
|
$ brew update && brew upgrade brew-cask
|
|
```
|
|
|
|
The first time you execute a `brew cask` command, all Tap migrations
|
|
should happen for you automatically.
|
|
|
|
## Uncommitted Casks May Be Deleted
|
|
|
|
If you have recently created a Cask using "brew cask create", and have not
|
|
submitted that Cask to the main GitHub repository (meaning that your local
|
|
repository is dirty), you should be aware that Homebrew may delete your
|
|
uncommited Casks during the process of Tap migration. See
|
|
|
|
* <https://github.com/caskroom/homebrew-cask/issues/4312>
|
|
|
|
If you are not in the midst of authoring a Cask, this issue will not affect
|
|
you.
|
|
|
|
## If Something Goes Wrong
|
|
|
|
If something goes wrong with automatic Tap migration:
|
|
|
|
### Run "brew update" Twice
|
|
|
|
Try running `brew update` again. Some users report that Homebrew's Tap
|
|
migration does not fire on the first try.
|
|
|
|
### Run Any "brew cask" Command
|
|
|
|
Try running (for example) `brew cask doctor`. Each time you issue a `brew
|
|
cask` command, we examine your directory layout, and attempt to upgrade your
|
|
Taps to follow the new standard.
|
|
|
|
### Check Your Taps
|
|
|
|
The output of the command
|
|
|
|
```bash
|
|
$ brew tap
|
|
```
|
|
|
|
should show `caskroom/cask` in the output. It should **not** show the
|
|
old Tap `phinze/cask`.
|
|
|
|
### Manually Convert Your Taps
|
|
|
|
The following command should migrate you to the new Tap:
|
|
|
|
```bash
|
|
$ brew untap phinze/cask; brew tap caskroom/cask
|
|
```
|
|
|
|
### Manually Check Tap Directories
|
|
|
|
The following directory should exist:
|
|
|
|
```bash
|
|
$ ls -ld "$(brew --repository)"/Library/Taps/caskroom/homebrew-cask
|
|
```
|
|
|
|
The following directories should **not** exist:
|
|
|
|
```bash
|
|
$ ls -ld "$(brew --repository)"/Library/Taps/phinze/homebrew-cask
|
|
$ ls -ld "$(brew --repository)"/Library/Taps/phinze-cask
|
|
```
|
|
|
|
### "Could not tap" Message
|
|
|
|
You may see the message
|
|
|
|
Warning: Could not tap caskroom/homebrew-cask/brew-cask over phinze/homebrew-cask/brew-cask
|
|
|
|
during Tap migration, which means that two conflicting Taps are present.
|
|
|
|
The auto-migrate code should fix this problem. If you continue to see this
|
|
message on subsequent commands, refer to [Manually Check Tap Directories](#manually-check-tap-directories) above.
|
|
|
|
### File an Issue
|
|
|
|
Please do let us hear from you if you are having problems. Open an issue at
|
|
[GitHub issues page](https://github.com/caskroom/homebrew-cask/issues?state=open),
|
|
or find an open issue which duplicates your problem.
|
|
|
|
It would be helpful to run
|
|
|
|
```bash
|
|
$ brew cask doctor
|
|
```
|
|
|
|
and paste the results into your comment.
|
|
|
|
## Technical Background
|
|
|
|
### Parent Project (Homebrew)
|
|
|
|
Though we are separate projects, [Homebrew-cask](http://caskroom.io) is
|
|
built on the infrastructure provided by [Homebrew](http://brew.sh).
|
|
|
|
On [24 Apr 2014](https://github.com/Homebrew/homebrew/commit/e07584e3fbdc88327bafe23b9c40c904d0fff0a1), the parent project Homebrew changed the layout of
|
|
the Tap directory to follow the form
|
|
|
|
"$(brew --repository)"/Library/Taps/<username>/<repo-fullname>
|
|
|
|
rather than
|
|
|
|
"$(brew --repository)"/Library/Taps/<username>-<repo-shortname>
|
|
|
|
causing our project to be moved from
|
|
|
|
"$(brew --repository)"/Library/Taps/phinze-cask
|
|
|
|
to
|
|
|
|
"$(brew --repository)"/Library/Taps/phinze/homebrew-cask
|
|
|
|
### Our Project (Homebrew-cask)
|
|
|
|
On [3 May 2014](https://github.com/caskroom/homebrew-cask/pull/4163), our
|
|
project also made a change affecting Taps. The main Homebrew-cask repo
|
|
moved from
|
|
|
|
https://github.com/phinze/homebrew-cask
|
|
|
|
to
|
|
|
|
https://github.com/caskroom/homebrew-cask
|
|
|
|
This means that the username portion of our Tap path changed from `phinze`
|
|
to `caskroom`, *ie*:
|
|
|
|
"$(brew --repository)"/Library/Taps/phinze/homebrew-cask
|
|
|
|
became
|
|
|
|
"$(brew --repository)"/Library/Taps/caskroom/homebrew-cask
|