cask: upgrade auto_updates casks when bundle version is stale

[bevanjkay]

---

• 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 (excluding integration tests) for your changes? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) with your changes locally?

---

• AI was used to generate or assist with generating this PR. Please specify below how you used AI to help you, and what steps you have taken to manually verify the changes.

I used Codex to help plan out and implement the initial version of bundle_version. I have reviewed and tested the functionality, but anticipate that there will be some edge-cases.

---

Outdated Description

This PR introduces an initial implementation of a bundle_version parameter for cask artifacts. In this first iteration, it only applies to app artifacts, which is the primary target for this feature.

The goal is to support metadata-only upgrades when an app has already been updated outside Homebrew, for example by an in-app updater. If a newer cask is available in Homebrew, and the installed app bundle already matches the incoming cask’s version and bundle_version, Homebrew updates its installed cask metadata without fetching or reinstalling the app.

Note that this only applies when the version matches, so brew upgrade <cask> would still run an installation when the installed version is greater than the Homebrew version. A future possible enhancement (out of scope here) could be to handle cases where the installed app is never than the incoming cask version.

I’ve kept this PR scoped to the MVP. For broader adoption, we would also want brew bump and brew bump-cask-pr support to detect and update bundle_version automatically. I intend to work on this as a follow-up, unless there is preference to include it here.

---

Included in this PR;

• Initial bundle_version support for app artifacts
• Metadata-only upgrades when the installed app matches the incoming cask’s version and bundle_version
• Skipping fetch when a metadata-only upgrade will be performed
• brew audit --online functionality to check the bundle_version values against the artifact

Follow-up work:

• bundle_version detection and update support in brew bump and brew bump-cask-pr
• Potential handling for apps already newer than the incoming cask version

This PR introduces a change to the way that we handle upgrades for simple Casks in homebrew-cask, with the qualifiers that they only have a single app artifact, and have auto_updates true. At present these are only ever upgraded with brew upgrade when the --greedy or --greedy-auto-updates flags are passed.

The PR introduces a bundle_version check that looks inside the installed applications info.plist file and compares the version numbers with the incoming latest version from the tap. If the incoming version is detected as being newer than the installed version, then we proceed with the upgrade.

There is a level of naivety involved in the version matching, as there is a lot of inconsistent between how developers set the CFBundleVersion and CFShortBundleVersionString in info.plist versus how we use version in homebrew-cask. This means that we look for a broad range of matches, which may prove to be too loose. In my testing it has seemed to be ok, especially because we still look for an outdated Caskroom file, so we shouldn't ever see repeated upgrades for the same version.

[Copilot]

Pull request overview

Adds initial bundle_version support for cask app artifacts to enable “metadata-only” upgrades when an installed app bundle already matches the incoming cask’s version + bundle_version, avoiding unnecessary downloads/reinstalls. This also extends API serialization/loading and introduces an online audit to validate declared bundle_version values against extracted artifacts.

Changes:

• Add bundle_version option to app artifacts, including API JSON serialization/loading and artifact matching logic.
• Implement metadata-only upgrade path (and skip prefetch/fetch where applicable) when installed bundle version matches.
• Add brew audit --online checks and unit tests covering metadata-only upgrade and bundle version auditing.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
Library/Homebrew/cask/artifact/abstract_artifact.rb	Adds default “metadata-upgrade” capability hooks to artifacts.
Library/Homebrew/cask/artifact/app.rb	Implements bundle_version option + matching against installed Info.plist.
Library/Homebrew/cask/upgrade.rb	Adds metadata-only upgrade flow and fetch filtering for upgrades.
Library/Homebrew/cmd/upgrade.rb	Skips prefetching downloads for casks eligible for metadata-only upgrades.
Library/Homebrew/cask/installer.rb	Adds write_metadata helper used by metadata-only upgrades.
Library/Homebrew/cask/audit.rb	Adds online audit for declared bundle_version vs extracted app bundle version.
Library/Homebrew/test/cask/upgrade_spec.rb	Tests metadata-only upgrade behavior and prefetch skipping.
Library/Homebrew/test/cask/audit_spec.rb	Tests online audit behavior for bundle version matching/mismatch.
Library/Homebrew/test/cask/artifact/app_spec.rb	Tests bundle_version parsing/storage and matching logic on App artifacts.
Library/Homebrew/test/cask/cask_loader/from_api_loader_spec.rb	Tests loading bundle_version from JSON and internal JSON API artifacts.
Library/Homebrew/test/api/cask/cask_struct_generator_spec.rb	Updates API artifact processing expectations for bundle_version.
Library/Homebrew/test/api/cask_spec.rb	Updates expected cask source checksum due to fixture changes.
Library/Homebrew/test/support/fixtures/cask/Casks/everything.rb	Adds bundle_version to fixture cask’s app stanza.
Library/Homebrew/test/support/fixtures/cask/everything.json	Updates API fixture artifacts to include bundle_version and checksum.
Library/Homebrew/test/support/fixtures/cask/everything.internal.json	Updates internal API fixture artifacts to include bundle_version and checksum.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bevanjkay]

