syncmac.sh

#!/bin/bash
#
# syncmac - 个人文件同步工具
# ========================================
#
# 使用 rsync 在本地和网络位置之间同步文件。
#
# @author       Hao Feng (F1)
# @copyright    2020-2026, RDS
# @license      Internal use only
# @version      2.1.5
# @link         https://github.com/example/syncmac (示例链接)
#

#===============================================================================
# 版本历史 (VERSION HISTORY)
#===============================================================================
#
# v2.1.0 (2026-04-04)
#   【kernel 核心数据备份功能完善与修复】
#   - 新增：kernel 组合目标，包含 dotfiles/research/init/work/doc/pictures/music/library
#   - 新增：kernel_dotfiles 目标（仅同步 dot 配置文件）
#   - 新增：kernel_library 目标排除 Docker 容器目录（Containers/com.docker.docker）
#   - 修复：配置解析逻辑支持多行排除规则（parameter expansion 替代 read 命令）
#   - 修复：两字段配置解析错误（目标路径被误认为排除规则）
#   - 修复：kernel_dotfiles 源路径尾斜杠问题，确保 include/exclude 规则生效
#   - 修复：排除规则格式（去掉 / 前缀以匹配 rsync 路径匹配行为）
#   - 增强：rsync 退出状态码检查和错误报告
#   - 增强：DOTFILES 模式自动排除临时目录（.Trash, .cache, .venv, .DS_Store 等）
#
# v2.0.0 (2026-03-01)
#   - 重构：消除代码重复，实现数据驱动的配置管理
#   - 新增：-h/--help, -n/--dry-run, -q/--quiet, -v/--verbose 选项
#   - 新增：依赖检查和路径验证
#   - 修复：删除重复的 syn_rds 函数
#   - 修复：修正 "syncronize" 拼写错误为 "synchronize"
#   - 修复：移除 opt=$opt 无效赋值
#   - 兼容：使用 bash 3.2 兼容的 case 语句
#
# v1.0.0 (2020-11-18)
#   - 初始版本
#   - 支持本地和网络同步
#   - 支持多种预定义目标
#
#===============================================================================
# 用法说明 (USAGE)
#===============================================================================
#
# 基本用法：
#   ./syncmac [-h] [-n] [-q] [-v] -tgt <target> [-from <source>] [-to <destination>]
#
# 通过别名使用（推荐）：
#   (sb | syncmac-backup)   [-n] [-q] [-v] -tgt <target>   # 备份模式
#   (sr | syncmac-restore)  [-n] [-q] [-v] -tgt <target>   # 恢复模式
#
# 别名说明：
#   sb, syncmac-backup  - 从 ~/Users 同步到 /Volumes/BACKUP/MAC（备份）
#   sr, syncmac-restore - 从 /Volumes/BACKUP/MAC 同步到 ~/Users（恢复）
#   sbr                 - 通过互联网备份
#   srr                 - 通过互联网恢复
#   sbri                - 通过局域网备份
#   srri                - 通过局域网恢复
#
# 目标列表 (TARGETS):
#
#   组合目标：
#       day    - bin, startup, rds（默认）
#       all    - feng, app, brew, opt, movie, journal, teach, elib
#       aba    - kernel, elib, movie, teach, app
#       vmware - win, linux
#       src    - app, brew
#       kernel - dotfiles, research, init, work, doc, pictures, music, library (不含 Caches)
#
#   单个目标：
#       feng   - ~/(排除 Trash/cache/venv)
#       hao    - ~/(排除 ~/Library 缓存和移动同步)
#       rds    - ~/Documents/RDS
#       bin    - ~/Work/home1/feng/BIN
#       startup- ~/Work/Company/STARTUP
#       cityu  - ~/Work/CityU
#       work   - ~/Work
#       doc    - ~/Documents
#       study  - ~/Documents/STUDY
#       tmp    - ~/Documents/temp
#       app    - /APP_SOURCE
#       brew   - Homebrew 缓存
#       opt    - /opt
#       movie  - /Movies
#       journal- /JOURNALS
#       teach  - /Teaching
#       elib   - /RDS Library
#       win    - VMware Windows 虚拟机
#       linux  - VMware Linux 虚拟机
#
# 选项 (OPTIONS):
#   -h, --help     显示此帮助信息
#   -n, --dry-run  预演模式，显示将要执行的操作但不实际运行
#   -q, --quiet    安静模式，减少输出信息
#   -v, --verbose  详细模式，显示更多调试信息
#   -tgt <target>  指定同步目标
#   -from <path>   源路径（可选，默认取决于调用方式）
#   -to <path>     目标路径（可选，默认取决于调用方式）
#
# 示例 (EXAMPLES):
#   # 查看帮助
#   ./syncmac -h
#
#   # 预演模式测试同步
#   ./syncmac -n -tgt bin
#
#   # 详细模式同步单个目录
#   ./syncmac -v -tgt tmp
#
#   # 使用别名备份
#   ./syncmac-backup -tgt day
#
#   # 使用别名恢复
#   ./syncmac-restore -tgt doc
#
#   # 安静模式同步
#   ./syncmac -q -tgt work
#
#===============================================================================

