Skip to content

docs: retire the jbcom/homebrew-tap mirror — pkgs is the single tap #53

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
jbdevprimary merged 1 commit into from
Jul 20, 2026
Merged

docs: retire the jbcom/homebrew-tap mirror — pkgs is the single tap #53

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
9 changes: 5 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,14 @@ Pick the format that matches your OS.
### Homebrew (macOS, Linux, WSL2+Linuxbrew)

```bash
brew tap jbcom/tap
brew tap jbcom/pkgs https://github.com/jbcom/pkgs
brew install <package>
Comment on lines +14 to 15

@coderabbitai coderabbitai Bot Jul 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== README.md ==\n'
nl -ba README.md | sed -n '1,40p'

printf '\n== docs/ARCHITECTURE.md ==\n'
nl -ba docs/ARCHITECTURE.md | sed -n '1,60p'

printf '\n== Search for tap/install guidance ==\n'
rg -n "brew tap|brew install|fully qualified|Tap-Trust|jbcom/pkgs" README.md docs/ARCHITECTURE.md

Repository: jbcom/pkgs

Length of output: 205

🌐 Web query:

Homebrew Tap Trust unqualified brew install tap trusted same-named core formula behavior

💡 Result:

In Homebrew 6.0.0 and later, Homebrew requires explicit trust for third-party taps because they can contain arbitrary, unsandboxed Ruby code [1]. This trust model impacts how Homebrew resolves formulae when a name collides with one in homebrew/core. When you attempt to install a formula using its short name (e.g., brew install formula) and a same-named formula exists in both an untrusted tap and homebrew/core, Homebrew prioritizes the official core formula and does not load the untrusted tap [2][1]. Because the untrusted tap is not loaded, it is effectively ignored for unqualified installs [2][3]. To install a specific version of a formula from an untrusted tap when a name collision occurs, you must use the fully qualified name [2]: brew install user/repository/formula Using the fully qualified name implicitly trusts that specific item for that installation [2][4]. Alternatively, you can explicitly grant trust to the item or the entire tap before installation using the brew trust command [2][5]: brew trust --formula user/repository/formula # or brew trust user/repository Once a specific formula or tap is trusted, Homebrew will include it when evaluating formulae, and you may then be able to use the short name depending on Homebrew's internal resolution order, although using the fully qualified name remains the standard way to ensure you are referencing the specific tap-provided formula [2][6]. If you find that an untrusted tap is preventing you from accessing a formula, it is because Homebrew refuses to evaluate code from untrusted repositories to mitigate security risks [2][1].

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== Nearby README context ==\n'
nl -ba README.md | sed -n '1,80p'

printf '\n== Nearby docs/ARCHITECTURE context ==\n'
nl -ba docs/ARCHITECTURE.md | sed -n '1,120p'

printf '\n== Cask/formula mentions ==\n'
rg -n "\bcask\b|formula|brew install --cask|brew install <|brew tap" .

Repository: jbcom/pkgs

Length of output: 217

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== README.md ==\n'
sed -n '1,40p' README.md | cat -n

printf '\n== docs/ARCHITECTURE.md ==\n'
sed -n '1,80p' docs/ARCHITECTURE.md | cat -n

printf '\n== Relevant mentions ==\n'
grep -nE 'brew tap|brew install|cask|formula|jbcom/pkgs' README.md docs/ARCHITECTURE.md

Repository: jbcom/pkgs

Length of output: 6135

🌐 Web query:

docs.brew.sh Tap-Trust brew install unqualified formula from tapped repository trusted untrusted short name behavior

💡 Result:

In Homebrew, tap trust is a security feature that restricts Homebrew from loading code from non-official (third-party) taps unless they have been explicitly trusted [1]. When tap trust is required—which is the default behavior—you cannot install a formula from a third-party tap using its short name (e.g., brew install formula) if the tap is untrusted [1][2]. If you attempt to do so, Homebrew will refuse to load the formula [1][2]. To successfully install a formula from a third-party tap, you have the following options: 1. Trust the specific item: You can grant trust to only the required formula by running the command: brew trust --formula user/repository/formula [1] Once the specific formula is trusted, you can install it using its short name [1]. 2. Trust the entire tap: You can grant trust to all formulae, casks, and commands within a specific tap by running: brew trust user/repository [1] This allows Homebrew to load any current or future item from that tap, which is recommended for taps you administer or use extensively [1]. 3. Use a fully qualified name: Installing a formula using its fully qualified name (e.g., brew install user/repository/formula) acts as an implicit trust for that specific item [1][3]. Homebrew will communicate this implicit trust to you during the installation [3]. The requirement for tap trust is enforced to prevent unexpected code execution from untrusted third-party repositories [1][2]. You can check your current configuration or opt out of this requirement using the HOMEBREW_NO_REQUIRE_TAP_TRUST environment variable, though this is not recommended [1][4]. Official Homebrew taps are trusted by default [1][4].

Citations:

Use fully qualified Homebrew names here.
brew install <package> can fail on a third-party tap and may resolve to a core formula. Use brew install jbcom/pkgs/<formula> and brew install --cask jbcom/pkgs/<cask> instead in both examples.

  • README.md#L14-L15
  • docs/ARCHITECTURE.md#L21-L23
📍 Affects 2 files
  • README.md#L14-L15 (this comment)
  • docs/ARCHITECTURE.md#L21-L23
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 14 - 15, Update the Homebrew installation examples in
README.md lines 14-15 and docs/ARCHITECTURE.md lines 21-23 to use fully
qualified tap names: use jbcom/pkgs/<formula> for formula installs and
jbcom/pkgs/<cask> with --cask for cask installs in both locations.

```

