2022-07-15 23:26:33 +02:00
Gum
===
2022-06-11 00:07:40 +02:00
2022-07-08 19:47:21 +02:00
< p >
2022-07-27 03:48:56 +02:00
< a href = "https://stuff.charm.sh/gum/nutritional-information.png" target = "_blank" > < img src = "https://stuff.charm.sh/gum/gum.png" alt = "Gum Image" width = "450" / > < / a >
2022-07-18 19:57:54 +02:00
< br > < br >
2022-07-08 19:47:21 +02:00
< a href = "https://github.com/charmbracelet/gum/releases" > < img src = "https://img.shields.io/github/release/charmbracelet/gum.svg" alt = "Latest Release" > < / a >
2022-07-28 14:52:44 +02:00
< a href = "https://pkg.go.dev/github.com/charmbracelet/gum?tab=doc" > < img src = "https://godoc.org/github.com/golang/gddo?status.svg" alt = "Go Docs" > < / a >
2022-07-08 19:47:21 +02:00
< a href = "https://github.com/charmbracelet/gum/actions" > < img src = "https://github.com/charmbracelet/gum/workflows/build/badge.svg" alt = "Build Status" > < / a >
< / p >
2022-07-27 23:00:38 +02:00
A tool for glamorous shell scripts. Leverage the power of
2022-07-27 00:33:42 +02:00
[Bubbles ](https://github.com/charmbracelet/bubbles ) and [Lip
2022-07-27 23:00:38 +02:00
Gloss](https://github.com/charmbracelet/lipgloss) in your scripts and aliases
without writing any Go code!
2022-07-15 22:11:32 +02:00
2024-04-05 08:32:11 +02:00
< img alt = "Shell running the ./demo.sh script" width = "600" src = "https://vhs.charm.sh/vhs-1qY57RrQlXCuydsEgDp68G.gif" >
2022-07-18 20:44:48 +02:00
2022-07-26 19:21:08 +02:00
The above example is running from a single shell script ([source](./examples/demo.sh)).
2022-07-26 17:01:11 +02:00
2022-07-21 17:55:52 +02:00
## Tutorial
2022-07-25 18:44:40 +02:00
Gum provides highly configurable, ready-to-use utilities to help you write
2022-07-28 22:24:41 +02:00
useful shell scripts and dotfiles aliases with just a few lines of code.
2024-04-04 08:17:07 +02:00
Let's build a simple script to help you write [Conventional Commits ](https://www.conventionalcommits.org/en/v1.0.0/#summary )
for your dotfiles.
2022-07-22 21:57:56 +02:00
2024-04-04 08:26:40 +02:00
Ask for the commit type with gum choose:
2022-07-21 17:55:52 +02:00
```bash
gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert"
```
2024-04-04 08:17:07 +02:00
> [!NOTE]
> This command itself will print to stdout which is not all that useful. To make use of the command later on you can save the stdout to a `$VARIABLE` or `file.txt`.
2022-07-21 17:55:52 +02:00
2024-04-04 08:17:07 +02:00
Prompt for the scope of these changes:
2022-07-21 17:55:52 +02:00
```bash
gum input --placeholder "scope"
```
2024-04-04 08:17:07 +02:00
Prompt for the summary and description of changes:
2022-07-21 17:55:52 +02:00
```bash
2024-04-04 08:17:07 +02:00
gum input --value "$TYPE$SCOPE: " --placeholder "Summary of this change"
gum write --placeholder "Details of this change"
2022-07-21 17:55:52 +02:00
```
2024-04-04 08:17:07 +02:00
Confirm before committing:
2022-07-28 00:40:52 +02:00
```bash
gum confirm "Commit changes?" & & git commit -m "$SUMMARY" -m "$DESCRIPTION"
```
2024-04-05 10:20:49 +02:00
Check out the [complete example ](https://github.com/charmbracelet/gum/blob/main/examples/commit.sh ) for combining these commands in a single script.
2022-07-21 17:55:52 +02:00
2024-04-05 08:32:11 +02:00
< img alt = "Running the ./examples/commit.sh script to commit to git" width = "600" src = "https://vhs.charm.sh/vhs-7rRq3LsEuJVwhwr0xf6Er7.gif" >
2022-07-21 17:55:52 +02:00
2022-07-08 19:31:54 +02:00
## Installation
Use a package manager:
```bash
# macOS or Linux
2022-07-31 17:49:38 +02:00
brew install gum
2022-07-08 19:31:54 +02:00
2022-07-08 23:34:51 +02:00
# Arch Linux (btw)
2022-08-04 17:51:05 +02:00
pacman -S gum
2022-07-08 19:31:54 +02:00
# Nix
nix-env -iA nixpkgs.gum
2022-12-18 23:51:19 +01:00
2023-07-25 18:23:48 +02:00
# Windows (via WinGet or Scoop)
2024-04-22 21:44:33 +02:00
winget install charmbracelet.gum
2022-12-18 23:51:19 +01:00
scoop install charm-gum
2022-07-08 19:31:54 +02:00
```
Or download it:
2022-10-23 05:04:16 +02:00
* [Packages][releases] are available in Debian, RPM, and Alpine formats
* [Binaries][releases] are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD
2022-07-08 19:31:54 +02:00
Or just install it with `go` :
```bash
go install github.com/charmbracelet/gum@latest
```
[releases]: https://github.com/charmbracelet/gum/releases
2024-04-04 08:17:07 +02:00
## Commands
2022-07-15 22:11:32 +02:00
2024-04-04 08:17:07 +02:00
* [`choose` ](#choose ): Choose an option from a list of choices
* [`confirm` ](#confirm ): Ask a user to confirm an action
* [`file` ](#file ): Pick a file from a folder
* [`filter` ](#filter ): Filter items from a list
* [`format` ](#format ): Format a string using a template
* [`input` ](#input ): Prompt for some input
* [`join` ](#join ): Join text vertically or horizontally
* [`pager` ](#pager ): Scroll through a file
* [`spin` ](#spin ): Display spinner while running a command
* [`style` ](#style ): Apply coloring, borders, spacing to text
* [`table` ](#table ): Render a table of data
* [`write` ](#write ): Prompt for long-form text
* [`log` ](#log ): Log messages to output
2022-07-15 22:11:32 +02:00
2022-07-26 19:21:08 +02:00
2024-04-04 08:17:07 +02:00
## Customization
You can customize `gum` options and styles with `--flags` and `$ENVIRONMENT_VARIABLES` .
See `gum <command> --help` for a full view of each command's customization and configuration options.
2022-07-15 22:11:32 +02:00
2024-04-04 08:17:07 +02:00
Customize with `--flags` :
2022-07-15 22:11:32 +02:00
```bash
2024-04-04 08:17:07 +02:00
gum input --cursor.foreground "#FF0" \
--prompt.foreground "#0FF" \
--placeholder "What's up?" \
--prompt "* " \
--width 80 \
--value "Not much, hby?"
2022-07-15 22:11:32 +02:00
```
2024-04-04 08:17:07 +02:00
Customize with `ENVIRONMENT_VARIABLES` :
2022-08-08 23:06:30 +02:00
```bash
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
2024-04-04 08:17:07 +02:00
# --flags can override values set with environment
2022-08-08 23:06:30 +02:00
gum input
```
2024-04-05 10:16:25 +02:00
< img alt = "Gum input displaying most customization options" width = "600" src = "https://vhs.charm.sh/vhs-5zb9DlQYA70aL9ZpYLTwKv.gif" >
2022-07-22 18:00:38 +02:00
2024-04-04 08:17:07 +02:00
## Input
2022-07-26 19:21:08 +02:00
Prompt for input with a simple command.
2022-06-11 00:07:40 +02:00
```bash
2022-10-08 13:54:41 +02:00
gum input > answer.txt
gum input --password > password.txt
2022-08-03 02:54:16 +02:00
```
2024-04-05 10:16:25 +02:00
< img src = "https://vhs.charm.sh/vhs-1nScrStFI3BMlCp5yrLtyg.gif" width = "600" alt = "Shell running gum input typing Not much, you?" / >
2022-07-13 05:44:06 +02:00
2024-04-04 08:17:07 +02:00
## Write
2022-07-08 05:21:31 +02:00
2024-04-04 08:17:07 +02:00
Prompt for some multi-line text (`ctrl+d` to complete text entry).
2022-08-05 14:48:31 +02:00
2022-07-08 05:21:31 +02:00
```bash
2022-10-08 13:54:41 +02:00
gum write > story.txt
2022-07-08 05:21:31 +02:00
```
2024-04-05 10:16:25 +02:00
< img src = "https://vhs.charm.sh/vhs-7abdKKrUEukgx9aJj8O5GX.gif" width = "600" alt = "Shell running gum write typing a story" / >
2022-07-13 05:44:06 +02:00
2024-04-04 08:17:07 +02:00
## Filter
2022-06-11 00:07:40 +02:00
2024-04-04 08:17:07 +02:00
Filter a list of values with fuzzy matching:
2022-06-11 00:07:40 +02:00
```bash
2022-10-08 13:54:41 +02:00
echo Strawberry >> flavors.txt
echo Banana >> flavors.txt
echo Cherry >> flavors.txt
2024-04-04 08:17:07 +02:00
gum filter < flavors.txt > selection.txt
2022-06-11 00:07:40 +02:00
```
2024-04-05 10:16:25 +02:00
< img src = "https://vhs.charm.sh/vhs-61euOQtKPtQVD7nDpHQhzr.gif" width = "600" alt = "Shell running gum filter on different bubble gum flavors" / >
2022-07-13 05:44:06 +02:00
2024-04-04 08:17:07 +02:00
Select multiple options with the `--limit` flag or `--no-limit` flag. Use `tab` or `ctrl+space` to select, `enter` to confirm.
2024-03-28 18:12:19 +01:00
2022-09-30 19:34:21 +02:00
```bash
2022-10-08 13:54:41 +02:00
cat flavors.txt | gum filter --limit 2
cat flavors.txt | gum filter --no-limit
2022-09-30 19:34:21 +02:00
```
2024-04-04 08:17:07 +02:00
## Choose
feat: `gum choose`, pick from a list of choices
gum choose allows the user to be prompted for a choice from a list of choices.
For example, let's ask the user to pick a card from a deck.
gum choose --height 15 {Ace,King,Queen,Jack,Ten,Nine,Eight,Seven,Six,Five,Four,Three,Two}" of "{Spades,Hearts,Clubs,Diamonds}
2022-07-11 22:17:47 +02:00
2022-07-26 19:21:08 +02:00
Choose an option from a list of choices.
feat: `gum choose`, pick from a list of choices
gum choose allows the user to be prompted for a choice from a list of choices.
For example, let's ask the user to pick a card from a deck.
gum choose --height 15 {Ace,King,Queen,Jack,Ten,Nine,Eight,Seven,Six,Five,Four,Three,Two}" of "{Spades,Hearts,Clubs,Diamonds}
2022-07-11 22:17:47 +02:00
```bash
echo "Pick a card, any card..."
CARD=$(gum choose --height 15 {{A,K,Q,J},{10..2}}" "{♠,♥,♣,♦})
echo "Was your card the $CARD?"
```
2024-04-04 08:17:07 +02:00
You can also select multiple items with the `--limit` or `--no-limit` flag, which determines
2022-07-26 19:21:08 +02:00
the maximum of items that can be chosen.
2022-07-13 19:14:59 +02:00
```bash
cat songs.txt | gum choose --limit 5
2024-04-04 08:17:07 +02:00
cat foods.txt | gum choose --no-limit --header "Grocery Shopping"
2022-07-13 19:14:59 +02:00
```
2024-04-05 10:16:25 +02:00
< img src = "https://vhs.charm.sh/vhs-3zV1LvofA6Cbn5vBu1NHHl.gif" width = "600" alt = "Shell running gum choose with numbers and gum flavors" / >
2022-07-13 05:44:06 +02:00
2024-04-04 08:17:07 +02:00
## Confirm
2022-07-26 22:09:33 +02:00
Confirm whether to perform an action. Exits with code `0` (affirmative) or `1`
(negative) depending on selection.
```bash
gum confirm & & rm file.txt || echo "File not removed"
```
2024-04-05 10:16:25 +02:00
< img src = "https://vhs.charm.sh/vhs-3xRFvbeQ4lqGerbHY7y3q2.gif" width = "600" alt = "Shell running gum confirm" / >
2022-07-26 22:09:33 +02:00
2024-04-04 08:17:07 +02:00
## File
2022-10-02 21:55:14 +02:00
Prompt the user to select a file from the file tree.
```bash
EDITOR $(gum file $HOME)
```
2024-04-05 10:16:25 +02:00
< img src = "https://vhs.charm.sh/vhs-2RMRqmnOPneneIgVJJ3mI1.gif" width = "600" alt = "Shell running gum file" / >
2022-10-02 21:55:14 +02:00
2024-04-04 08:17:07 +02:00
## Pager
2022-10-02 21:55:14 +02:00
Scroll through a long document with line numbers and a fully customizable viewport.
```bash
gum pager < README.md
```
2024-04-05 10:16:25 +02:00
< img src = "https://vhs.charm.sh/vhs-3iMDpgOLmbYr0jrYEGbk7p.gif" width = "600" alt = "Shell running gum pager" / >
2022-10-02 21:55:14 +02:00
2024-04-04 08:17:07 +02:00
## Spin
2022-06-11 00:07:40 +02:00
2022-07-26 19:21:08 +02:00
Display a spinner while running a script or command. The spinner will
automatically stop after the given command exits.
2022-06-11 00:07:40 +02:00
2023-06-27 16:31:54 +02:00
To view or pipe the command's output, use the `--show-output` flag.
2022-06-11 00:07:40 +02:00
```bash
2022-07-07 19:26:35 +02:00
gum spin --spinner dot --title "Buying Bubble Gum..." -- sleep 5
2022-06-11 00:07:40 +02:00
```
2024-04-05 10:16:25 +02:00
< img src = "https://vhs.charm.sh/vhs-3YFswCmoY4o3Q7MyzWl6sS.gif" width = "600" alt = "Shell running gum spin while sleeping for 5 seconds" / >
2022-07-13 05:44:06 +02:00
2022-07-30 22:56:22 +02:00
Available spinner types include: `line` , `dot` , `minidot` , `jump` , `pulse` , `points` , `globe` , `moon` , `monkey` , `meter` , `hamburger` .
2022-07-30 22:53:24 +02:00
2024-04-04 08:17:07 +02:00
## Table
2022-10-02 21:55:14 +02:00
Select a row from some tabular data.
```bash
gum table < flavors.csv | cut -d ' , ' -f 1
```
2024-04-05 10:16:25 +02:00
<!-- <img src="https://stuff.charm.sh/gum/table.gif" width="600" alt="Shell running gum table" /> -->
2022-10-02 21:55:14 +02:00
2024-04-04 08:17:07 +02:00
## Style
2022-07-18 20:44:48 +02:00
2022-06-11 00:07:40 +02:00
Pretty print any string with any layout with one command.
```bash
2022-07-07 19:26:35 +02:00
gum style \
2022-07-13 20:45:44 +02:00
--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!'
2022-06-11 00:07:40 +02:00
```
2024-04-05 10:16:25 +02:00
< img src = "https://github.com/charmbracelet/gum/assets/42545625/67468acf-b3e0-4e78-bd89-360739eb44fa" width = "600" alt = "Bubble Gum, So sweet and so fresh!" / >
2022-06-11 00:07:40 +02:00
2024-04-04 08:17:07 +02:00
## Join
2022-07-08 05:21:31 +02:00
2022-07-26 19:21:08 +02:00
Combine text vertically or horizontally. Use this command with `gum style` to
build layouts and pretty output.
2022-07-08 05:21:31 +02:00
2022-07-26 19:21:08 +02:00
Tip: Always wrap the output of `gum style` in quotes to preserve newlines
(`\n`) when using it as an argument in the ` join` command.
2022-07-08 05:21:31 +02:00
```bash
2022-07-13 20:45:44 +02:00
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")
2022-07-08 05:29:18 +02:00
I_LOVE=$(gum join "$I" "$LOVE")
BUBBLE_GUM=$(gum join "$BUBBLE" "$GUM")
gum join --align center --vertical "$I_LOVE" "$BUBBLE_GUM"
2022-07-08 05:21:31 +02:00
```
2024-04-05 10:16:25 +02:00
< img src = "https://github.com/charmbracelet/gum/assets/42545625/68f7a25d-b495-48dd-982a-cee0c8ea5786" width = "600" alt = "I LOVE Bubble Gum written out in four boxes with double borders around them." / >
2022-07-08 05:21:31 +02:00
2022-07-18 20:44:48 +02:00
## Format
2022-07-26 19:21:08 +02:00
`format` processes and formats bodies of text. `gum format` can parse markdown,
template strings, and named emojis.
2022-07-15 17:01:19 +02:00
```bash
2022-07-20 19:49:09 +02:00
# Format some markdown
2022-07-15 17:14:38 +02:00
gum format -- "# Gum Formats" "- Markdown" "- Code" "- Template" "- Emoji"
2022-07-15 17:01:19 +02:00
echo "# Gum Formats\n- Markdown\n- Code\n- Template\n- Emoji" | gum format
2022-07-20 19:49:09 +02:00
# Syntax highlight some code
2022-07-15 17:01:19 +02:00
cat main.go | gum format -t code
2022-07-18 20:44:48 +02:00
2022-07-20 19:49:09 +02:00
# Render text any way you want with templates
2022-07-15 17:14:38 +02:00
echo '{{ Bold "Tasty" }} {{ Italic "Bubble" }} {{ Color "99" "0" " Gum " }}' \
| gum format -t template
2022-07-15 17:01:19 +02:00
2022-07-20 19:49:09 +02:00
# Display your favorite emojis!
2022-07-15 17:01:19 +02:00
echo 'I :heart: Bubble Gum :candy:' | gum format -t emoji
```
2022-07-29 18:51:44 +02:00
For more information on template helpers, see the [Termenv
2022-07-26 19:21:08 +02:00
docs](https://github.com/muesli/termenv#template-helpers). For a full list of
named emojis see the [GitHub API ](https://api.github.com/emojis ).
2024-04-05 10:16:25 +02:00
< img src = "https://github.com/charmbracelet/gum/assets/42545625/5cfbb0c8-0022-460d-841b-fec37527ca66" width = "300" alt = "Running gum format for different types of formats" / >
2022-07-15 17:14:38 +02:00
2023-11-08 16:59:16 +01:00
## Log
`log` logs messages to the terminal at using different levels and styling using
the [`charmbracelet/log` ](https://github.com/charmbracelet/log ) library.
```bash
# Log some debug information.
gum log --structured --level debug "Creating file..." name file.txt
# DEBUG Unable to create file. name=temp.txt
# Log some error.
gum log --structured --level error "Unable to create file." name file.txt
# ERROR Unable to create file. name=temp.txt
2024-01-12 20:31:18 +01:00
# Include a timestamp.
gum log --time rfc822 --level error "Unable to create file."
2023-11-08 16:59:16 +01:00
```
2024-01-12 20:31:18 +01:00
See the Go [`time` package ](https://pkg.go.dev/time#pkg-constants ) for acceptable `--time` formats.
2023-11-08 16:59:16 +01:00
See [`charmbracelet/log` ](https://github.com/charmbracelet/log ) for more usage.
2023-11-08 17:11:50 +01:00
< img src = "https://vhs.charm.sh/vhs-6jupuFM0s2fXiUrBE0I1vU.gif" width = "600" alt = "Running gum log with debug and error levels" / >
2022-07-11 19:30:57 +02:00
## Examples
How to use `gum` in your daily workflows:
2024-04-05 08:38:26 +02:00
See the [examples ](./examples/ ) directory for more real world use cases.
2022-07-11 19:30:57 +02:00
2024-04-05 08:38:26 +02:00
* Write a commit message:
2022-07-11 19:30:57 +02:00
```bash
git commit -m "$(gum input --width 50 --placeholder "Summary of changes")" \
2024-04-05 08:38:26 +02:00
-m "$(gum write --width 80 --placeholder "Details of changes")"
2022-07-11 19:30:57 +02:00
```
2024-04-05 08:38:26 +02:00
* Open files in your `$EDITOR`
2022-07-13 22:26:58 +02:00
```bash
$EDITOR $(gum filter)
```
2024-04-05 08:38:26 +02:00
* Connect to a `tmux` session
2022-07-11 19:30:57 +02:00
```bash
SESSION=$(tmux list-sessions -F \#S | gum filter --placeholder "Pick session...")
tmux switch-client -t $SESSION || tmux attach -t $SESSION
```
2022-07-08 05:21:31 +02:00
2024-04-05 08:38:26 +02:00
* Pick a commit hash from `git` history
2022-07-11 19:54:45 +02:00
```bash
git log --oneline | gum filter | cut -d' ' -f1 # | copy
```
2024-04-05 08:38:26 +02:00
* Simple [`skate` ](https://github.com/charmbracelet/skate ) password selector.
2022-08-30 18:24:11 +02:00
```
skate list -k | gum filter | xargs skate get
```
2024-04-05 08:38:26 +02:00
* Uninstall packages
2022-07-13 19:14:59 +02:00
```bash
brew list | gum choose --no-limit | xargs brew uninstall
```
2022-07-11 19:54:45 +02:00
2024-04-05 08:38:26 +02:00
* Clean up `git` branches
2022-07-31 04:02:07 +02:00
```bash
git branch | cut -c 3- | gum choose --no-limit | xargs git branch -D
```
2024-04-05 08:38:26 +02:00
* Checkout GitHub pull requests with [`gh` ](https://cli.github.com/ )
2022-08-01 22:09:45 +02:00
```bash
2022-08-02 17:26:44 +02:00
gh pr list | cut -f1,2 | gum choose | cut -f1 | xargs gh pr checkout
2022-08-01 22:09:45 +02:00
```
2024-04-05 08:38:26 +02:00
* Copy command from shell history
2022-08-04 23:53:53 +02:00
```bash
gum filter < $HISTFILE --height 20
```
2024-04-05 08:38:26 +02:00
* `sudo` replacement
2022-08-04 23:53:53 +02:00
```bash
alias please="gum input --password | sudo -nS"
```
2022-06-11 00:07:40 +02:00
## Feedback
We’ d love to hear your thoughts on this project. Feel free to drop us a note!
* [Twitter ](https://twitter.com/charmcli )
2022-10-24 08:36:19 +02:00
* [The Fediverse ](https://mastodon.social/@charmcli )
* [Discord ](https://charm.sh/chat )
2022-06-11 00:07:40 +02:00
## License
2022-07-11 19:30:57 +02:00
[MIT ](https://github.com/charmbracelet/gum/raw/main/LICENSE )
2022-06-11 00:07:40 +02:00
2022-10-24 08:36:19 +02:00
***
2022-07-27 01:29:07 +02:00
2022-06-11 00:07:40 +02:00
Part of [Charm ](https://charm.sh ).
2022-07-20 21:19:23 +02:00
< a href = "https://charm.sh/" > < img alt = "The Charm logo" src = "https://stuff.charm.sh/charm-badge.jpg" width = "400" / > < / a >
2022-06-11 00:07:40 +02:00
Charm热爱开源 • Charm loves open source