From b4fd89672926578c02b478592faf31605a5b2781 Mon Sep 17 00:00:00 2001 From: Maas Lalani Date: Thu, 21 Jul 2022 11:55:52 -0400 Subject: [PATCH] docs: Add a tutorial for building a script --- README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 60 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d383a81..4786574 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,66 @@ beautiful and highly configurable ready-to-use utilities. Shell running the ./demo.sh script +## Tutorial + +With Gum, you can build wonderful and useful bash scripts with just a few lines +of code. Let's build a simple script to help you write [Conventional +Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) for your +dotfiles. + +Start with a `#!/bin/bash`. +```bash +#!/bin/bash +``` + +Ask the user for the commit type with `gum choose`: + +```bash +gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert" +``` + +> Note: this command itself will print to `stdout` which is not all that useful. +To make use of the command later on you should save the stdout to a `$VARIABLE` +or `file.txt`. + +Prompt for an (optional) scope for the commit: + +```bash +gum input --placeholder "scope" +``` + +Prompt the user for a commit message: + +```bash +gum input --placeholder "Summary of this change" +``` + +Prompt for a detailed (multi-line) explanation of the changes: + +```bash +gum write --placeholder "Details of this change" +``` + +Putting it all together... + +```bash +#!/bin/bash +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. +[[ -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") + +# Commit these changes +git commit -m "$SUMMARY" -m "$DETAILS" +``` + +Running the ./examples/commit.sh script to commit to git + ## Installation Use a package manager: @@ -210,8 +270,6 @@ 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)