From 63debfa2a22c4d4fd91856ee982819a9a8477dda Mon Sep 17 00:00:00 2001 From: JMARyA Date: Wed, 27 Mar 2024 17:48:18 +0100 Subject: [PATCH] add gum --- technology/applications/cli/gum.md | 424 +++++++++++++++++++++++++++++ 1 file changed, 424 insertions(+) create mode 100644 technology/applications/cli/gum.md diff --git a/technology/applications/cli/gum.md b/technology/applications/cli/gum.md new file mode 100644 index 0000000..dbd2b25 --- /dev/null +++ b/technology/applications/cli/gum.md @@ -0,0 +1,424 @@ +--- +obj: application +repo: https://github.com/charmbracelet/gum +rev: 2024-03-27 +--- + +# gum +Gum provides highly configurable, ready-to-use utilities to help you write useful [shell](Shell.md) scripts and dotfiles aliases with just a few lines of code. + +![Gum][Gum] + +## Usage +**Example:** +```shell +#!/bin/sh +TYPE=$(gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert") +SCOPE=$(gum input --placeholder "scope") + +# Since the scope is optional, wrap it in parentheses if it has a value. +test -n "$SCOPE" && SCOPE="($SCOPE)" + +# Pre-populate the input with the type(scope): so that the user may change it +SUMMARY=$(gum input --value "$TYPE$SCOPE: " --placeholder "Summary of this change") +DESCRIPTION=$(gum write --placeholder "Details of this change (CTRL+D to finish)") + +# Commit these changes +gum confirm "Commit changes?" && git commit -m "$SUMMARY" -m "$DESCRIPTION" +``` + +### gum choose +Choose an option from a list of choices +Usage: `gum choose [ ...]` + +| Option | Environment Variable | Description | +| ----------------------------- | --------------------------------- | -------------------------------------------------------------- | +| `--ordered` | `$GUM_CHOOSE_ORDERED` | Maintain the order of the selected options | +| `--height=10` | `$GUM_CHOOSE_HEIGHT` | Height of the list | +| `--cursor="> "` | `$GUM_CHOOSE_CURSOR` | Prefix to show on item that corresponds to the cursor position | +| `--header=""` | `$GUM_CHOOSE_HEADER` | Header value | +| `--cursor-prefix="○ "` | `$GUM_CHOOSE_CURSOR_PREFIX` | Prefix to show on the cursor item (hidden if limit is 1) | +| `--selected-prefix="◉ "` | `$GUM_CHOOSE_SELECTED_PREFIX` | Prefix to show on selected items (hidden if limit is 1) | +| `--unselected-prefix="○ "` | `$GUM_CHOOSE_UNSELECTED_PREFIX` | Prefix to show on unselected items (hidden if limit is 1) | +| `--selected=,...` | `$GUM_CHOOSE_SELECTED` | Options that should start as selected | +| `--timeout=0` | `$GUM_CCHOOSE_TIMEOUT` | Timeout until choose returns selected element | +| `--limit=1` | - | Maximum number of options to pick | +| `--no-limit` | - | Pick unlimited number of options (ignores limit) | +| `--select-if-one` | - | Select the given option if there is only one | +| `--cursor.foreground="212"` | `$GUM_CHOOSE_CURSOR_FOREGROUND` | Foreground Color | +| `--header.foreground="240"` | `$GUM_CHOOSE_HEADER_FOREGROUND` | Foreground Color | +| `--item.foreground=""` | `$GUM_CHOOSE_ITEM_FOREGROUND` | Foreground Color | +| `--selected.foreground="212"` | `$GUM_CHOOSE_SELECTED_FOREGROUND` | Foreground Color | + +**Example**: +Choose an option from a list of choices. +```shell +echo "Pick a card, any card..." +CARD=$(gum choose --height 15 {{A,K,Q,J},{10..2}}" "{♠,♥,♣,♦}) +echo "Was your card the $CARD?" +``` + +### gum confirm +Ask a user to confirm an action +Usage: `gum confirm []` + +| Option | Environment Variable | Description | +| ------------------------------- | ------------------------------------ | ------------------------------------------------------------------- | +| `--default` | - | Default confirmation action | +| `--affirmative="Yes"` | - | The title of the affirmative action | +| `--negative="No"` | - | The title of the negative action | +| `--timeout=0` | `$GUM_CONFIRM_TIMEOUT` | Timeout until confirm returns selected value or default if provided | +| `--prompt.foreground=""` | `$GUM_CONFIRM_PROMPT_FOREGROUND` | Foreground Color | +| `--selected.foreground="230"` | `$GUM_CONFIRM_SELECTED_FOREGROUND` | Foreground Color | +| `--unselected.foreground="254"` | `$GUM_CONFIRM_UNSELECTED_FOREGROUND` | Foreground Color | + +**Example**: +Confirm whether to perform an action. Exits with code 0 (affirmative) or 1 (negative) depending on selection. +```shell +gum confirm && rm file.txt || echo "File not removed" +``` + +### gum file +Pick a file from a folder +Usage: `gum file []` + +| Option | Environment Variable | Description | +| -------------------------------- | ---------------------------------- | ------------------------------------------------ | +| `[]` | `$GUM_FILE_PATH` | The path to the folder to begin traversing | +| `-c, --cursor=">"` | `$GUM_FILE_CURSOR` | The cursor character | +| `-a, --all` | `$GUM_FILE_ALL` | Show hidden and 'dot' files | +| `--file` | `$GUM_FILE_FILE` | Allow files selection | +| `--directory` | `$GUM_FILE_DIRECTORY` | Allow directories selection | +| `--height=0` | `$GUM_FILE_HEIGHT` | Maximum number of files to display | +| `--timeout=0` | `$GUM_FILE_TIMEOUT` | Timeout until command aborts without a selection | +| `--cursor.foreground="212"` | `$GUM_FILE_CURSOR_FOREGROUND` | Foreground Color | +| `--symlink.foreground="36"` | `$GUM_FILE_SYMLINK_FOREGROUND` | Foreground Color | +| `--directory.foreground="99"` | `$GUM_FILE_DIRECTORY_FOREGROUND` | Foreground Color | +| `--file.foreground="" ` | `$GUM_FILE_FILE_FOREGROUND` | Foreground Color | +| `--permissions.foreground="244"` | `$GUM_FILE_PERMISSIONS_FOREGROUND` | Foreground Color | +| `--selected.foreground="212"` | `$GUM_FILE_SELECTED_FOREGROUND` | Foreground Color | +| `--file-size.foreground="240"` | `$GUM_FILE_FILE_SIZE_FOREGROUND` | Foreground Color | + +**Example**: +Prompt the user to select a file from the file tree. +```shell +EDITOR $(gum file $HOME) +``` + +### gum filter +Filter items from a list +Usage: `gum filter [ ...]` + +| Option | Environment Variable | Description | +| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------- | +| `--indicator="•`" | `$GUM_FILTER_INDICATOR` | Character for selection | +| `--selected-prefix=" ◉ "` | `$GUM_FILTER_SELECTED_PREFIX` | Character to indicate selected items (hidden if limit is 1) | +| `--unselected-prefix=" ○ "` | `$GUM_FILTER_UNSELECTED_PREFIX` | Character to indicate unselected items (hidden if limit is 1) | +| `--header=""` | `$GUM_FILTER_HEADER` | Header value | +| `--placeholder="Filter..."` | `$GUM_FILTER_PLACEHOLDER` | Placeholder value | +| `--prompt="> "` | `$GUM_FILTER_PROMPT` | Prompt to display | +| `--width=20` | `$GUM_FILTER_WIDTH` | Input width | +| `--height=0` | `$GUM_FILTER_HEIGHT` | Input height | +| `--value=""` | `$GUM_FILTER_VALUE` | Initial filter value | +| `--reverse` | `$GUM_FILTER_REVERSE` | Display from the bottom of the screen | +| `--[no-]fuzzy` | `$GUM_FILTER_FUZZY` | Enable fuzzy matching | +| `--[no-]sort` | `$GUM_FILTER_SORT` | Sort the results | +| `--timeout=0` | `$GUM_FILTER_TIMEOUT` | Timeout until filter command aborts | +| `--indicator.foreground="212"` | `$GUM_FILTER_INDICATOR_FOREGROUND` | Foreground Color | +| `--selected-indicator.foreground="212"` | `$GUM_FILTER_SELECTED_PREFIX_FOREGROUND` | Foreground Color | +| `--unselected-prefix.foreground="240"` | `$GUM_FILTER_UNSELECTED_PREFIX_FOREGROUND` | Foreground Color | +| `--header.foreground="240"` | `$GUM_FILTER_HEADER_FOREGROUND` | Foreground Color | +| `--text.foreground=""` | `$GUM_FILTER_TEXT_FOREGROUND` | Foreground Color | +| `--cursor-text.foreground=""` | `$GUM_FILTER_CURSOR_TEXT_FOREGROUND` | Foreground Color | +| `--match.foreground="212"` | `$GUM_FILTER_MATCH_FOREGROUND` | Foreground Color | +| `--prompt.foreground="240"` | `$GUM_FILTER_PROMPT_FOREGROUND` | Foreground Color | +| `--limit=1` | - | Maximum number of options to pick | +| `--no-limit` | - | Pick unlimited number of options (ignores limit) | +| `--select-if-one` | - | Select the given option if there is only one | +| `--[no-]strict` | - | Only returns if anything matched. Otherwise return Filter | + +**Example**: +Use fuzzy matching to filter a list of values: +```shell +echo Strawberry >> flavors.txt +echo Banana >> flavors.txt +echo Cherry >> flavors.txt +cat flavors.txt | gum filter > selection.txt +``` + +### gum format +Format a string using a template +Usage: `gum format [