#-------------------------------------------------------------------------------
# 配置常量 (CONFIGURATION)
#-------------------------------------------------------------------------------

# 默认用户配置
DEFAULT_HOME="fengh"           # 默认用户名
DEFAULT_UDIR="/Users"          # 用户目录根路径
DEFAULT_UDISK="/Volumes/BACKUP/MAC"  # 备份磁盘挂载点

# 网络地址配置
PRO_LAN="192.168.2.51"         # 局域网 IP
PRO_INTERNET="183.223.218.11"  # 互联网 IP

# rsync 默认选项
# -a: 归档模式（保留权限、时间戳等）
# -l: 保留符号链接
# -v: 详细输出
# -z: 压缩传输
# -r: 递归
# -t: 保留时间戳
# -o: 保留所有者
# -p: 保留权限
# -g: 保留组
# --progress: 显示进度
# --delete: 删除目标中多余的文件
DEFAULT_RSYNC_OPTS="-alvzrtopg --progress --delete"

#-------------------------------------------------------------------------------
# 工具函数 (UTILITY FUNCTIONS)
#-------------------------------------------------------------------------------

# 错误退出函数
# 用法: die "错误消息"
die() {
    echo "ERROR: $*" >&2
    exit 1
}

# 警告消息函数
# 用法: warn "警告消息"
warn() {
    echo "WARNING: $*" >&2
}

# 信息输出函数（受安静模式影响）
# 用法: info "信息消息"
info() {
    if [[ "$QUIET" != "true" ]]; then
        echo "$*"
    fi
}

# 详细输出函数（仅在详细模式下显示）
# 用法: verbose "调试信息"
verbose() {
    if [[ "$VERBOSE" == "true" ]]; then
        echo "$*" >&2
    fi
}

#-------------------------------------------------------------------------------
# 依赖检查和验证 (DEPENDENCY & VALIDATION)
#-------------------------------------------------------------------------------

# 检查必需的依赖
# 验证 rsync 是否可用
check_dependencies() {
    if ! command -v rsync >/dev/null 2>&1; then
        die "rsync not found. Please install rsync first."
    fi
}

# 验证源路径存在（仅本地路径）
# 用法: validate_source "$source_path"
validate_source() {
    local src="$1"

    # 远程源跳过验证
    if [[ "$src" =~ @.*: ]]; then
        verbose "Remote source detected, skipping validation: $src"
        return 0
    fi

    if [[ ! -e "$src" ]]; then
        die "Source path does not exist: $src"
    fi

    verbose "Source path validated: $src"
}

#-------------------------------------------------------------------------------
# 目标配置查找 (TARGET CONFIGURATION LOOKUP)
#-------------------------------------------------------------------------------

