Skip to content

Correct cask migration docs to measured behavior #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kevdoran merged 2 commits into from
Jul 4, 2026
Merged

Correct cask migration docs to measured behavior #34

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37eaeac
Correct cask migration docs to measured behavior
kevdoran Jul 4, 2026
7af0b07
Link upstream Homebrew issue in known-issue note
kevdoran Jul 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 21 additions & 6 deletions docs/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,20 +27,35 @@ To upgrade to the latest version:
brew upgrade pj
```

> **Known issue**: Homebrew 6.0.x currently has a locking bug
> ([Homebrew/brew#22948](https://github.com/Homebrew/brew/issues/22948)) that
> can make `brew upgrade pj` (and `brew reinstall pj`) fail with
> `Error: A process has already locked ...` for source-built tap formulae,
> even when no other brew process is running. Until the fix ships in Homebrew,
> upgrade with:
>
> ```bash
> brew uninstall pj && brew install pj
> ```

### Upgrading from a cask install

Prior to v1.0.0, `pj` was distributed as a Homebrew **cask**. It is now
distributed as a Homebrew **formula**. The tap includes a migration mapping
(`tap_migrations.json`), so the switch happens automatically on the next
upgrade (the `brew trust` step is required on Homebrew 6+, even if you tapped
before upgrading to it; skip it on brew < 5.1.15, where the command does not
exist):
(`tap_migrations.json`): when you run `brew update`, Homebrew detects the
removed cask and installs the `pj` formula automatically. It does **not**
remove the old cask, whose binary still owns `pj` on your PATH, so two more
commands complete the migration:

```bash
brew trust kevdoran/tap
brew update && brew upgrade pj
brew trust kevdoran/tap # Homebrew 6+ (skip on brew < 5.1.15)
brew update # installs the pj formula automatically
brew uninstall --cask pj # remove the old cask (still owns the pj binary)
brew link pj # activate the formula's pj
```

Verify with `pj version` — it should report the new version.

## Binary download

Grab the latest release from [GitHub Releases](https://github.com/kevdoran/projector/releases), extract the archive, and move `pj` to a directory on your PATH:
Expand Down
Loading