通过 Git 生成热力贡献图并同步博客

工作原理

[!INFO]
git-stats 依赖 post-commit 钩子 在每次提交时记录数据，配合 pre-commit 钩子 自动生成图表

• post-commit 钩子：记录 commit hash、repo url、commit date 到 ~/.git-stats 数据库
• pre-commit 钩子（Husky）：每次提交后自动调用 git-stats-html 生成热力图

前置依赖

[!TIP]
以下三个 npm 包配合使用，实现从数据记录到图表生成的全流程

npm install -g git-stats git-stats-html git-stats-importer

当前安装版本：

• git-stats@3.5.0 - 核心数据库
• git-stats-html@1.0.10 - HTML 图表生成器
• git-stats-importer@2.4.13 - 历史数据导入工具

步骤一：确认 Git 邮箱

[!IMPORTANT]
git-stats 是靠邮箱来识别提交者的，请确保配置正确

git config user.email "你的邮箱"

步骤二：安装全局钩子

[!NOTE]
这一步让你的 Git 模板自动包含 post-commit 钩子，新克隆/初始化的仓库会自动获得钩子

运行 PowerShell 脚本（会自动为 D:\project 下所有 Git 仓库安装钩子）：

# 克隆或下载 Update-GitStatsHooks.ps1 后运行
.\Update-GitStatsHooks.ps1

[!TIP]
脚本会扫描指定目录下的所有 Git 项目，为其安装 post-commit 钩子

post-commit 钩子核心逻辑：

commit_hash=$(git rev-parse HEAD)
repo_url=$(git config --get remote.origin.url)
commit_date=$(git log -1 --format=%cI)
commit_data="{ \"date\": \"$commit_date\", \"url\": \"$repo_url\", \"hash\": \"$commit_hash\" }"
git-stats --record "${commit_data}"

步骤三：导入历史数据

[!NOTE]
git-stats 不会自动记录历史，需要手动导入一次

进入项目目录并执行导入：

cd D:\project\你的项目文件夹
git-stats-importer -e "你的邮箱"

[!TIP]
如果你有多个项目（公司项目、个人项目），需要分别进入每个项目目录运行此命令

步骤四：生成 HTML 图表

git-stats --raw | git-stats-html -o stats.html

步骤五：集成到 VuePress

1. 将生成的 stats.html 移动到 VuePress/public/ 目录
2. 在 Markdown 文件中使用 <iframe src="/stats.html"> 引用

步骤六：配置自动化钩子

[!TIP]
配置好 Husky 钩子后，每次提交代码会自动更新热力图

编辑 .husky/pre-commit 文件：

#!/usr/bin/env sh
# 设置终端环境变量，解决 cli-gh-cal 的 window-size 依赖问题
export COLUMNS=120
export ROWS=30

. "$(dirname -- "$0")/_/husky.sh"

echo "🔄 正在更新代码热力图..."

if command -v git-stats >/dev/null 2>&1 && command -v git-stats-html >/dev/null 2>&1; then
    if git-stats --raw | git-stats-html -o src/.vuepress/public/stats.html; then
        git add src/.vuepress/public/stats.html
        echo "✅ 代码热力图已更新"
    else
        echo "⚠️ 代码热力图生成失败，请检查 git-stats 配置"
    fi
else
    echo "⚠️ git-stats 或 git-stats-html 未安装，跳过热力图更新"
fi

避坑指南

[!WARNING]
全局统计：git-stats 的图表永远是你所有项目的总和，无法生成"仅当前项目"的热力图

[!WARNING]
数据持久化：数据库文件在 ~/.git-stats，重装系统后需重新运行步骤三恢复数据

[!WARNING]
邮箱匹配：如果提交记录有多个邮箱，需分别运行 git-stats-importer -e "邮箱A" 和 git-stats-importer -e "邮箱B"

[!WARNING]
VSCode 提交报错：git-stats 依赖的 window-size 模块在非 TTY 环境下会返回 undefined，导致报错 Cannot read properties of undefined (reading 'width')

解决方案：在 pre-commit 钩子中设置环境变量

[!IMPORTANT]
Husky 通过 Git Bash (sh) 执行钩子脚本，修改 .ps1 或 .cmd shim 文件对 Husky 无效，因为 Git Bash 不会解析这些文件。

在 .husky/pre-commit 的 #!/usr/bin/env sh 下方添加：

export COLUMNS=120
export ROWS=30

这种方式确保无论通过何种路径调用 git-stats，环境变量都已就位。