# 获取目标配置
# 返回格式: source_path|destination_path|excludes
# 用法: get_target_config "target_name"
get_target_config() {
    local target="$1"

    case "$target" in
        bin)
            echo "$home/Work/home1/feng/BIN|$home/Work/home1/feng"
            ;;
        cityu)
            echo "$home/Work/CityU|$home/Work"
            ;;
        startup)
            echo "$home/Work/Company/STARTUP|$home/Work/Company"
            ;;
        tmp)
            echo "$home/Documents/temp|$home/Documents"
            ;;
        work)
            echo "$home/Work|$home"
            ;;
        doc)
            echo "$home/Documents|$home"
            ;;
        study)
            echo "$home/Documents/STUDY|$home"
            ;;
        rds)
            echo "$home/Documents/RDS|$home/Documents"
            ;;
        app)
            echo "APP_SOURCE|"
            ;;
        brew)
            echo "$home/Library/Caches/Homebrew|$home/Library/Caches"
            ;;
        opt)
            echo "opt|"
            ;;
        movie)
            echo "Movies|"
            ;;
        journal)
            echo "JOURNALS|"
            ;;
        teach)
            echo "Teaching|"
            ;;
        elib)
            echo "RDS Library|"
            ;;
        feng)
            # 排除垃圾文件、缓存和虚拟环境
            echo "$home||.Trash .cache .venv"
            ;;
        hao)
            # 排除库缓存、同步数据和临时文件
            echo "$home||Library/Application Support/Caches"$'\n'"Library/Application Support/CrashReporter"$'\n'"Library/Application Support/LarkShell"$'\n'"Library/Application Support/MobileSync"$'\n'"Library/Application Support/XiYou"$'\n'"Library/Caches"$'\n'"Library/Containers"$'\n'"Library/Group Containers"$'\n'"Library/Trial"$'\n'".SynologyDrive"$'\n'".Trash"$'\n'".venv"$'\n'".cache"
            ;;
        #-----------------------------------------------------------------------
        # VMware 虚拟机目标
        #-----------------------------------------------------------------------
        win)
            echo "Shared/Windows.vmwarevm|Shared"
            ;;
        linux)
            echo "Shared/Ubuntu.vmwarevm|Shared"
            ;;
        #-----------------------------------------------------------------------
        # kernel 核心数据备份目标（v2.1.0 新增）
        #-----------------------------------------------------------------------
        kernel_dotfiles)
            # 仅同步 home 目录下的 dot 文件（以点开头的配置文件）
            # DOTFILES 是特殊标记，由 sync_target 函数处理为：
            #   --include='.*/' --include='.*/**' --include='.*' --exclude='*'
            # 这确保只同步 .vimrc, .bashrc, .gitconfig 等配置文件
            # 源路径带尾斜杠以确保 include/exclude 规则正确应用于目录内容
            echo "$home/|$home|DOTFILES"
            ;;
        kernel_research)
            # 同步 Research 研究目录
            echo "$home/Research|$home"
            ;;
        kernel_init)
            # 同步 Init 初始化配置目录
            echo "$home/Init|$home"
            ;;
        kernel_work)
            # 同步 Work 工作目录
            echo "$home/Work|$home"
            ;;
        kernel_doc)
            # 同步 Documents 文档目录
            echo "$home/Documents|$home"
            ;;
        kernel_pictures)
            # 同步 Pictures 图片目录
            echo "$home/Pictures|$home"
            ;;
        kernel_music)
            # 同步 Music 音乐目录
            echo "$home/Music|$home"
            ;;
        kernel_library)
            # 同步 Library 库目录，排除以下目录：
            #   - Caches              缓存目录
            #   - Application Support/MobileSync  移动同步目录
            #   - Containers/com.docker.docker     Docker 容器目录
            echo "$home/Library|$home|Caches"$'\n'"Application Support/MobileSync"$'\n'"Containers/com.docker.docker"
            ;;
        #-----------------------------------------------------------------------
        # 默认情况
        #-----------------------------------------------------------------------
        *)
            echo ""
            ;;
    esac
}