The `jbcom/tap` shorthand resolves to `github.com/jbcom/homebrew-tap`,
a GoReleaser-managed mirror of this repo's `Formula/` directory. Both
locations stay in sync on every release.
The explicit URL form is required because this repo isn't named
`homebrew-pkgs`. Homebrew serves `Formula/` (and `Casks/`) straight from
this repo — the old `jbcom/homebrew-tap` mirror is retired; this is the
single distribution repo.
Comment on lines +18 to +21

@gemini-code-assist gemini-code-assist Bot Jul 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The repository layout (lines 42-65) does not list a Casks/ directory, and this repository currently only contains Homebrew formulas in Formula/. Mentioning (and Casks/) might be confusing to users looking for Casks. Consider removing it to keep the documentation accurate.

For example:

The explicit URL form is required because this repo isn't named
`homebrew-pkgs`. Homebrew serves `Formula/` straight from
this repo — the old `jbcom/homebrew-tap` mirror is retired; this is the
single distribution repo.

Comment on lines +18 to +21

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Update the public landing page to use the new tap

After retiring jbcom/homebrew-tap, the generated package index still tells Homebrew users to run brew tap jbcom/tap in src/data/pages/index.mdx:16. That command resolves to the retired mirror, so visitors using the public site—the primary package-install entry point—will not tap this repository. Update that page to the explicit jbcom/pkgs URL form as well.

Useful? React with 👍 / 👎.


### Scoop (Windows)

Expand Down
12 changes: 6 additions & 6 deletions docs/ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ domain: technical

The two are decoupled: packagers never need the site, and the site
never blocks a package install. If GitHub Pages is down, `brew tap
jbcom/tap && brew install <pkg>` still works because brew reads the
tap git tree directly.
jbcom/pkgs https://github.com/jbcom/pkgs && brew install <pkg>` still
works because brew reads the tap git tree directly.

## Data flow

Expand Down Expand Up @@ -53,10 +53,10 @@ tap git tree directly.
### Homebrew

- Canonical source: `Formula/<pkg>.rb` in this repo.
- Operators resolve `brew tap jbcom/tap` → `github.com/jbcom/homebrew-tap`
(convention-based shorthand). We publish to both this repo and the
mirror (`jbcom/homebrew-tap`) via two entries in the upstream's
`.goreleaser.yaml` so the shorthand keeps working.
- Operators tap with `brew tap jbcom/pkgs https://github.com/jbcom/pkgs`
(explicit URL form — the repo isn't named `homebrew-pkgs`). The old
`jbcom/homebrew-tap` mirror is retired; each upstream's release
pipeline publishes to this repo only.

### Scoop

Expand Down
Loading