deblan-mirror/gum

Fork 0

mirror of https://github.com/charmbracelet/gum synced 2024-05-29 03:42:26 +02:00

Maas Lalani 74ef277486

docs: customization flags

2022-07-15 16:12:50 -04:00

10 KiB

Raw Blame History

Gum

Gum is a collection of command-line utilities that make your shell scripts a little more glamorous. It gives you the power of Bubbles and Lip Gloss without needing to write any Go code.

# Prompt users for input
NAME=$(gum input --placeholder "What is your name?")

# Style some text
gum style --foreground 212 --padding "1 4" \
	--border double --border-foreground 57 \
	"Nice to meet you, $NAME."

# Do some work while spinning
gum spin --title "Taking a nap..." --color 212 -- sleep 5

# Fuzzy find a file or directory
find . -type f | gum filter

The following example is running from a single bash script.

Shell running the Gum examples/demo.sh script

Installation

Use a package manager:

# macOS or Linux
brew tap charmbracelet/tap && brew install charmbracelet/tap/gum

# Arch Linux (btw)
pacman -S gum

# Nix
nix-env -iA nixpkgs.gum

# Debian/Ubuntu
echo 'deb [trusted=yes] https://repo.charm.sh/apt/ /' \
    | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install gum

# Fedora
echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=0' | sudo tee /etc/yum.repos.d/charm.repo
sudo yum install gum

Or download it:

Packages are available in Debian and RPM formats
Binaries are available for Linux, macOS, and Windows

Or just install it with go:

go install github.com/charmbracelet/gum@latest

Customization

gum is designed to be embedded in scripts and different use cases. All components are configurable and customizable to fit your theme and use case.

You can customize with --flags. See gum <command> --help for a full view of all the command's customization and configuration options.

For example, let's customize the cursor color, prompt color, prompt indicator, placeholder text, width, and pre-populate the value of the input:

gum input --cursor.foreground "#FF0" --prompt.foreground "#0FF" --prompt "* " \
    --placeholder "What's up?" --width 80 --value "Not much, hby?"

Interaction

Input

Prompt your users for input with a simple command.

gum input > answer.text

Shell running gum input typing I love bubble gum <3

Write

Prompt your users to write some multi-line text.

gum write > story.text

Shell running gum write typing My favorite flavors are:

Filter

Allow your users to filter through a list of options by fuzzy searching.

echo Strawberry >> flavors.text
echo Banana >> flavors.text
echo Cherry >> flavors.text
cat flavors.text | gum filter > selection.text

Shell running gum filter on different bubble gum flavors

Choose

Ask your users to choose an option from a list of choices.

echo "Pick a card, any card..."
CARD=$(gum choose --height 15 {{A,K,Q,J},{10..2}}" "{♠,♥,♣,♦})
echo "Was your card the $CARD?"

Shell running gum choose on a deck of cards, picking the Ace of Hearts

You can also set a limit on the number of items to choose with the --limit flag.

echo "Pick your top 5 songs."
cat songs.txt | gum choose --limit 5

Or, allow any number of selections with the --no-limit flag.

echo "What do you need from the grocery store?"
cat foods.txt | gum choose --no-limit

Progress

Display a progress bar while loading. The following command will display a progress bar and increment the progress by 10% every 1 second. Thus, taking 10 seconds to complete the progress bar.

gum progress --increment 0.1 --interval 1s

Spinners

Display a spinner while taking some running action. We specify the command to run while showing the spinner, the spinner will automatically stop after the command exits.

gum spin --spinner dot --title "Buying Bubble Gum..." -- sleep 5

Shell running gum spin while sleeping for 5 seconds

Styling and Layout

Style

Pretty print any string with any layout with one command.

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

Combine text vertically or horizontally with a single command, use this command with gum style to build layouts and pretty output.

Note: It's important to wrap the output of gum style in quotes to ensure new lines (\n) are part of a single argument passed to the join command.

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"

I LOVE Bubble Gum written out in four boxes with double borders around them.

Format

Format allows you to take some text and stylize it. gum format can parse markdown, code, template strings, and emoji strings.

For example, we can output a markdown list with the following command:

gum format -- "# Gum Formats" "- Markdown" "- Code" "- Template" "- Emoji"
echo "# Gum Formats\n- Markdown\n- Code\n- Template\n- Emoji" | gum format

Format markdown displaying a markdown list with content of different possible formats

Apply syntax highlighting to code with gum format -t code:

cat main.go | gum format -t code

Format code command displaying a simple Hello, world! Go program with syntax highlighting.

Render a template string with gum format -t template:

echo '{{ Bold "Tasty" }} {{ Italic "Bubble" }} {{ Color "99" "0" " Gum " }}' \
    | gum format -t template

Format template command displaying Tasty Bubble Gum in different styles

Render some emojis with :emoji: syntax with gum format -t emoji.

echo 'I :heart: Bubble Gum :candy:' | gum format -t emoji

Format emoji command displaying I :heart: Bubble Gum :candy:.

Examples

See the examples directory for more real world use cases.

How to use gum in your daily workflows:

Write a commit message

Prompt for user input to write git commit messages with a short summary and longer details with gum input and gum write.

Bonus points if you use gum filter with the Conventional Commits Specification as a prefix for your commit message.

git commit -m "$(gum input --width 50 --placeholder "Summary of changes")" \
           -m "$(gum write --width 80 --placeholder "Details of changes")"

Running the ./examples/commit.sh script to commit to git

Open files in your `$EDITOR`

By default gum filter will display a list of all files (searched recursively) through your current directory, it has some sensible ignored defaults (.git, node_modules). You can use this to pick a file and open it in your $EDITOR.

$EDITOR $(gum filter)

Connect to a TMUX session

Pick from a running TMUX session and attach to it if not inside TMUX or switch your client to the session if already attached to a session.

SESSION=$(tmux list-sessions -F \#S | gum filter --placeholder "Pick session...")
tmux switch-client -t $SESSION || tmux attach -t $SESSION

Pick commit hash from history

Filter through your git history searching for commit messages and copy the commit hash of the selected commit.

git log --oneline | gum filter | cut -d' ' -f1 # | copy

Choose packages to uninstall

List all packages installed by your package manager (we'll use brew) and choose which packages to uninstall.

brew list | gum choose --no-limit | xargs brew uninstall

Feedback

We’d love to hear your thoughts on this project. Feel free to drop us a note!

License

MIT

Part of Charm.

Charm热爱开源 • Charm loves open source

10 KiB Raw Blame History Unescape Escape

Gum