# 获取组合目标的子目标列表
# 返回格式: 空格分隔的目标名称
# 用法: get_composite_target "composite_name"
get_composite_target() {
    local target="$1"

    case "$target" in
        day)
            echo "bin startup rds"
            ;;
        all)
            echo "feng app brew opt movie journal teach elib"
            ;;
        aba)
            echo "kernel elib movie teach app"
            ;;
        vmware)
            echo "win linux"
            ;;
        src)
            echo "app brew"
            ;;
        #-----------------------------------------------------------------------
        # kernel 核心数据备份组合目标（v2.1.0 新增）
        # 包含：dotfiles, research, init, work, doc, pictures, music, library
        #-----------------------------------------------------------------------
        kernel)
            echo "kernel_dotfiles kernel_research kernel_init kernel_work kernel_doc kernel_pictures kernel_music kernel_library"
            ;;
        *)
            echo ""
            ;;
    esac
}

# 检查目标是否有效
# 用法: is_valid_target "target_name"
# 返回: 0=有效, 1=无效
is_valid_target() {
    local target="$1"
    local config
    config=$(get_target_config "$target")

    if [[ -n "$config" ]]; then
        return 0
    fi

    local composite
    composite=$(get_composite_target "$target")

    if [[ -n "$composite" ]]; then
        return 0
    fi

    return 1
}

#-------------------------------------------------------------------------------
# 选项处理 (OPTION HANDLING)
#-------------------------------------------------------------------------------

# 处理命令行选项
# 解析并设置所有配置变量和运行时选项
# 用法: handle_opt "$@"
handle_opt() {
    # 设置默认值
    home="$DEFAULT_HOME"
    udir="$DEFAULT_UDIR"
    udisk="$DEFAULT_UDISK"
    opt="$DEFAULT_RSYNC_OPTS"
    tgt="day"           # 默认目标
    from=""
    to=""

    # 解析命令行选项
    while [[ $# -gt 0 ]]; do
        case "$1" in
            -h|--help)
                show_help
                exit 0
                ;;
            -n|--dry-run)
                DRY_RUN="true"
                ;;
            -q|--quiet)
                QUIET="true"
                ;;
            -v|--verbose)
                VERBOSE="true"
                ;;
            -tgt)
                tgt="$2"
                shift 2
                continue
                ;;
            -opt)
                opt="$2"
                shift 2
                continue
                ;;
            -from)
                from="$2"
                shift 2
                continue
                ;;
            -to)
                to="$2"
                shift 2
                continue
                ;;
            *)
                warn "Unknown option: $1"
                ;;
        esac
        shift
    done

    # 设置默认的 from/to 路径
    if [[ -z "$from" ]]; then
        from="$udir"
    fi

    if [[ -z "$to" ]]; then
        to="$udisk"
    fi

    # 根据脚本名称确定运行模式
    local runname
    runname=$(basename "$0")

    case "$runname" in
        syncmac-backup|sb|sbs)
            # 备份模式：从用户目录到备份磁盘
            from="$udir"
            to="$udisk"
            ;;
        syncmac-restore|sr|srs)
            # 恢复模式：从备份磁盘到用户目录
            from="$udisk"
            to="$udir"
            ;;
        sbr)
            # 通过互联网备份
            from="$udir"
            to="$home@$PRO_INTERNET:$udir"
            ;;
        srr)
            # 通过互联网恢复
            from="$home@$PRO_INTERNET:$udir"
            to="$udir"
            ;;
        sbri)
            # 通过局域网备份
            from="$udir"
            to="$home@$PRO_LAN:$udir"
            ;;
        srri)
            # 通过局域网恢复
            from="$home@$PRO_LAN:$udir"
            to="$udir"
            ;;
    esac

    # 构建 rsync 命令
    if [[ "$DRY_RUN" == "true" ]]; then
        RSYNC_CMD="echo rsync $opt --dry-run"
    else
        RSYNC_CMD="rsync $opt"
    fi

    # 显示配置信息
    info "$0 -tgt $tgt -from $from -to $to"
    if [[ "$DRY_RUN" == "true" ]]; then
        info "DRY RUN MODE - No actual changes will be made"
    fi
    info ""
}

