Allow adopting or replacing manually installed apps in the GUI #276

Before submitting section

• I have searched the issues and pull requests for duplicates.
• I am proposing a specific improvement to Homebrew App with a use case and a clear outcome.

Problem and use case section

The official Homebrew GUI app only provides an Install button for a cask, equivalent to:

brew install --cask iterm2

If the application was previously installed manually, installation fails:

==> Purging files for version 3.7.6 of Cask iterm2
Error: iterm2: It seems there is already an App at '/Applications/iTerm.app'.

The GUI does not provide an option to resolve this conflict. Users who want Homebrew to manage a manually installed application must switch to the command line.

Steps to reproduce:

1. Manually install iTerm2 in /Applications.
2. Open the official Homebrew GUI app.
3. Find iTerm2 and click Install.
4. Installation fails because /Applications/iTerm.app already exists.

Proposed behaviour section

When an existing application causes an installation conflict, show a dialog offering:

• Adopt existing app: run the equivalent of brew install --cask --adopt iterm2, when the existing application matches the cask.
• Replace existing app: run the equivalent of brew install --cask --force iterm2, with confirmation before replacing the application.
• Cancel: leave the existing application unchanged.

If adoption fails because the existing application differs from the cask, explain the reason and offer the replacement option.

This would allow users to bring manually installed applications under Homebrew management entirely through the GUI.

Alternatives considered section

Run brew install --cask --force iterm2 manually. This resolves the conflict but requires leaving the GUI and using the terminal.

Move the existing application out of /Applications, then retry installation through the GUI. This requires additional manual steps and may be confusing for users unfamiliar with how Homebrew manages applications.

macOS and Homebrew context section

• Interface: official Homebrew GUI app.
• Affected cask: iterm2.
• Cask version shown in the installation output: 3.7.6.
• Existing application path: /Applications/iTerm.app.
• The existing application was installed manually, outside Homebrew.
• The conflict occurs when clicking Install in the GUI.