charmbracelet/gum
GitHub: charmbracelet/gum
一款让 Shell 脚本变得交互式且美观的命令行工具，提供选择、确认、输入、过滤等多种即用型 UI 组件。
Stars: 23002 | Forks: 467
# Gum
上面的示例运行自一个单独的 Shell 脚本 ([源码](./examples/demo.sh))。
## 教程
Gum 提供了高度可配置、即用型的实用工具，帮助你只需几行代码就能编写出有用的 Shell 脚本和 dotfiles 别名。
让我们构建一个简单的脚本，帮助你为你的 dotfiles 编写 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)。
使用 gum choose 询问提交类型：
```
gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert"
```
提示输入这些更改的范围：
```
gum input --placeholder "scope"
```
提示输入更改的摘要和描述：
```
gum input --value "$TYPE$SCOPE: " --placeholder "Summary of this change"
gum write --placeholder "Details of this change"
```
提交前确认：
```
gum confirm "Commit changes?" && git commit -m "$SUMMARY" -m "$DESCRIPTION"
```
查看 [完整示例](https://github.com/charmbracelet/gum/blob/main/examples/commit.sh) 以了解如何将这些命令组合在一个脚本中。
## 安装
使用包管理器：
```
# macOS 或 Linux
brew install gum
# Arch Linux (btw)
pacman -S gum
# Fedora 或 EPEL 10
dnf install gum
# Nix
nix-env -iA nixpkgs.gum
# Flox
flox install gum
# Windows (通过 WinGet 或 Scoop)
winget install charmbracelet.gum
scoop install charm-gum
```
或者下载它：
- [软件包][releases] 提供 Debian、RPM 和 Alpine 格式
- [二进制文件][releases] 适用于 Linux、macOS、Windows、FreeBSD、OpenBSD 和 NetBSD
或者直接用 `go` 安装：
```
go install github.com/charmbracelet/gum@latest
```
## 命令
- [`choose`](#choose): 从选项列表中选择一个选项
- [`confirm`](#confirm): 请求用户确认操作
- [`file`](#file): 从文件夹中选择一个文件
- [`filter`](#filter): 从列表中筛选项目
- [`format`](#format): 使用模板格式化字符串
- [`input`](#input): 提示输入
- [`join`](#join): 垂直或水平连接文本
- [`pager`](#pager): 滚动浏览文件
- [`spin`](#spin): 在运行命令时显示加载动画
- [`style`](#style): 为文本应用颜色、边框、间距
- [`table`](#table): 渲染数据表格
- [`write`](#write): 提示输入长文本
- [`log`](#log): 输出日志信息
## 自定义
你可以通过 `--flags` 和 `$ENVIRONMENT_VARIABLES` 自定义 `gum` 的选项和样式。
查看 `gum --help` 以获取每个命令的完整自定义和配置选项视图。
使用 `--flags` 自定义：
```
gum input --cursor.foreground "#FF0" \
--prompt.foreground "#0FF" \
--placeholder "What's up?" \
--prompt "* " \
--width 80 \
--value "Not much, hby?"
```
使用 `ENVIRONMENT_VARIABLES` 自定义：
```
export GUM_INPUT_CURSOR_FOREGROUND="#FF0"
export GUM_INPUT_PROMPT_FOREGROUND="#0FF"
export GUM_INPUT_PLACEHOLDER="What's up?"
export GUM_INPUT_PROMPT="* "
export GUM_INPUT_WIDTH=80
# --flags 可以覆盖通过环境设置的值
gum input
```
## Input
使用简单的命令提示输入。
```
gum input > answer.txt
gum input --password > password.txt
```
## Write
提示输入多行文本（按 `ctrl+d` 完成文本输入）。
```
gum write > story.txt
```
## Filter
使用模糊匹配筛选值列表：
```
echo Strawberry >> flavors.txt
echo Banana >> flavors.txt
echo Cherry >> flavors.txt
gum filter < flavors.txt > selection.txt
```
使用 `--limit` 或 `--no-limit` 标志选择多个选项。使用 `tab` 或 `ctrl+space` 选择，`enter` 确认。
```
cat flavors.txt | gum filter --limit 2
cat flavors.txt | gum filter --no-limit
```
## Choose
从选项列表中选择一个选项。
```
echo "Pick a card, any card..."
CARD=$(gum choose --height 15 {{A,K,Q,J},{10..2}}" "{♠,♥,♣,♦})
echo "Was your card the $CARD?"
```
你也可以使用 `--limit` 或 `--no-limit` 标志选择多个项目，这决定了可以选择的最大项目数。
```
cat songs.txt | gum choose --limit 5
cat foods.txt | gum choose --no-limit --header "Grocery Shopping"
```
## Confirm
确认是否执行操作。根据选择以退出代码 `0`（肯定）或 `1`（否定）退出。
```
gum confirm && rm file.txt || echo "File not removed"
```
## File
提示用户从文件树中选择一个文件。
```
$EDITOR $(gum file $HOME)
```
## Pager
滚动浏览带有行号和完全可自定义视口的长文档。
```
gum pager < README.md
```
## Spin
在运行脚本或命令时显示加载动画。加载动画将在给定命令退出后自动停止。
要查看或管道传输命令的输出，请使用 `--show-output` 标志。
```
gum spin --spinner dot --title "Buying Bubble Gum..." -- sleep 5
```
可用的加载动画类型包括：`line`、`dot`、`minidot`、`jump`、`pulse`、`points`、`globe`、`moon`、`monkey`、`meter`、`hamburger`。
## Table
从表格数据中选择一行。
```
gum table < flavors.csv | cut -d ',' -f 1
```
## Style
使用单个命令以任意布局漂亮地打印任何字符串。
```
gum style \
--foreground 212 --border-foreground 212 --border double \
--align center --width 50 --margin "1 2" --padding "2 4" \
'Bubble Gum (1¢)' 'So sweet and so fresh!'
```
## Join
垂直或水平组合文本。将此命令与 `gum style` 配合使用以构建布局和美化输出。
提示：在 `join` 命令中将 `gum style` 的输出作为参数使用时，请始终将其用引号括起来，以保留换行符 (`\n`)。
```
I=$(gum style --padding "1 5" --border double --border-foreground 212 "I")
LOVE=$(gum style --padding "1 4" --border double --border-foreground 57 "LOVE")
BUBBLE=$(gum style --padding "1 8" --border double --border-foreground 255 "Bubble")
GUM=$(gum style --padding "1 5" --border double --border-foreground 240 "Gum")
I_LOVE=$(gum join "$I" "$LOVE")
BUBBLE_GUM=$(gum join "$BUBBLE" "$GUM")
gum join --align center --vertical "$I_LOVE" "$BUBBLE_GUM"
```
## Format
`format` 处理并格式化文本正文。`gum format` 可以解析 Markdown、模板字符串和命名表情符号。
```
# Format 一些 markdown
gum format -- "# Gum Formats" "- Markdown" "- Code" "- Template" "- Emoji"
echo "# Gum Formats\n- Markdown\n- Code\n- Template\n- Emoji" | gum format
# Syntax highlight 一些代码
cat main.go | gum format -t code
# 使用 templates 以任何方式渲染文本
echo '{{ Bold "Tasty" }} {{ Italic "Bubble" }} {{ Color "99" "0" " Gum " }}' \
| gum format -t template
# 显示您最喜欢的 emojis！
echo 'I :heart: Bubble Gum :candy:' | gum format -t emoji
```
有关模板助手的更多信息，请参阅 [Termenv 文档](https://github.com/muesli/termenv#template-helpers)。有关命名表情符号的完整列表，请参阅 [GitHub API](https://api.github.com/emojis)。
## Log
`log` 使用 [`charmbracelet/log`](https://github.com/charmbracelet/log) 库将消息以不同级别和样式记录到终端。
```
# Log 一些 debug 信息。
gum log --structured --level debug "Creating file..." name file.txt
# DEBUG 无法创建文件。name=temp.txt
# Log 一些 error。
gum log --structured --level error "Unable to create file." name file.txt
# ERROR 无法创建文件。name=temp.txt
# 包含 timestamp。
gum log --time rfc822 --level error "Unable to create file."
```
有关可接受的 `--time` 格式，请参阅 Go [`time` package](https://pkg.go.dev/time#pkg-constants)。
有关更多用法，请参阅 [`charmbracelet/log`](https://github.com/charmbracelet/log)。
## 示例
如何在日常工作中使用 `gum`：
请参阅 [examples](./examples/) 目录以获取更多真实用例。
- 编写提交信息：
```
git commit -m "$(gum input --width 50 --placeholder "Summary of changes")" \
-m "$(gum write --width 80 --placeholder "Details of changes")"
```
- 在你的 `$EDITOR` 中打开文件
```
$EDITOR $(gum filter)
```
- 连接到 `tmux` 会话
```
SESSION=$(tmux list-sessions -F \#S | gum filter --placeholder "Pick session...")
tmux switch-client -t "$SESSION" || tmux attach -t "$SESSION"
```
- 从 `git` 历史中选择提交哈希
```
git log --oneline | gum filter | cut -d' ' -f1 # | copy
```
- 简易 [`skate`](https://github.com/charmbracelet/skate) 密码选择器。
```
skate list -k | gum filter | xargs skate get
```
- 卸载软件包
```
brew list | gum choose --no-limit | xargs brew uninstall
```
- 清理 `git` 分支
```
git branch | cut -c 3- | gum choose --no-limit | xargs git branch -D
```
- 使用 [`gh`](https://cli.github.com/) 检出 GitHub Pull Requests
```
gh pr list | cut -f1,2 | gum choose | cut -f1 | xargs gh pr checkout
```
- 从 Shell 历史复制命令
```
gum filter < $HISTFILE --height 20
```
- `sudo` 替代品
```
alias please="gum input --password | sudo -nS"
```
## 贡献
请参阅 [贡献指南][contribute]。
## 反馈
我们很乐意听到您对这个项目的想法。欢迎给我们留言！
- [Twitter](https://twitter.com/charmcli)
- [The Fediverse](https://mastodon.social/@charmcli)
- [Discord](https://charm.sh/chat)
## 许可证
[MIT](https://github.com/charmbracelet/gum/raw/main/LICENSE)
[Charm](https://charm.sh) 的一部分。
Charm热爱开源 • Charm loves open source
上面的示例运行自一个单独的 Shell 脚本 ([源码](./examples/demo.sh))。
## 教程
Gum 提供了高度可配置、即用型的实用工具，帮助你只需几行代码就能编写出有用的 Shell 脚本和 dotfiles 别名。
让我们构建一个简单的脚本，帮助你为你的 dotfiles 编写 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)。
使用 gum choose 询问提交类型：
```
gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert"
```
提示输入这些更改的范围：
```
gum input --placeholder "scope"
```
提示输入更改的摘要和描述：
```
gum input --value "$TYPE$SCOPE: " --placeholder "Summary of this change"
gum write --placeholder "Details of this change"
```
提交前确认：
```
gum confirm "Commit changes?" && git commit -m "$SUMMARY" -m "$DESCRIPTION"
```
查看 [完整示例](https://github.com/charmbracelet/gum/blob/main/examples/commit.sh) 以了解如何将这些命令组合在一个脚本中。
## 安装
使用包管理器：
```
# macOS 或 Linux
brew install gum
# Arch Linux (btw)
pacman -S gum
# Fedora 或 EPEL 10
dnf install gum
# Nix
nix-env -iA nixpkgs.gum
# Flox
flox install gum
# Windows (通过 WinGet 或 Scoop)
winget install charmbracelet.gum
scoop install charm-gum
```
Debian/Ubuntu
``` sudo mkdir -p /etc/apt/keyrings curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list sudo apt update && sudo apt install gum ```Fedora/RHEL/OpenSuse
``` echo '[charm] name=Charm baseurl=https://repo.charm.sh/yum/ enabled=1 gpgcheck=1 gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo sudo rpm --import https://repo.charm.sh/yum/gpg.key # yum sudo yum install gum # zypper sudo zypper refresh sudo zypper install gum ```FreeBSD
``` # packages sudo pkg install gum # ports cd /usr/ports/devel/gum && sudo make install clean ```
## Input
使用简单的命令提示输入。
```
gum input > answer.txt
gum input --password > password.txt
```
## Write
提示输入多行文本（按 `ctrl+d` 完成文本输入）。
```
gum write > story.txt
```
## Filter
使用模糊匹配筛选值列表：
```
echo Strawberry >> flavors.txt
echo Banana >> flavors.txt
echo Cherry >> flavors.txt
gum filter < flavors.txt > selection.txt
```
使用 `--limit` 或 `--no-limit` 标志选择多个选项。使用 `tab` 或 `ctrl+space` 选择，`enter` 确认。
```
cat flavors.txt | gum filter --limit 2
cat flavors.txt | gum filter --no-limit
```
## Choose
从选项列表中选择一个选项。
```
echo "Pick a card, any card..."
CARD=$(gum choose --height 15 {{A,K,Q,J},{10..2}}" "{♠,♥,♣,♦})
echo "Was your card the $CARD?"
```
你也可以使用 `--limit` 或 `--no-limit` 标志选择多个项目，这决定了可以选择的最大项目数。
```
cat songs.txt | gum choose --limit 5
cat foods.txt | gum choose --no-limit --header "Grocery Shopping"
```
## Confirm
确认是否执行操作。根据选择以退出代码 `0`（肯定）或 `1`（否定）退出。
```
gum confirm && rm file.txt || echo "File not removed"
```
## File
提示用户从文件树中选择一个文件。
```
$EDITOR $(gum file $HOME)
```
## Pager
滚动浏览带有行号和完全可自定义视口的长文档。
```
gum pager < README.md
```
## Spin
在运行脚本或命令时显示加载动画。加载动画将在给定命令退出后自动停止。
要查看或管道传输命令的输出，请使用 `--show-output` 标志。
```
gum spin --spinner dot --title "Buying Bubble Gum..." -- sleep 5
```
可用的加载动画类型包括：`line`、`dot`、`minidot`、`jump`、`pulse`、`points`、`globe`、`moon`、`monkey`、`meter`、`hamburger`。
## Table
从表格数据中选择一行。
```
gum table < flavors.csv | cut -d ',' -f 1
```
## Style
使用单个命令以任意布局漂亮地打印任何字符串。
```
gum style \
--foreground 212 --border-foreground 212 --border double \
--align center --width 50 --margin "1 2" --padding "2 4" \
'Bubble Gum (1¢)' 'So sweet and so fresh!'
```
## Join
垂直或水平组合文本。将此命令与 `gum style` 配合使用以构建布局和美化输出。
提示：在 `join` 命令中将 `gum style` 的输出作为参数使用时，请始终将其用引号括起来，以保留换行符 (`\n`)。
```
I=$(gum style --padding "1 5" --border double --border-foreground 212 "I")
LOVE=$(gum style --padding "1 4" --border double --border-foreground 57 "LOVE")
BUBBLE=$(gum style --padding "1 8" --border double --border-foreground 255 "Bubble")
GUM=$(gum style --padding "1 5" --border double --border-foreground 240 "Gum")
I_LOVE=$(gum join "$I" "$LOVE")
BUBBLE_GUM=$(gum join "$BUBBLE" "$GUM")
gum join --align center --vertical "$I_LOVE" "$BUBBLE_GUM"
```
## Format
`format` 处理并格式化文本正文。`gum format` 可以解析 Markdown、模板字符串和命名表情符号。
```
# Format 一些 markdown
gum format -- "# Gum Formats" "- Markdown" "- Code" "- Template" "- Emoji"
echo "# Gum Formats\n- Markdown\n- Code\n- Template\n- Emoji" | gum format
# Syntax highlight 一些代码
cat main.go | gum format -t code
# 使用 templates 以任何方式渲染文本
echo '{{ Bold "Tasty" }} {{ Italic "Bubble" }} {{ Color "99" "0" " Gum " }}' \
| gum format -t template
# 显示您最喜欢的 emojis！
echo 'I :heart: Bubble Gum :candy:' | gum format -t emoji
```
有关模板助手的更多信息，请参阅 [Termenv 文档](https://github.com/muesli/termenv#template-helpers)。有关命名表情符号的完整列表，请参阅 [GitHub API](https://api.github.com/emojis)。
## Log
`log` 使用 [`charmbracelet/log`](https://github.com/charmbracelet/log) 库将消息以不同级别和样式记录到终端。
```
# Log 一些 debug 信息。
gum log --structured --level debug "Creating file..." name file.txt
# DEBUG 无法创建文件。name=temp.txt
# Log 一些 error。
gum log --structured --level error "Unable to create file." name file.txt
# ERROR 无法创建文件。name=temp.txt
# 包含 timestamp。
gum log --time rfc822 --level error "Unable to create file."
```
有关可接受的 `--time` 格式，请参阅 Go [`time` package](https://pkg.go.dev/time#pkg-constants)。
有关更多用法，请参阅 [`charmbracelet/log`](https://github.com/charmbracelet/log)。
## 示例
如何在日常工作中使用 `gum`：
请参阅 [examples](./examples/) 目录以获取更多真实用例。
- 编写提交信息：
```
git commit -m "$(gum input --width 50 --placeholder "Summary of changes")" \
-m "$(gum write --width 80 --placeholder "Details of changes")"
```
- 在你的 `$EDITOR` 中打开文件
```
$EDITOR $(gum filter)
```
- 连接到 `tmux` 会话
```
SESSION=$(tmux list-sessions -F \#S | gum filter --placeholder "Pick session...")
tmux switch-client -t "$SESSION" || tmux attach -t "$SESSION"
```
- 从 `git` 历史中选择提交哈希
```
git log --oneline | gum filter | cut -d' ' -f1 # | copy
```
- 简易 [`skate`](https://github.com/charmbracelet/skate) 密码选择器。
```
skate list -k | gum filter | xargs skate get
```
- 卸载软件包
```
brew list | gum choose --no-limit | xargs brew uninstall
```
- 清理 `git` 分支
```
git branch | cut -c 3- | gum choose --no-limit | xargs git branch -D
```
- 使用 [`gh`](https://cli.github.com/) 检出 GitHub Pull Requests
```
gh pr list | cut -f1,2 | gum choose | cut -f1 | xargs gh pr checkout
```
- 从 Shell 历史复制命令
```
gum filter < $HISTFILE --height 20
```
- `sudo` 替代品
```
alias please="gum input --password | sudo -nS"
```
## 贡献
请参阅 [贡献指南][contribute]。
## 反馈
我们很乐意听到您对这个项目的想法。欢迎给我们留言！
- [Twitter](https://twitter.com/charmcli)
- [The Fediverse](https://mastodon.social/@charmcli)
- [Discord](https://charm.sh/chat)
## 许可证
[MIT](https://github.com/charmbracelet/gum/raw/main/LICENSE)
[Charm](https://charm.sh) 的一部分。
Charm热爱开源 • Charm loves open source
标签：Awesome, Bubbles, Charmbracelet, CLI增强, Dotfiles管理, EVTX分析, EVTX分析, Git提交辅助, Go语言, Lipgloss, Shell脚本, TUI, 交互式编程, 命令行美化, 威胁情报, 开发者工具, 提示框, 数字取证, 日志审计, 用户界面组件, 程序破解, 系统管理, 终端UI, 脚本工具, 自动化脚本, 表格显示, 运维工具, 进度条, 选择菜单