Skip to content

docs: repair the Homebrew install, broken by Homebrew 6 - #57

Merged
Periicles merged 1 commit into
mainfrom
docs/homebrew-quarantine
Aug 31, 2026
Merged

docs: repair the Homebrew install, broken by Homebrew 6#57
Periicles merged 1 commit into
mainfrom
docs/homebrew-quarantine

Conversation

@Periicles

Copy link
Copy Markdown
Owner

The install command we publish in the README and on the landing page does not work any more:

$ brew install --cask --no-quarantine notchbar
Error: invalid option: --no-quarantine

Homebrew removed the flag (ba25213c81, July 2026) and now quarantines every cask unconditionally. Dropping the flag is not enough — the installed bundle still carries com.apple.quarantine (0381;…), and NotchBar is ad-hoc signed, so Gatekeeper blocks the first launch. Both docs claimed the opposite: "they install and launch with no prompt at all."

What changes

  • The Homebrew block gains xattr -dr com.apple.quarantine /Applications/NotchBar.app, the step that now does what --no-quarantine used to.
  • Only the curl route is still described as prompt-free — curl sets no flag, so that claim was and stays true.
  • The Updating table repeats the xattr line. Homebrew carries an unquarantined app forward across an upgrade only while its signing identity is unchanged, and an ad-hoc signature is designated by the binary cdhash, which every build changes — so the release decision lands on :signer_changed and the new copy is quarantined again.
  • Landing page updated in both locales; "unsigned" reworded to "not notarized", which is what Gatekeeper actually objects to (the app is signed, ad-hoc).
  • Changelog compare links were stale at v0.3.0, leaving the 0.3.1 and 0.3.2 headings pointing at nothing.

Verification

The documented sequence was replayed from a clean uninstall on Homebrew 6.0.20:

brew install --cask notchbar         -> /Applications/NotchBar.app, quarantined 0381
xattr -dr com.apple.quarantine ...   -> No such xattr
codesign --verify --strict           -> exit 0 (signature intact)
open -a /Applications/NotchBar.app   -> process running, no Gatekeeper prompt

swift build and swift test (102 tests) pass — no source file is touched.

Note

This is a workaround, not a fix for the root cause. Every route that sets a quarantine flag now costs the user a step, which only notarization removes. Worth reconsidering whether the tap cask should carry a caveats stanza with the same line, so the step is visible to people who never read the README.

`brew install --cask --no-quarantine notchbar` — the command README and the
landing page both hand out — fails outright: Homebrew removed the flag and now
quarantines every cask unconditionally. Dropping the flag is not enough. The
installed bundle carries `com.apple.quarantine`, and NotchBar is ad-hoc signed,
so Gatekeeper blocks the first launch.

Document `xattr -dr com.apple.quarantine /Applications/NotchBar.app` as the step
that replaces the flag, and stop claiming the Homebrew route is prompt-free —
only the curl route still is, because curl sets no flag.

The step repeats on every upgrade: Homebrew carries an unquarantined app forward
only while its signing identity is unchanged, and an ad-hoc signature is
designated by the binary's `cdhash`, which each build changes.

Also fixes the changelog compare links, stale since 0.3.0, so the 0.3.1 and
0.3.2 headings resolve.
@Periicles Periicles self-assigned this Aug 31, 2026
@Periicles
Periicles merged commit 85c2398 into main Aug 31, 2026
4 checks passed
@Periicles
Periicles deleted the docs/homebrew-quarantine branch August 31, 2026 11:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant