homebrew

适用于 macOS 的 Homebrew 包管理器。搜索、安装、管理包和桶并对其进行故障排除。

## 概述（中文）

适用于 macOS 的 Homebrew 包管理器。搜索、安装、管理包和桶并对其进行故障排除。

## 原文

# Homebrew Package Manager

Complete Homebrew command reference and usage guide for installing, managing, and troubleshooting macOS packages.

## When to Use
- Installing packages or applications (`brew install X`)
- Searching for available packages (`brew search X`)
- Updating and upgrading existing packages
- Checking package information and dependencies
- Troubleshooting installation issues
- Managing installed packages

## Command Reference

### Package Search & Information

#### `brew search TEXT|/REGEX/`
**Usage:** Find packages by name or regex pattern
**When to use:** When user asks to find or search for a package
**Examples:**
```bash
brew search python
brew search /^node/
```

#### `brew info [FORMULA|CASK...]`
**Usage:** Display detailed information about one or more packages
**When to use:** Before installing to see dependencies, options, and details
**Examples:**
```bash
brew info python
brew info chrome google-chrome
```

### Installation & Upgrades

#### `brew install FORMULA|CASK...`
**Usage:** Install one or more packages or applications
**When to use:** When user says "install X" or "use brew to install X"
**Notes:**
- FORMULA = command-line tools (installed to /usr/local/bin)
- CASK = GUI applications (installed to /Applications)
- Can install multiple at once: `brew install git python nodejs`
**Examples:**
```bash
brew install python
brew install google-chrome  # installs as cask
brew install git python nodejs
```

#### `brew update`
**Usage:** Fetch the newest version of Homebrew and all formulae
**When to use:** When brew seems outdated or before major operations
**Notes:** Doesn't upgrade packages, just updates the package list
**Examples:**
```bash
brew update
```

#### `brew upgrade [FORMULA|CASK...]`
**Usage:** Upgrade installed packages or specific packages
**When to use:** When user wants to update to newer versions
**Notes:**
- Without args: upgrades all outdated packages
- With args: upgrades only specified packages
**Examples:**
```bash
brew upgrade              # upgrade all outdated packages
brew upgrade python       # upgrade just python
brew upgrade python git   # upgrade multiple
```

### Package Management

#### `brew uninstall FORMULA|CASK...`
**Usage:** Remove installed packages
**When to use:** When user wants to remove/delete a package
**Notes:** Can uninstall multiple at once
**Examples:**
```bash
brew uninstall python
brew uninstall google-chrome
```

#### `brew list [FORMULA|CASK...]`
**Usage:** List installed packages or files from specific packages
**When to use:** When user wants to see what's installed or what files a package contains
**Examples:**
```bash
brew list                 # show all installed packages
brew list python          # show files installed by python
```

### Configuration & Troubleshooting

#### `brew config`
**Usage:** Display Homebrew configuration and environment info
**When to use:** Debugging installation issues or checking system setup
**Shows:**
- Installation path
- Xcode location
- Git version
- CPU architecture
**Examples:**
```bash
brew config
```

#### `brew doctor`
**Usage:** Check for potential problems with Homebrew installation
**When to use:** When experiencing installation issues or errors
**Returns:** Warnings and suggestions for fixing issues
**Examples:**
```bash
brew doctor
```

#### `brew install --verbose --debug FORMULA|CASK`
**Usage:** Install with verbose output and debug information
**When to use:** When standard install fails and you need detailed error messages
**Examples:**
```bash
brew install --verbose --debug python
```

### Advanced Usage

#### `brew create URL [--no-fetch]`
**Usage:** Create a new formula from source code
**When to use:** Creating custom packages (advanced users)
**Options:**
- `--no-fetch` = don't download source immediately
**Examples:**
```bash
brew create https://example.com/package.tar.gz
```

#### `brew edit [FORMULA|CASK...]`
**Usage:** Edit formula or cask definition
**When to use:** Customizing package installation (advanced users)
**Examples:**
```bash
brew edit python
```

#### `brew commands`
**Usage:** Show all available brew commands
**When to use:** Learning about additional brew features
**Examples:**
```bash
brew commands
```

#### `brew help [COMMAND]`
**Usage:** Get help for specific command
**When to use:** Need detailed help for a specific command
**Examples:**
```bash
brew help install
brew help upgrade
```

## Quick Reference

