BrewUI

# 🧑‍💻 BrewUI

<img width="1476" height="975" alt="BrewUI user interface" src="docs/images/brewui.png" />

Homebrew's official macOS GUI: making package management approachable for users who prefer graphical interfaces over Terminal, while maintaining complete transparency about underlying Homebrew operations.

## 💡 Motivation

Enable CLI-averse users to safely discover, install, update and manage Homebrew packages through a native SwiftUI interface that never hides what Homebrew is doing.

## 📲 Tech

- **Swift** with strict concurrency · **SwiftUI** · **Swift Package Manager**
- Toolchain and macOS requirements: [Package.swift](Package.swift), [.swift-version](.swift-version) and [Xcode project](Homebrew.xcodeproj/project.pbxproj)
- Data from the `brew` CLI and the [Homebrew JSON API](https://formulae.brew.sh/docs/api/)

## 📦 Installation

```bash
brew install --cask homebrew-app
```

## Homebrew configuration

Put Homebrew options in `brew.env` and relaunch BrewUI after changing them. Shell aliases and
exported variables do not configure the app. See [Homebrew configuration](ARCHITECTURE.md#homebrew-configuration).

## 🛠️ Development

After cloning:

```bash
./scripts/bootstrap
```

This installs Mint from `Brewfile`, runs `mint bootstrap` to build the SwiftFormat and SwiftLint versions pinned in `Mintfile`, enables repository git hooks and resolves Swift package dependencies for `Homebrew.xcodeproj`.

After bootstrap, commits automatically run checks on staged Swift files:

1. `mint run swiftformat`
2. `mint run swiftlint` (with `--fix`, then strict validation)

The hook also runs BrewUILint over the production tree. If unresolved lint violations remain, the commit is blocked and the hook prints the failures so you can fix and re-commit.

See [development setup](AGENTS.md#development-setup) for signing configuration, [conventions and testing](AGENTS.md#coding-conventions)
for contributor guidance and [architecture](ARCHITECTURE.md) for system design.

## 🌍 Translations

Translations are community-sourced and a partial one is welcome: any string without a translation
falls back to English. Copy lives in one `Localizable.xcstrings` catalog per UI target, `Homebrew/`
for the window, sidebar and menus, and `Resources/` in `BrewUIComponents` and each `BrewFeature*`
package. Edit a catalog in Xcode. See [localisation](AGENTS.md#localisation) for the reasoning
behind the steps below.

### Adding a language

1. Open `Homebrew/Localizable.xcstrings`, press `+`, pick the language and translate at least one
   string there. macOS only lists a language in the per-app picker under *Applications* in System
   Settings when the app bundle ships it, so a language that exists only in a package catalog never
   loads and `scripts/localize verify` fails. Adding it also records the language in `knownRegions`
   in `Homebrew.xcodeproj`; commit that.
2. Add the language to each package catalog you want to translate and do as much of it as you like.
3. Never leave a