From 37eaeac01d666ff86599746ac5c02f99b2ff378f Mon Sep 17 00:00:00 2001 From: Kevin Doran Date: Sat, 4 Jul 2026 11:05:24 -0400 Subject: [PATCH 1/2] Correct cask migration docs to measured behavior Live-tested on stable Homebrew 6.0.6: brew update auto-installs the formula via tap_migrations but leaves the cask installed with its binary owning pj on PATH; completing the migration requires uninstalling the cask and linking the formula. Also document the current Homebrew locking bug that breaks brew upgrade/reinstall for source-built tap formulae, with the uninstall+install workaround. --- docs/install.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/install.md b/docs/install.md index aff75bf..e4faf45 100644 --- a/docs/install.md +++ b/docs/install.md @@ -27,20 +27,34 @@ To upgrade to the latest version: brew upgrade pj ``` +> **Known issue**: Homebrew 6.0.x currently has a locking bug 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: From 7af0b07936abf6bc6c85856811d4b6f1455fc5fa Mon Sep 17 00:00:00 2001 From: Kevin Doran Date: Sat, 4 Jul 2026 11:14:13 -0400 Subject: [PATCH 2/2] Link upstream Homebrew issue in known-issue note --- docs/install.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/install.md b/docs/install.md index e4faf45..9a0d433 100644 --- a/docs/install.md +++ b/docs/install.md @@ -27,8 +27,9 @@ To upgrade to the latest version: brew upgrade pj ``` -> **Known issue**: Homebrew 6.0.x currently has a locking bug that can make -> `brew upgrade pj` (and `brew reinstall pj`) fail with +> **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: