Creating Scripts

Step-by-step guide to creating new scripts using the template

Learn how to create new scripts quickly using the provided template. The template includes all the standard features and best practices built-in.

Using the Script Template

The fastest way to create a new script is to use the script template located at ~/workspace/source/templates/script-template.sh.

1. Copy the template

   Copy the template to your desired location and give it a meaningful name:

   cp templates/script-template.sh my-script.sh
   
2. Make it executable

   Set the executable permission on your new script:

   chmod +x my-script.sh
   
3. Customize the header

   Update the header section with your script’s information:

   #!/bin/bash
   # my-script.sh - Brief description of what this script does
   #
   # Usage:
   #   ./my-script.sh [OPTIONS] [ARGS]
   #
   # Options:
   #   -h, --help      Show this help message
   #   -d, --debug     Enable debug mode
   #   -v, --verbose   Verbose output
   #
   # Examples:
   #   ./my-script.sh
   #   ./my-script.sh --debug
   
4. Update the help function

   Customize the show_help() function with your script’s details:

   show_help() {
     cat << EOF
   ${BOLD}${CYAN}my-script.sh${NC} - Brief description
   
   ${BOLD}USAGE:${NC}
     ./my-script.sh [OPTIONS] [ARGS]
   
   ${BOLD}OPTIONS:${NC}
     ${GREEN}-h, --help${NC}      Show this help message
     ${GREEN}-d, --debug${NC}     Enable debug mode (dry-run)
     ${GREEN}-v, --verbose${NC}   Verbose output
   
   ${BOLD}EXAMPLES:${NC}
     ${DIM}# Basic usage${NC}
     ./my-script.sh
     
     ${DIM}# Debug mode${NC}
     ./my-script.sh --debug
   
   ${BOLD}DESCRIPTION:${NC}
     Add a longer description here explaining what your script does,
     its purpose, and any important details users should know.
   
   EOF
     exit 0
   }
   
5. Add your logic

   Replace the placeholder code in the main() function with your actual logic:

   main() {
     log "Starting script..."
     
     # Your code here
     
     if [[ $DEBUG -eq 1 ]]; then
       debug "Debug mode enabled"
       warning "This is a dry-run, no changes will be made"
       # Show what would happen
     else
       # Do actual work
       success "Task completed successfully"
     fi
   }
   
6. Test your script

   Test the script for syntax errors and functionality:

   # Check syntax
   bash -n my-script.sh
   
   # Test with debug mode
   ./my-script.sh --debug
   
   # Run the script
   ./my-script.sh
   

Template Features

The script template comes with several built-in features:

Color-Coded Output

Predefined color constants for consistent output:

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
MAGENTA='\033[0;35m'
CYAN='\033[0;36m'
BOLD='\033[1m'
DIM='\033[2m'
NC='\033[0m' # No Color

Logging Functions

Ready-to-use logging functions for different message types:

log "Processing file..."           # Blue info message
success "File processed"            # Green success with checkmark
error "Failed to read file"         # Red error with X
warning "File size is large"        # Yellow warning
debug "Variable value: $VAR"        # Dim debug message (only in debug mode)

Error Handling

The template uses set -eo pipefail for robust error handling:

set -eo pipefail
# -e: Exit immediately if any command fails
# -o pipefail: Return exit code of first failed command in pipeline

Argument Parsing

Built-in argument parsing with common options:

while [[ $# -gt 0 ]]; do
  case $1 in
    -h|--help)
      show_help
      ;;
    -d|--debug)
      DEBUG=1
      shift
      ;;
    -v|--verbose)
      VERBOSE=1
      shift
      ;;
    *)
      error "Unknown option: $1"
      echo "Use --help for usage information"
      exit 1
      ;;
  esac
done

Adding Custom Options

To add custom command-line options:

1. Add the option to the argument parsing section:

-f|--file)
  FILE="$2"
  shift 2
  ;;

2. Update the help text:

${GREEN}-f, --file${NC} <path>  Input file path

3. Add validation if needed:

if [[ -z "$FILE" ]]; then
  error "File argument is required"
  exit 1
fi

Best Practices

Start with the template - Don’t write scripts from scratch. Use the template to ensure consistency and include all standard features.

• Keep it simple - Write clear, readable code
• Add comments - Explain complex logic
• Use logging functions - Consistent, color-coded output
• Support debug mode - Allow dry-runs without side effects
• Validate inputs - Check arguments and file paths
• Handle errors - Provide helpful error messages
• Update help text - Keep documentation current

Example: Simple Backup Script

Here’s a complete example of a script created from the template:

#!/bin/bash
# backup.sh - Create timestamped backup of a directory

set -eo pipefail

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

# Configuration
DEBUG=0
SOURCE=""
DEST="/backup"

# Functions
log() { echo -e "${BLUE}ℹ${NC} $*"; }
success() { echo -e "${GREEN}✓${NC} $*"; }
error() { echo -e "${RED}✗${NC} $*" >&2; }
warning() { echo -e "${YELLOW}⚠${NC} $*"; }

# Argument parsing
while [[ $# -gt 0 ]]; do
  case $1 in
    -s|--source)
      SOURCE="$2"
      shift 2
      ;;
    -d|--dest)
      DEST="$2"
      shift 2
      ;;
    --debug)
      DEBUG=1
      shift
      ;;
    *)
      error "Unknown option: $1"
      exit 1
      ;;
  esac
done

# Main logic
main() {
  if [[ -z "$SOURCE" ]]; then
    error "Source directory required"
    exit 1
  fi
  
  TIMESTAMP=$(date +%Y%m%d_%H%M%S)
  BACKUP_FILE="$DEST/backup_$TIMESTAMP.tar.gz"
  
  log "Creating backup of $SOURCE"
  
  if [[ $DEBUG -eq 1 ]]; then
    warning "Debug mode: would create $BACKUP_FILE"
  else
    tar -czf "$BACKUP_FILE" "$SOURCE"
    success "Backup created: $BACKUP_FILE"
  fi
}

main

Next Steps

• Learn about Script Standards to understand coding conventions
• Read about Testing to validate your scripts
• Explore existing scripts in cloud/ and system/ directories for examples