#-------------------------------------------------------------------------------
# 帮助信息 (HELP MESSAGE)
#-------------------------------------------------------------------------------

# 显示帮助信息
# 从脚本头部的注释中提取并显示用法说明
show_help() {
    grep -A 100 '^# 用法说明' "$0" | grep -B 100 '^#===' | sed 's/^# //' | sed 's/^#//'
}

#-------------------------------------------------------------------------------
# 同步功能 (SYNCHRONIZATION FUNCTIONS)
#-------------------------------------------------------------------------------

# 同步单个目标
# 根据目标配置执行 rsync 同步
# 用法: sync_target "target_name"
sync_target() {
    local name="$1"
    local config
    config=$(get_target_config "$name")

    # 解析配置: source|destination|includes|excludes 或 source|destination|excludes
    # 注意：配置可能包含换行符（排除规则列表），需要特殊处理
    local src_path dst_path includes excludes rest
    # 使用 parameter expansion 分割前两个字段
    src_path="${config%%|*}"
    rest="${config#*|}"
    dst_path="${rest%%|*}"
    rest="${rest#*|}"
    # 剩余部分可能是 includes 或 excludes（包含换行符的列表）
    # 但如果 rest 等于 dst_path，说明配置只有两个字段，没有 includes/excludes
    if [[ "$rest" == "$dst_path" ]]; then
        includes=""
        excludes=""
    else
        includes="$rest"
        excludes=""
    fi

    # 兼容旧格式：如果 excludes 为空且 includes 不为空，则 includes 实际上是 excludes
    # 排除 DOTFILES 特殊标记和仅包含通配符的 include 规则
    if [[ -z "$excludes" ]] && [[ -n "$includes" ]] && [[ "$includes" != "DOTFILES" ]]; then
        excludes="$includes"
        includes=""
    fi

    # 构建完整源路径
    local full_src
    if [[ "$src_path" =~ ^/ ]]; then
        # 绝对路径：从 $from 开始
        full_src="$from${src_path}"
    else
        # 相对路径
        full_src="$from/$src_path"
    fi

    # 为 DOTFILES 模式确保源路径有尾斜杠，使 include/exclude 规则正确应用于目录内容
    if [[ "$includes" == "DOTFILES" ]] && [[ ! "$full_src" =~ /$ ]]; then
        full_src="$full_src/"
    fi

    # 构建完整目标路径
    local full_dst
    if [[ -z "$dst_path" ]]; then
        # 无相对路径，直接使用 $to
        full_dst="$to"
    elif [[ "$dst_path" =~ ^/ ]]; then
        # 绝对路径：从 $to 开始
        full_dst="$to${dst_path}"
    else
        # 相对路径
        full_dst="$to/$dst_path"
    fi

    info " → Synchronizing: $name"
    verbose "   Source: $full_src"
    verbose "   Destination: $full_dst"

    # 构建 include 和 exclude 参数
    local filter_args=""

    #-----------------------------------------------------------------------
    # DOTFILES 特殊模式处理（v2.1.0 新增，v2.1.2 增强支持排除规则）
    #-----------------------------------------------------------------------
    # 当 includes 为 "DOTFILES" 时，使用特殊的 rsync 规则只同步 dot 文件
    # 这些规则确保：
    #   1. .*/  - 包含所有隐藏目录（如 .ssh, .config）
    #   2. .*/** - 包含隐藏目录下的所有内容（递归）
    #   3. .*   - 包含所有隐藏文件（如 .vimrc, .bashrc）
    #   4. 排除所有其他文件
    # 如果有排除规则（excludes），会在 DOTFILES 规则之后添加，以排除特定目录
    #-----------------------------------------------------------------------
    if [[ "$includes" == "DOTFILES" ]]; then
        # DOTFILES 基础规则：只同步隐藏文件和目录
        filter_args="--include='.*/' --include='.*/**' --include='.*' --exclude='*'"
        # 添加常见的不需要同步的隐藏文件/目录排除规则（避免 rsync 错误）
        filter_args="$filter_args --exclude='.Trash/' --exclude='.cache/' --exclude='.venv/'"
        filter_args="$filter_args --exclude='.DS_Store' --exclude='.localized'"
        # 邮件客户端和同步软件的临时文件
        filter_args="$filter_args --exclude='.Mail/' --exclude='.mbsync/' --exclude='.SynologyDrive/'"
    elif [[ -n "$includes" ]]; then
        # 使用换行符分隔包含项，以支持包含空格的路径
        local old_ifs="$IFS"
        IFS=$'\n'
        set -f
        for inc in $includes; do
            filter_args="$filter_args --include=\"$inc\""
        done
        set +f
        IFS="$old_ifs"
        filter_args="$filter_args --exclude=\"*\""
    fi

    # 如果有 exclude 规则，添加 --exclude
    # 使用换行符分隔排除项，以支持包含空格的路径
    if [[ -n "$excludes" ]]; then
        local old_ifs="$IFS"
        IFS=$'\n'
        for excl in $excludes; do
            filter_args="$filter_args --exclude=\"$excl\""
        done
        IFS="$old_ifs"
    fi

    # 执行 rsync 命令并捕获退出状态
    eval "$RSYNC_CMD $filter_args \"$full_src\" \"$full_dst\""
    local rsync_exit=$?

    # 处理 rsync 退出状态码
    # 0 = 成功, 23 = 部分文件传输错误（非致命）, 24 = 部分文件传输错误（致命）
    # 其他 = 错误
    if [[ $rsync_exit -eq 23 ]]; then
        warn "rsync: some files could not be transferred (code 23)"
    elif [[ $rsync_exit -ne 0 ]] && [[ $rsync_exit -ne 24 ]]; then
        # 24 也是部分错误，但通常是严重的
        warn "rsync: exit code $rsync_exit"
    fi
}

