script/homebrew/README.md

Homebrew Upgrade Manager

brew-upgrade-manager.sh 是一个 macOS Homebrew 升级脚本，用来按固定流程更新仓库、检查环境、升级命令行工具和 GUI 应用，并清理旧缓存。

功能

• 执行 brew update -v 更新 Homebrew 仓库。
• 执行 brew doctor 做健康检查，发现问题时给出警告但不中断后续流程。
• 自动检查并安装 buo/cask-upgrade，用于提供 brew cu。
• 使用 brew upgrade --formula 升级命令行 Formula。
• 使用 brew cu -yaq 升级 Cask GUI 应用。
• 使用 Python PTY 包装 brew cu，用于处理交互输入转发和终端尺寸问题。
• 执行 brew cleanup --prune=all 清理旧版本与缓存。

依赖

• macOS
• Homebrew
• Bash
• Python 3
• 可访问 Homebrew tap 的网络环境

可先检查：

brew --version
python3 --version

使用方法

进入目录并赋予执行权限：

cd homebrew
chmod +x brew-upgrade-manager.sh

运行：

./brew-upgrade-manager.sh

默认会动态读取当前终端宽度；运行过程中缩放窗口时，brew cu 的 PTY 尺寸也会跟随更新。如果遇到非交互环境或某些表格渲染异常，可以指定固定终端宽度：

./brew-upgrade-manager.sh --width 130
./brew-upgrade-manager.sh --width=130

也可以通过环境变量指定：

HB_TERMINAL_WIDTH=130 ./brew-upgrade-manager.sh

优先级为：命令行 --width 高于 HB_TERMINAL_WIDTH。两者都不设置时使用动态终端宽度。

sudo 认证

脚本不会保存、传递或自动注入 sudo 密码。如果你的 brew cu 流程会触发 sudo，建议在运行脚本前先刷新 sudo 凭据：

sudo -v
./brew-upgrade-manager.sh

如果 sudo 凭据过期，脚本内的 PTY 逻辑只会把你的键盘输入转发给子进程，不会嗅探 Password: 提示，也不会替你填写密码。

执行流程

1. 打印分隔线并更新 Homebrew 仓库。
2. 执行 brew doctor。
3. 检查 buo/cask-upgrade tap。
4. 升级 Formula。
5. 升级 Cask。
6. 清理 Homebrew 缓存。

常见问题

brew cu 不存在

脚本会自动执行：

brew tap buo/cask-upgrade

如果失败，通常是网络、Homebrew tap 或权限问题。

表格渲染或 Ruby 报终端宽度错误

默认会跟随终端窗口变化；如果某些环境无法正确报告窗口尺寸，可以使用固定宽度运行：

./brew-upgrade-manager.sh --width 130

sudo 卡住

先在交互终端运行 sudo -v，确认 sudo 凭据有效后再执行脚本。非交互环境中请避免依赖脚本内输入密码。

注意事项

• 脚本启用了 set -e 和 set -o pipefail，关键命令失败会终止流程。
• 升级 GUI 应用可能关闭或替换已安装应用，建议在重要工作保存后执行。
• 如果你使用公司设备或受管 macOS，先确认 Homebrew、Cask 和 sudo 策略是否允许自动升级。