[WIP] diagnostic: check outdated mirrors and repositories #21383

botantony · 2026-01-10T20:56:42Z

Have you followed the guidelines in our Contributing document?
Have you checked to ensure there aren't other open Pull Requests for the same change?
Have you added an explanation of what your changes do and why you'd like us to include them?
Have you written new tests for your changes? Here's an example.
Have you successfully run brew lgtm (style, typechecking and tests) with your changes locally?

Draft PR, feel free to discuss and suggest changes (what checks should be added/removed, other mirrors with known problems, etc.)

Library/Homebrew/diagnostic.rb

Signed-off-by: botantony <antonsm21@gmail.com>

Bo98 · 2026-01-11T05:31:15Z

Library/Homebrew/diagnostic.rb

+            HOMEBREW_CORE_DEFAULT_GIT_REMOTE,
+            "https://github.com/Homebrew/homebrew-cask", # There's no `HOMEBREW_CASK_DEFAULT_GIT_REMOTE`


These two can intentionally get outdated on a device without HOMEBREW_NO_INSTALL_FROM_API so may want to conditionally include these two.

(as demonstrated by the CI failures here)

We have another doctor check telling people to untap them unless HOMEBREW_NO_INSTALL_FROM_API or HOMEBREW_DEVELOPER are set so agreed we should match that logic.

Bo98 · 2026-01-11T05:37:31Z

Library/Homebrew/diagnostic.rb

            You can solve this by setting the origin remote:
              git -C "#{repository_path}" remote set-url origin #{Formatter.url(desired_origin)}
          EOS
+        elsif (Time.now - last_commit_time) > Homebrew::API::DEFAULT_API_STALE_SECONDS


Just using the default auto-update stale interval is too short for multiple reasons. Firstly, it might have just not got to auto-forcing an update yet if it has just passed - you want some leeway.

Secondly, there's also some things with slower update cadences, e.g: GitHub Actions images for example could be outdated by as much as a month. For end-users, this cadence might actually be more sporadic as not every command triggers an auto-update.

And thirdly since this also checks Homebrew/brew, people without developer mode enabled might not even have 1 update a week. We sometimes have made releases on 2-3 week intervals if something is baking in main. And it's worth having some extra leeway on top of that in case something major happens.

Overall point being: I don't think we want to make this too tight to simply be a "it's been a couple days, Homebrew might have an update" check and lean more towards a "Homebrew installation is obviously majorly outdated" check. The problems that inspired this check have all been cases where things have been outdated by several months.

Agreed. This could be hardcoded to a month or more.

Bo98 · 2026-01-11T05:39:25Z

Library/Homebrew/diagnostic.rb

+          cask_tap_migrations.jws.json
+          cask.jws.json
+          formula_tap_migrations.jws.json
+          formula.jws.json


Are these all correct under the new internal API?

They won't be, no. We should use existing API methods for this rather than hardcoding filenames here. We only really need to check a single file here, not all.

Bo98 · 2026-01-11T05:40:02Z

Library/Homebrew/diagnostic.rb