# 运行组合目标（包含多个子目标）
# 递归执行所有子目标
# 用法: run_composite_target "composite_name"
run_composite_target() {
    local name="$1"
    local targets
    targets=$(get_composite_target "$name")

    info " → Running composite target: $name"
    info ""

    for sub_target in $targets; do
        local config
        config=$(get_target_config "$sub_target")

        if [[ -n "$config" ]]; then
            # 单个目标
            sync_target "$sub_target"
        else
            local composite
            composite=$(get_composite_target "$sub_target")
            if [[ -n "$composite" ]]; then
                # 嵌套的组合目标
                run_composite_target "$sub_target"
            else
                warn "Unknown sub-target in composite: $sub_target"
            fi
        fi
    done
}

#-------------------------------------------------------------------------------
# 主程序 (MAIN EXECUTION)
#-------------------------------------------------------------------------------

# 主函数
# 执行完整的同步流程
# 用法: main "$@"
main() {
    # 1. 检查依赖
    check_dependencies

    # 2. 处理命令行选项
    handle_opt "$@"

    # 3. 验证目标有效性
    if ! is_valid_target "$tgt"; then
        die "Unknown target: '$tgt'. Use -h to see available targets."
    fi

    # 4. 验证源路径（本地路径）
    validate_source "$from"

    # 5. 执行同步
    local config
    config=$(get_target_config "$tgt")

    if [[ -n "$config" ]]; then
        # 单个目标
        sync_target "$tgt"
    else
        # 组合目标
        run_composite_target "$tgt"
    fi

    # 6. 完成提示
    info ""
    info "Synchronization complete."
}

# 程序入口点
main "$@"