| Task | Command |
|------|---------|
| Search for package | `brew search TEXT` |
| Get package info | `brew info FORMULA` |
| Install package | `brew install FORMULA` |
| Install app | `brew install CASK` |
| Update package list | `brew update` |
| Upgrade all packages | `brew upgrade` |
| Upgrade specific package | `brew upgrade FORMULA` |
| Remove package | `brew uninstall FORMULA` |
| List installed | `brew list` |
| Check config | `brew config` |
| Troubleshoot | `brew doctor` |

## Common Workflows

### Installing a New Package
1. Search: `brew search python`
2. Get info: `brew info python@3.11`
3. Install: `brew install python@3.11`

### Troubleshooting Installation
1. Check config: `brew config`
2. Run doctor: `brew doctor`
3. Retry with debug: `brew install --verbose --debug FORMULA`

### Maintaining Homebrew
1. Update: `brew update`
2. Check what's outdated: `brew upgrade` (shows what would upgrade)
3. Upgrade all: `brew upgrade`

## Key Concepts

**FORMULA:** Command-line tools and libraries (e.g., python, git, node)
**CASK:** GUI applications (e.g., google-chrome, vscode, slack)
**TAP:** Third-party formula repositories (e.g., `brew tap homebrew/cask-versions`)

## Notes
- All brew commands require Homebrew to be installed
- Xcode Command Line Tools are required for building from source
- Some packages may prompt for sudo password
- Different packages have different installation times
- Package names are case-insensitive but shown lowercase by convention

## Resources
- Official docs: https://docs.brew.sh
- Formula documentation: https://github.com/Homebrew/homebrew-core
- Cask documentation: https://github.com/Homebrew/homebrew-cask

---

## 中文说明

# Homebrew 包管理器

完整的 Homebrew 命令参考与使用指南，用于安装、管理 macOS 包以及排查相关问题。

## 何时使用
- 安装包或应用程序（`brew install X`）
- 搜索可用的包（`brew search X`）
- 更新和升级已安装的包
- 查看包信息和依赖关系
- 排查安装问题
- 管理已安装的包

## 命令参考

### 包搜索与信息

#### `brew search TEXT|/REGEX/`
**用途：** 按名称或正则表达式模式查找包
**何时使用：** 当用户要求查找或搜索某个包时
**示例：**
```bash
brew search python
brew search /^node/
```

#### `brew info [FORMULA|CASK...]`
**用途：** 显示一个或多个包的详细信息
**何时使用：** 在安装前查看依赖项、选项和详细信息
**示例：**
```bash
brew info python
brew info chrome google-chrome
```

### 安装与升级

#### `brew install FORMULA|CASK...`
**用途：** 安装一个或多个包或应用程序
**何时使用：** 当用户说"install X"或"use brew to install X"时
**说明：**
- FORMULA = 命令行工具（安装到 /usr/local/bin）
- CASK = 图形界面应用程序（安装到 /Applications）
- 可以一次安装多个：`brew install git python nodejs`
**示例：**
```bash
brew install python
brew install google-chrome  # installs as cask
brew install git python nodejs
```

#### `brew update`
**用途：** 获取最新版本的 Homebrew 和所有 formula
**何时使用：** 当 brew 看起来过时或在执行重要操作之前
**说明：** 不升级包，仅更新包列表
**示例：**
```bash
brew update
```

#### `brew upgrade [FORMULA|CASK...]`
**用途：** 升级已安装的包或指定的包
**何时使用：** 当用户希望更新到较新版本时
**说明：**
- 不带参数：升级所有过时的包
- 带参数：仅升级指定的包
**示例：**
```bash
brew upgrade              # upgrade all outdated packages
brew upgrade python       # upgrade just python
brew upgrade python git   # upgrade multiple
```

### 包管理

#### `brew uninstall FORMULA|CASK...`
**用途：** 移除已安装的包
**何时使用：** 当用户希望移除/删除某个包时
**说明：** 可以一次卸载多个
**示例：**
```bash
brew uninstall python
brew uninstall google-chrome
```

#### `brew list [FORMULA|CASK...]`
**用途：** 列出已安装的包或特定包包含的文件
**何时使用：** 当用户希望查看已安装内容或某个包包含哪些文件时
**示例：**
```bash
brew list                 # show all installed packages
brew list python          # show files installed by python
```

### 配置与故障排除

#### `brew config`
**用途：** 显示 Homebrew 的配置和环境信息
**何时使用：** 调试安装问题或检查系统设置
**显示内容：**