基于 git-archive 的项目打包

在多项目开发环境下，手动压缩往往会导致非受控文件污染。为了维持工程纯净度，git-pack 工具通过封装 Git 树对象操作，实现了从源码仓库到交付产物的原子化转换。

git-pack 工具逻辑：从源码树到标准化归档的原子化转换流

DATA CAPTURE: [HARP@DEEPIN] // 2026-03-24 13:40

配置思路

该工具通过以下三个逻辑维度实现交付物的标准化：

智能版本定位：优先检索精确匹配的 Git Tag，无 Tag 时回退至 Branch-Hash 组合，并自动处理斜杠（/）等非合法路径字符。
前缀注入与解耦：支持可选的目录前缀（Prefix），避免解压后文件散落在当前目录。
负向匹配过滤：利用 Git 的 pathspec 语法（:!）实现打包时的动态排除，确保敏感文件（如 .env）或构建产物不进入归档。

关键代码实现

1. 核心打包脚本逻辑

Source: github.com/changhorizon/git-plus/blob/main/git-pack.sh

脚本采用标准 getopts 进行参数解析。以下是处理“版本判定”与“归档流”的核心逻辑摘要：

# [Logic // 1. 智能版本/分支判定]
TAG=$(git -C "$GIT_REPO" describe --tags --exact-match 2>/dev/null || echo "")

if [[ -n "$TAG" ]]; then
    VERSION_STR="$TAG"
else
    BRANCH=$(git -C "$GIT_REPO" rev-parse --abbrev-ref HEAD)
    COMMIT_HASH=$(git -C "$GIT_REPO" rev-parse --short HEAD)

    if [[ "$BRANCH" == "HEAD" ]]; then
        VERSION_STR="$COMMIT_HASH"
    else
        # 转换分支名中的路径符号，如 feature/login -> feature-login
        SAFE_BRANCH="${BRANCH//\//-}"
        VERSION_STR="${SAFE_BRANCH}-${COMMIT_HASH}"
    fi
fi

# [Logic // 2. 执行原子化归档]
# 针对不同格式采用差异化处理流：tgz 走管道 gzip，zip 走原生 output
if [[ "$EXT" == "tar.gz" ]]; then
    git -C "$GIT_REPO" archive "${GIT_ARGS[@]}" HEAD | gzip > "$OUTPUT_PATH"
else
    git -C "$GIT_REPO" archive "${GIT_ARGS[@]}" --output "$OUTPUT_PATH" HEAD
fi

2. 全局环境挂载

通过符号链接（Symlink）将逻辑层映射至系统执行路径 /usr/local/bin，实现全系统范围内的原生调用感。

# 物理路径映射关系：
# /usr/local/bin/git-pack -> $HOME/bin/git-plus/git-pack.sh

# 安装完成后可直接调用：
# [harp@deepin]$ git pack -d . -p

3. 系统运行反馈

脚本支持静默模式（-q）与详细模式（-v）。在标准执行流下，系统会回显状态追踪以确保过程的可观测性：

[SYSTEM LOG]: Target: git-pack (Version: v2.0-main)

[PROC] Injecting prefix: git-pack/

[EXEC] Executing git tree-object traversal...

[STATUS] 0x00 Success. Artifact: ./git-pack-v2.0-main-20260324-release.zip

总结与洞察

Conclusion: git-archive 的本质是在不触碰工作区的情况下提取仓库索引。通过将分支状态、时间戳与排他性过滤逻辑进行封装，我们将繁琐的项目归档操作转化为一种可预测、可审计的系统幂等行为，实现了从单一脚本向系统扩展协议的进化。