I think we may also need to add an audit to not allow the use of bundle_version when the download url is unversioned, because the download of a specific version is not guaranteed in that case.

[MikeMcQuaid]

Thanks for the PR @bevanjkay but I think this needs a different approach.

I think we may also need to add an audit to not allow the use of bundle_version when the download url is unversioned, because the download of a specific version is not guaranteed in that case.

This is revealing because I think, unfortunately, it makes the DSL pointless in that case. The "problem to be solved" also applies when the download URL is unversioned, unless I've missed something.

Basically: we want a way to have brew upgrade --greedy be the default but avoid upgrading things where the bundle version indicates it's already up-to-date. We may still want to update e.g. the caskroom version in that case so we don't keep repeatedly needing to check the same data.

We have a bundle_version attribute in our existing cask JSON API that sniffs this bundle version. That's what's already been used by other tools to do this sort of comparison.

Hope that helps, let me know what you think as I may be totally wrong about some of the above!

[bevanjkay]

This is revealing because I think, unfortunately, it makes the DSL pointless in that case. The "problem to be solved" also applies when the download URL is unversioned, unless I've missed something.

Unversioned downloads are always a worse UX because there's no guarantee the version in the cask will match brew fetch. So perhaps the issue I referred to is not actually any worse than the status quo. If the incoming cask metadata is stale with the actual download contents we just have to naively trust it anyway. Unless we handle a bundle_version comparison at upgrade time (after fetching).

[MikeMcQuaid]

Unless we handle a bundle_version comparison at upgrade time (after fetching).

This seems better than nothing if we can 👍🏻

[bevanjkay]

Thanks for the back and forth here @MikeMcQuaid - I think it's going to take some time to land exactly what the best way forward is here, as I'm discovering some different permutations as they arise. But I think it's better to that with some logic out in the open because I think the discussion is useful, if that's ok?

---

This round removes the dsl updates, and automatically checks the currently installed application's info.plist and compares the values with the "latest" version in the tap. If they match it runs a "metadata_only" upgrade. This is gated to only occur within Casks that have a single app stanza, because there are no additional moving parts. The discussion below provides some cases where increasing this radius requires significant extra logic.

---

One thought that has arisen is that this isn't actually the primary issue. it's nice to know with brew info what the latest version is, and to keep the metadata in line with this, but I may be focussing too much on the Caskroom here.

Your comment in the earlier thread;

"do we have a good reason to believe all users need this upgrade".

made me think that maybe some detection around this idea is a better first goal, and then syncing the Caskroom metadata is secondary.

A new goal may be to find a may to detect and develop the criteria for when brew upgrade should occur by default on a Cask. With maybe three distinct pathways;

1. A full upgrade is necessary
2. A metadata-only upgrade will suffice
3. A --greedy flag is required (some instances are impossible to detect without running the whole upgrade process and exiting at the end with a no-op)

In full, to decide between 1 & 2 is not as simple as comparing bundle_version because we also need to compare any other changes that may have occurred that require Homebrew to take action.

[MikeMcQuaid]

Thanks for the back and forth here @MikeMcQuaid - I think it's going to take some time to land exactly what the best way forward is here, as I'm discovering some different permutations as they arise. But I think it's better to that with some logic out in the open because I think the discussion is useful, if that's ok?

Yeh, of course: much appreciated!

If they match it runs a "metadata_only" upgrade.

What does this look like, output (and speed) wise compared to the "normal" upgrade?

In full, to decide between 1 & 2 is not as simple as comparing bundle_version because we also need to compare any other changes that may have occurred that require Homebrew to take action.

I guess my thinking is: this change is not so much about deciding whether to upgrade or not but instead having more cases of casks not currently upgraded today without --greedy that we can upgrade without --greedy without doing effective just a full reinstall of content already there.

Even if this PR ends up only enabling this for a single cask that's updated relatively often: I think that'll be a net positive and good foundation to build off.

Hope that helps!

Thanks again @bevanjkay, cracking work.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

Library/Homebrew/cmd/upgrade.rb:482

