jamie-bitflight/bash-logging

Bash Logging

Structured logging patterns for bash scripts with color support, emoji icons, and CI/CD integration.

Basic Logging Functions

Simple, portable logging implementation:

# Color definitions
declare -A colors=(
    [green]=$'\033[0;32m'
    [red]=$'\033[0;31m'
    [yellow]=$'\033[1;33m'
    [blue]=$'\033[0;34m'
    [reset]=$'\033[0m'
)

declare -A emojis=(
    [success]='✅'
    [error]='❌'
    [warning]='⚠️'
    [info]='ℹ️'
    [debug]='🐛'
)

# Logging functions
print_success() {
    printf '%b %b%b%b\n' "${emojis[success]}" "${colors[green]}" "$*" "${colors[reset]}"
}

print_error() {
    printf '%b %b%b%b\n' "${emojis[error]}" "${colors[red]}" "$*" "${colors[reset]}" >&2
}

print_warning() {
    printf '%b %b%b%b\n' "${emojis[warning]}" "${colors[yellow]}" "$*" "${colors[reset]}"
}

print_info() {
    printf '%b %b\n' "${emojis[info]}" "$*"
}

print_debug() {
    [[ -n "${DEBUG:-}" ]] && printf '%b %b%b%b\n' "${emojis[debug]}" "${colors[blue]}" "$*" "${colors[reset]}"
}

Log Levels

Implement configurable log levels.

Code examples

TTY Detection

Disable colors in non-interactive environments:

setup_colors() {
    if [[ -t 1 ]] && [[ -z "${NO_COLOR:-}" ]]; then
        # Terminal supports colors
        COLOR_RED=$'\033[0;31m'
        COLOR_GREEN=$'\033[0;32m'
        COLOR_YELLOW=$'\033[1;33m'
        COLOR_BLUE=$'\033[0;34m'
        COLOR_RESET=$'\033[0m'
    else
        # No color support
        COLOR_RED=''
        COLOR_GREEN=''
        COLOR_YELLOW=''
        COLOR_BLUE=''
        COLOR_RESET=''
    fi
}

# CI environments often support colors
detect_color_support() {
    if [[ -n "${CI:-}" ]] || [[ -n "${GITLAB_CI:-}" ]] || [[ -n "${GITHUB_ACTIONS:-}" ]]; then
        return 0  # CI environment, enable colors
    elif [[ -t 1 ]]; then
        return 0  # Terminal, enable colors
    else
        return 1  # No color support
    fi
}

GitLab CI Collapsible Sections

Create collapsible log sections in GitLab CI:

section_start() {
    local section_key="\${1:-section}"
    local section_header="\${2:-$section_key}"
    local collapsed="\${3:-true}"

    if [[ -n "${GITLAB_CI:-}" ]]; then
        printf "\e[0Ksection_start:%s:%s[collapsed=%s]\r\e[0K%s\n" \
            "$(date +%s)" "$section_key" "$collapsed" "$section_header"
    else
        printf '\n=== %s ===\n' "$section_header"
    fi
}

section_end() {
    local section_key="\${1:-section}"

    if [[ -n "${GITLAB_CI:-}" ]]; then
        printf "\e[0Ksection_end:%s:%s\r\e[0K" "$(date +%s)" "$section_key"
    else
        printf '\n'
    fi
}

# Usage
section_start "build" "Building Application"
make build
section_end "build"

GitHub Actions Grouping

Code examples

Progress Indicators

Code examples

Structured Step Logging

Code examples

Shlocksmith Logging Library

For comprehensive logging with full CI integration, use the shlocksmith logging library.

Features

• 20+ log level functions (log_info, log_error, log_warning, etc.)
• Step-based logging (log_step_start, log_step_pass, log_step_fail)
• Color and emoji support with TTY detection
• GitLab CI section management
• Box drawing characters for TUI
• Key-value pair formatting

Available Functions

# Basic logging
log_info "Informational message"
log_warning "Warning message"
log_error "Error message"
log_debug "Debug message"  # Only shown when DEBUG is set
log_notice "Notice message"
log_fatal "Fatal error"    # Exits script

# Step-based logging
log_start "Process name"
log_step_start "Step description"
log_step_pass "Success message"
log_step_fail "Failure message"
log_step_skip "Skipped message"
log_step_done "Completion message"
log_done "Process complete"

# Results
log_pass "Test passed"
log_fail "Test failed"
log_result "Result details"
log_success "Success message"

# CI sections
section_start "section_id" "Section Title"
section_end "section_id"

Usage

#!/usr/bin/env bash
source /path/to/log_functions.sh

log_start "Deployment Process"

section_start "deps" "Installing Dependencies"
log_step_start "Installing packages"
if apt-get install -y package; then
    log_step_pass "Packages installed"
else
    log_step_fail "Package installation failed"
fi
section_end "deps"

log_done "Deployment complete"

Additional Resources

Scripts

• log_functions.sh - Full shlocksmith logging library

Color Reference

| Code | Color | | ------------ | ------------ | | \033[0;30m | Black | | \033[0;31m | Red | | \033[0;32m | Green | | \033[0;33m | Yellow | | \033[0;34m | Blue | | \033[0;35m | Magenta | | \033[0;36m | Cyan | | \033[0;37m | White | | \033[1;XXm | Bold variant | | \033[0m | Reset |