- 所有文章/
使用 stagit 自托管纯静态 Git 存储库
本文目录
前言 #
昨天看 阮老师周刊 的时候，发现一个有趣的工具──stagit，这个小工具可以从 Git 存储库生成包含 Git 信息的纯静态 HTML 网页。
特性：
- 来自 HEAD 的所有提交信息
- 每个提交的日志和 diff 统计
- 显示带有可链接行号的文件树
- 显示引用：本地分支和标签
- 检测 README 和 LICENSE 文件并生成页面
- 检测 Git 子模块并生成页面
- 生成提交日志、标签、引用的 Atom Feed
- 使用 stagit-index 为多个 Git 存储库生成索引页
限制：
- 不适合大型 Git 存储库（2000+ 提交记录）
- 不适合含有数量巨多文件的 Git 存储库
- 不适合含有大量 Git 子模块的存储库
- 不适合含有大量二进制文件的存储库
- 不适合含有代码行数数量级巨大1（过万级别）的存储库
对于个人用户来说，也许您并不需要 Gitea、GitLab、Gogs 或 SourceHut2 等可以自托管的 Git 服务。相反，使用 stagit 生成的静态 Git 存储库就已足够。
安装 #
stagit 是完全用 C 写的，在 *nix 系统上安装 GCC 编译器和 Make 构建工具
Windows 用户可以使用 WSL2
# Debian/Ubuntu
sudo apt install -y gcc make
# Fedora/CentOS
sudo yum install -y gcc make
拉取 stagit 源码，编译安装
git clone git://git.codemadness.org/stagit \
&& cd stagit \
&& make \
&& sudo make install
如果在编译的时候缺少 git2.h 头文件，出现以下报错
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 无测试）
# 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 库
# Debian/Ubuntu
sudo apt install -y libgit2-dev
# Fedora/CentOS
sudo yum install -y libgit2-devel
# macOS
brew install libgit2
在 macOS 使用 Homebrew 安装 libgit2，手动查看安装路径
brew --prefix libgit2
# 输出
/opt/homebrew/opt/libgit2
然后编辑 stagit 的 Makefile
# 修改这两行
# 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 的用户手册
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 目录下3
- 创建一个 repos 目录
- 将您的 Git 存储库移动到 repos 里
Git 存储库里面的 owner 和 description 是特殊文件，用于单独显示每个存储库的所有者名称和描述，直接写入纯文本内容即可。下面是两个 Git 存储库的示例，省略了部分文件。
.# 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 存储库的 绝对路径，比如
reposdir="/Users/dejavu/Space/git-source/repos"
赋予脚本可执行权限
chmod +x example_create.sh
在 git-source 下执行脚本，生成静态网页
./htmldir/build-git.sh
生成的网页可以托管到任意的静态托管服务上，如 GitHub Pages、Cloudflare Pages 等。
