前言
昨天看 阮老师周刊 的时候，发现一个有趣的工具──stagit，这个小工具可以从 Git 存储库生成包含 Git 信息的纯静态 HTML 网页。
特性：
- 来自 HEAD 的所有提交信息
- 每个提交的日志和 diff 统计
- 显示带有可链接行号的文件树
- 显示引用：本地分支和标签
- 检测 README 和 LICENSE 文件并生成页面
- 检测 Git 子模块并生成页面
- 生成提交日志、标签、引用的 Atom Feed
- 使用 stagit-index 为多个 Git 存储库生成索引页
限制：
- 不适合大型 Git 存储库（2000+ 提交记录）
- 不适合含有数量巨多文件的 Git 存储库
- 不适合含有大量 Git 子模块的存储库
- 不适合含有大量二进制文件的存储库
- 不适合含有代码行数数量级巨大（过万级别）的存储库
对于个人用户来说，也许您并不需要 Gitea、GitLab、Gogs 或 SourceHut 等可以自托管的 Git 服务。相反，使用 stagit 生成的静态 Git 存储库就已足够。
安装
stagit 是完全用 C 写的，在 *nix 系统上安装 GCC 编译器和 Make 构建工具
Windows 用户可以使用 WSL2
1
2
3
4
5
| # Debian/Ubuntu
sudo apt install -y gcc make
# Fedora/CentOS
sudo yum install -y gcc make
|
拉取 stagit 源码，编译安装
1
2
3
4
| git clone git://git.codemadness.org/stagit \
&& cd stagit \
&& make \
&& sudo make install
|
如果在编译的时候缺少 git2.h 头文件，出现以下报错
1
2
3
4
5
6
| cc -o stagit.o -c stagit.c -I/usr/local/include -D_XOPEN_SOURCE=700 -D_DEFAULT_SOURCE -D_BSD_SOURCE
stagit.c:15:10: fatal error: 'git2.h' file not found
#include <git2.h>
^~~~~~~~
1 error generated.
make: *** [stagit.o] Error 1
|
在 x86_64 和 ARM64/v8 的 Debian 11测试发现，Debian 上需要一些额外步骤（Fedora/CentOS 无测试）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
| # Debian 额外步骤开始
sudo apt update \
&& sudo apt install cmake libssl-dev libcurl4-gnutls-dev zlib1g-dev unzip
# 从源码开始
wget https://github.com/libgit2/libgit2/archive/refs/tags/v1.6.4.zip \
&& unzip v1.6.4.zip \
&& cd libgit2-1.6.4
vim CMakeLists.txt
# 将下面一行中的 ON 改为 OFF
option(BUILD_TESTS "Build Tests using the Clar suite" ON)
# 开始编译安装
mkdir build && cd build \
&& cmake .. \
&& cmake --build . \
&& cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local \
&& sudo cmake --build . --target install
# Debian 额外步骤结束
|
安装 libgit2 库
1
2
3
4
5
6
7
8
| # Debian/Ubuntu
sudo apt install -y libgit2-dev
# Fedora/CentOS
sudo yum install -y libgit2-devel
# macOS
brew install libgit2
|
在 macOS 使用 Homebrew 安装 libgit2，手动查看安装路径
1
2
3
4
| brew --prefix libgit2
# 输出
/opt/homebrew/opt/libgit2
|
然后编辑 stagit 的 Makefile
1
2
3
4
5
6
7
| # 修改这两行
# LIBGIT_INC = -I/usr/local/include
# LIBGIT_LIB = -L/usr/local/lib -lgit2
# 替换实际路径
LIBGIT_INC = -I/opt/homebrew/opt/libgit2/include
LIBGIT_LIB = -L/opt/homebrew/opt/libgit2/lib -lgit2
|
继续执行编译安装，然后可以用 man 查看 stagit 和 stagit-index 的用户手册
1
2
| man stagit
man stagit-index
|
我们暂时不需要掌握 stagit 和 stagit-index 的实际用法
快速上手
创建一个工作目录，专门用来生成 stagit 站点，我创建了名为 git-source 的目录，准备：
- 将 stagit 的 style.css 复制到 git-source 目录
- 创建子目录 htmldir
- 将 stagit 的 example_create.sh 和 example_post-receive.sh 到 htmldir 里
- 将您站点的 Logo 和 Favicon 图片复制到 git-source 目录下
- 创建一个 repos 目录
- 将您的 Git 存储库移动到 repos 里
Git 存储库里面的 owner 和 description 是特殊文件，用于单独显示每个存储库的所有者名称和描述，直接写入纯文本内容即可。下面是两个 Git 存储库的示例，省略了部分文件。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| .# git-source 目录（绝对路径为 /Users/dejavu/Space/git-source）
├── favicon.png
├── logo.png
├── htmldir
│ ├── example_create.sh # 生成多个 Git 存储库静态页面的脚本
│ └── example_post-receive.sh # Git 的 post-receive hook 脚本，暂且按下不表
├── repos # 包含您的 Git 存储库
│ ├── self-hosted # 存储库一，内容已省略
│ └── xvo.es # 存储库二，示例内容如下
│ ├── 404.html
│ ├── LICENSE # 存储库许可证
│ ├── owner # 存储库所有者名称
│ ├── README.md # 存储库说明
│ ├── _redirects
│ ├── description # 存储库描述
│ ├── index.html
│ ├── lists.html
│ └── vercel.json
└── style.css
|
编辑 example_create.sh，将 reposdir 的值设置为包含您的 Git 存储库的 绝对路径，比如
1
| reposdir="/Users/dejavu/Space/git-source/repos"
|
赋予脚本可执行权限
1
| chmod +x example_create.sh
|
在 git-source 下执行脚本，生成静态网页
生成的网页可以托管到任意的静态托管服务上，如 GitHub Pages、Cloudflare Pages 等。
