PlantUML 在 git 工程里的全生命周期：pre-commit / CI / git-lfs / PR 评审

npm install --save-dev husky lint-staged
npx husky install

#!/bin/sh
# .husky/pre-commit
# 1. 校验所有 staged .puml
git diff --cached --name-only --diff-filter=ACMR -- '*.puml' | \
  xargs -I{} plantuml -checkonly {}

# 2. 校验 puml 修改后 SVG 也会改（不直接渲染，只校验 source）
for f in $(git diff --cached --name-only -- '*.puml'); do
  echo "→ checking $f"
  plantuml -checkonly "$f" || exit 1
done

#!/bin/sh
# .husky/pre-commit — 强制 puml+svg 一并提交
changed_puml=$(git diff --cached --name-only --diff-filter=ACMR -- '*.puml' | sed 's|^docs/diagrams/||;s|\.puml$||')
changed_svg=$(git diff --cached --name-only --diff-filter=ACMR -- '*.svg' | sed 's|^public/img/diagrams/||;s|\.svg$||')

missing=""
for p in $changed_puml; do
  if ! echo "$changed_svg" | grep -q "^$p$"; then
    missing="$missing $p.svg"
  fi
done

if [ -n "$missing" ]; then
  echo "❌ 修改了 puml 但 SVG 没更新: $missing"
  echo "   先跑 plantuml 渲染"
  exit 1
fi

git add docs/diagrams/auth.puml
git commit -m "改 auth 架构"
# pre-commit 阶段
# → 检测到 auth.puml 改了
# → public/img/diagrams/auth.svg 没改
# → 拒绝提交

# 修复流程
npx plantuml -tsvg docs/diagrams/auth.puml -o public/img/diagrams/
git add public/img/diagrams/auth.svg
git commit -m "改 auth 架构"
# → 通过

plantuml -tsvg docs/diagrams/*.puml
# ❌ ERROR: Diagram not supported

git lfs install
git lfs track "public/img/diagrams/*.svg"
git add .gitattributes

git lfs migrate import --include="*.svg"

# 1. pre-merge 状态渲染
git checkout main
plantuml -tsvg docs/diagrams/auth.puml -o /tmp/before/
git checkout feature-branch
plantuml -tsvg docs/diagrams/auth.puml -o /tmp/after/

# 2. 用 image-diff 工具生成 diff image
npx lookatme compare /tmp/before/auth.svg /tmp/after/auth.svg --output diff.png

git diff docs/diagrams/auth.puml
# - Alice -> Bob: hello
# + Alice -> Bob: 改 hello 为 hi

plantuml -tsvg docs/diagrams/*.puml -o public/img/diagrams/
git add public/img/diagrams/  # 重新 staged
git rebase --continue

# scripts/setup-puml-git.sh
# 在 git 项目里设置 PlantUML 环境
set -e

# 1. .gitignore
cat >> .gitignore <<EOF

# PlantUML render output - regenerated by CI
public/img/diagrams/
EOF

# 2. .gitattributes
cat > .gitattributes <<EOF
# PlantUML SVG: treat as text for diff
*.svg diff=svg merge=ours
EOF
git add .gitattributes

# 3. pre-commit hook
mkdir -p .husky
cat > .husky/pre-commit <<'EOF'
#!/bin/sh
set -e
git diff --cached --name-only --diff-filter=ACMR -- '*.puml' | \
  while IFS= read -r f; do
    echo "→ checking $f"
    plantuml -checkonly "$f" || {
      echo "❌ $f syntax error"
      exit 1
    }
  done
EOF
chmod +x .husky/pre-commit

# 4. CI workflow
mkdir -p .github/workflows
cat > .github/workflows/render.yml <<'EOF'
name: render
on: push: paths: ['docs/diagrams/**']
jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: sudo apt-get update && sudo apt-get install -y plantuml
      - run: plantuml -tsvg -thread 4 -o out/ docs/diagrams/*.puml
      - run: |
          git diff --exit-code out/ || {
            echo "图渲染了还没 commit"
            exit 1
          }
EOF

# 5. 完成
echo "✓ PlantUML git workflow 已配置"
echo ""
echo "下一步："
echo "  pre-commit hook 装了，但需要 install"
echo "  $ npx husky install"