Jamie-BitFlight/bash-logging

Bash 日誌系統

為 Bash 腳本提供結構化日誌模式，支援彩色輸出、表情符號圖示以及 CI/CD 整合。

基礎日誌函式

簡單、可攜的日誌實作：

# 顏色定義
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]='🐛'
)

# 日誌函式
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]}"
}

日誌層級

實作可設定的日誌層級。

程式碼範例

TTY 偵測

在非互動式環境中停用色彩：

setup_colors() {
    if [[ -t 1 ]] && [[ -z "${NO_COLOR:-}" ]]; then
        # 終端機支援色彩
        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
        # 無色彩支援
        COLOR_RED=''
        COLOR_GREEN=''
        COLOR_YELLOW=''
        COLOR_BLUE=''
        COLOR_RESET=''
    fi
}

# CI 環境通常支援色彩
detect_color_support() {
    if [[ -n "${CI:-}" ]] || [[ -n "${GITLAB_CI:-}" ]] || [[ -n "${GITHUB_ACTIONS:-}" ]]; then
        return 0  # CI 環境，啟用色彩
    elif [[ -t 1 ]]; then
        return 0  # 終端機，啟用色彩
    else
        return 1  # 無色彩支援
    fi
}

GitLab CI 可折疊區段

在 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
}

# 使用範例
section_start "build" "建置應用程式"
make build
section_end "build"

GitHub Actions 群組

程式碼範例

進度指示器

程式碼範例

結構化步驟日誌

程式碼範例

Shlocksmith 日誌函式庫

如需完整的日誌功能並與 CI 深度整合，請使用 shlocksmith 日誌函式庫。

特色

• 超過 20 個日誌層級函式（log_info、log_error、log_warning 等）
• 基於步驟的日誌（log_step_start、log_step_pass、log_step_fail）
• 色彩與表情符號支援，附 TTY 偵測
• GitLab CI 區段管理
• 用於 TUI 的方框繪製字元
• 鍵值對格式化

可用函式

# 基礎日誌
log_info "資訊訊息"
log_warning "警告訊息"
log_error "錯誤訊息"
log_debug "除錯訊息"  # 僅在設定 DEBUG 時顯示
log_notice "通知訊息"
log_fatal "致命錯誤"    # 結束腳本

# 基於步驟的日誌
log_start "程序名稱"
log_step_start "步驟說明"
log_step_pass "成功訊息"
log_step_fail "失敗訊息"
log_step_skip "跳過訊息"
log_step_done "完成訊息"
log_done "程序完成"

# 結果
log_pass "測試通過"
log_fail "測試失敗"
log_result "結果詳細資訊"
log_success "成功訊息"

# CI 區段
section_start "section_id" "區段標題"
section_end "section_id"

使用範例

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

log_start "部署流程"

section_start "deps" "安裝依賴項目"
log_step_start "安裝套件中"
if apt-get install -y package; then
    log_step_pass "套件安裝完成"
else
    log_step_fail "套件安裝失敗"
fi
section_end "deps"

log_done "部署完成"

其他資源

腳本

• log_functions.sh - 完整的 shlocksmith 日誌函式庫

顏色參考

代碼	顏色
\033[0;30m	黑色
\033[0;31m	紅色
\033[0;32m	綠色
\033[0;33m	黃色
\033[0;34m	藍色
\033[0;35m	洋紅色
\033[0;36m	青色
\033[0;37m	白色
\033[1;XXm	粗體變體
\033[0m	重設