• prefetch_outdated_casks! now calls Install.show_combined_fetch_downloads_heading twice (lines 475 and 481), which will print duplicate “Fetching/Downloading…” headings during brew upgrade prefetch. It also does prefetch_names&.replace(cask_names) twice; please keep a single, correctly placed update + heading call.

        cask_names = outdated_casks.map(&:full_name)
        prefetch_names&.replace(cask_names)
        Install.show_combined_fetch_downloads_heading(cask_names:) if show_downloads_heading
        Install.enqueue_cask_installers(fetchable_cask_installers)
        prefetch_names&.replace(cask_names)
        prefetch_upgrades&.replace(
          outdated_casks.map { |cask| "#{cask.full_name} #{cask.installed_version} -> #{cask.version}" },
        )
        Install.show_combined_fetch_downloads_heading(cask_names:) if show_downloads_heading

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bevanjkay]

Converting to draft, because I need to clean some things up here.

Quite a diversion from the original PR, but I think it's a productive outcome.

Currently, casks marked as auto_updates true are only upgrade when --greedy or --greedy-auto-updates is passed to brew upgrade. This PR adds some checks to allow these upgrades to run with a general brew upgrade when certain conditions are met.

For an auto_updates Cask, this PR now updates the flow to now check the applications bundle_version when there is a newer version available in the Tap, than what is currently in the Caskroom. If the application's bundle_version is older than the "latest" version in the tap, then we run the upgrade, if not we don't do anything. These casks would still be upgrade with the --greedy or --greedy-auto-updates flag, as I would suggest it implies the user doesn't want Homebrew to check the current application status.

---

For now this is still applied only to Cask with a single app stanza, as we ensure the bundle_version check occurs in the right place. Even so, this change will affect 1,500 casks.

[MikeMcQuaid]

This PR adds some checks to allow these upgrades to run with a general brew upgrade when certain conditions are met.
Even so, this change will affect 1,500 casks.

👏🏻

[bevanjkay]

I have been daily driving this branch since my last push and haven't noticed anything out of the ordinary, other than more casks being upgraded without having to pass --greedy-auto-updates.

[MikeMcQuaid]

Happy to merge when you are, great work here!

[bevanjkay]

Let's merge now, it should give a few days before it lands in a release to hopefully pick up anything that needs adjustment.

[paschun]

I don't think this info.plist inspection is working for several of my apps. Homebrew today tries to update 15 casks. Some of these I haven't opened in a while, so their internal auto-updaters haven't run, and they aren't up to date. But some of them such as signal update themselves every day, but homebrew is still trying to upgrade signal. I just checked inside the signal app, it is version 8.6.0, which is latest.

Aside from the info.plist version inspection issue, I personally prefer the old behavior of letting the app's auto updater handle updates. Because the homebrew process for cask upgrades is iirc to uninstall the current version, and install a new version. Which for some apps, can wipe out it's state/appdata .

[bevanjkay]

This PR #21974 should resolve thesignal cask from being detected too greedily. The challenge there is that the signal application bundle has "1" set as the Bundle Version which fails in the comparison with "8.6.1".

Aside from the info.plist version inspection issue, I personally prefer the old behavior of letting the app's auto updater handle updates. Because the homebrew process for cask upgrades is iirc to uninstall the current version, and install a new version. Which for some apps, can wipe out it's state/appdata .

I see this as more of an unfortunate side-effect of the change rather than an actual causation. In saying that, if an application you use has it's state/appdata removed during a brew upgrade process then an issue should be filed in the homebrew-cask repository to resolve this, as this is not expected behaviour.

[paschun]

I see this as more of an unfortunate side-effect of the change rather than an actual causation. In saying that, if an application you use has it's state/appdata removed during a brew upgrade process then an issue should be filed in the homebrew-cask repository to resolve this, as this is not expected behaviour.

Thank you for the quick response. I didn't know that was unintended behavior. Thanks for clarifying.

I guess I will continue to mention my issues here..
Another issue i'm having is with the disabled casks. I installed the mudlet cask before it was disabled. It is set to auto_updates. Now, every time I run brew upgrade, it throws an error. So I can't run brew upgrade without uninstalling the cask.

[dkav]

Is there a way to discern which outdated auto-update casks will be upgraded by brew upgrade as currently implemented?

For my casks, when I run brew upgrade --cask, it only updates a subset of what is listed with bw outdated --cask --greedy-auto-updates. If I run bw outdated --cask, no cask is listed. There doesn't appear to be a way to know which casks that are set to auto-update will be upgraded without running brew upgrade.

Homebrew 5.1.11-77-gd430e68

[bevanjkay]

@dkav Thanks for reporting, #22272 should fix this.