+        # These are popular mirrors with known problems
+        bad_mirrors = [
+          %r{^https?://mirrors\.aliyun\.com/homebrew/.+}, # Last update was in May 2025
+        ]
+        problems = []


This seems annoying to maintain - any entry could spring to life at a moments notice and there could be others we're not aware of. It might even do the opposite of what we want and discourage mirrors from fixing their outdated ones in favour of just making a new URL (easier than requesting us to delist it from here). It's technically also incorrect as while the API mirror is outdated, the brew git mirror is not.

In any case, does this check matter if the other one is always going to trigger anyway (and already mentions mirrors)? You're going to get two warnings that effectively say the same thing. This can be an open question to other reviewers too.

It's technically also incorrect as while the API mirror is outdated, the brew git mirror is not.

This feels like something we should check instead of some of these other checks.

Ultimately it doesn't matter if Homebrew/brew and Homebrew/homebrew-core are both outdated by the same amount. We should compare the timestamps in both and if they are mismatched by >1 month then that's the thing to warn about.

MikeMcQuaid

Thanks @botantony, appreciate the work here. I think there may be a bit of back and forth to get this ready, just as a warning. Nice work so far!

MikeMcQuaid · 2026-01-12T09:29:45Z

Library/Homebrew/diagnostic.rb

      end

+      sig { returns(String) }
+      def mirror_docs_url


probably makes more sense as a constant

MikeMcQuaid · 2026-01-12T09:30:03Z

Library/Homebrew/diagnostic.rb

        return if !Utils::Git.available? || !repository_path.git_repository?

        current_origin = repository_path.origin_url
+        last_commit_time = Time.parse(T.must(repository_path.last_commit_date))


What guarantees last_commit_date will be set?

MikeMcQuaid · 2026-01-12T09:32:00Z

Library/Homebrew/diagnostic.rb

            You can solve this by setting the origin remote:
              git -C "#{repository_path}" remote set-url origin #{Formatter.url(desired_origin)}
          EOS
+        elsif (Time.now - last_commit_time) > Homebrew::API::DEFAULT_API_STALE_SECONDS


Agreed. This could be hardcoded to a month or more.

MikeMcQuaid · 2026-01-12T09:33:00Z

Library/Homebrew/diagnostic.rb

+            HOMEBREW_CORE_DEFAULT_GIT_REMOTE,
+            "https://github.com/Homebrew/homebrew-cask", # There's no `HOMEBREW_CASK_DEFAULT_GIT_REMOTE`


We have another doctor check telling people to untap them unless HOMEBREW_NO_INSTALL_FROM_API or HOMEBREW_DEVELOPER are set so agreed we should match that logic.

MikeMcQuaid · 2026-01-12T09:33:25Z

Library/Homebrew/diagnostic.rb

+              Try to update Homebrew and repositories:
+                brew update
+
+              If it does not fix the problem, you might need to use a mirror:


We should not recommend using mirrors.

We should recommend brew update-reset if brew update is not sufficient.

MikeMcQuaid · 2026-01-12T09:33:51Z

Library/Homebrew/diagnostic.rb

+          cask_tap_migrations.jws.json
+          cask.jws.json
+          formula_tap_migrations.jws.json
+          formula.jws.json


They won't be, no. We should use existing API methods for this rather than hardcoding filenames here. We only really need to check a single file here, not all.

MikeMcQuaid · 2026-01-12T09:35:13Z

Library/Homebrew/diagnostic.rb

+        # These are popular mirrors with known problems
+        bad_mirrors = [
+          %r{^https?://mirrors\.aliyun\.com/homebrew/.+}, # Last update was in May 2025
+        ]
+        problems = []


It's technically also incorrect as while the API mirror is outdated, the brew git mirror is not.

This feels like something we should check instead of some of these other checks.

Ultimately it doesn't matter if Homebrew/brew and Homebrew/homebrew-core are both outdated by the same amount. We should compare the timestamps in both and if they are mismatched by >1 month then that's the thing to warn about.

github-advanced-security bot found potential problems Jan 10, 2026

View reviewed changes

Library/Homebrew/diagnostic.rb Fixed Show fixed Hide fixed

botantony force-pushed the brew-doctor-check-mirrors branch from 0f7c6bd to 9795c77 Compare January 10, 2026 21:07

diagnostic: check outdated mirrors and repositories

12f224d

Signed-off-by: botantony <antonsm21@gmail.com>

botantony force-pushed the brew-doctor-check-mirrors branch from 9795c77 to 12f224d Compare January 10, 2026 21:16

Bo98 reviewed Jan 11, 2026

View reviewed changes

MikeMcQuaid reviewed Jan 12, 2026

View reviewed changes

		HOMEBREW_CORE_DEFAULT_GIT_REMOTE,
		"https://github.com/Homebrew/homebrew-cask", # There's no `HOMEBREW_CASK_DEFAULT_GIT_REMOTE`

Uh oh!

[WIP] diagnostic: check outdated mirrors and repositories #21383

Are you sure you want to change the base?

[WIP] diagnostic: check outdated mirrors and repositories #21383

Conversation

botantony commented Jan 10, 2026

Uh oh!

Uh oh!

Bo98 Jan 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Bo98 Jan 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Bo98 Jan 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MikeMcQuaid left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Bo98 Jan 11, 2026 •

edited

Loading

Bo98 Jan 11, 2026 •

edited

Loading

Bo98 Jan 11, 2026 •

edited

Loading