Gitit 0.15.1.1 常用 CLI 命令与工具详解

目标：把 Gitit 运维可用的四条操作通道——gitit 主命令、expireGititCache 配套工具、wikidata Git 后端原生操作、HTTP 表单接口的 curl 操作系——逐命令、逐字段讲清并全部实测回显。适合已部署完成、要做自动化脚本或日常运维的读者；安装见《Ubuntu 24.04 安装 Gitit 0.15.1.1 指南》，参数含义见《Gitit 0.15.1.1 配置参数详解》。

一、环境信息

操作系统：Ubuntu 24.04.2 LTS (noble)，x86_64
软件：gitit 0.15.1.1+dfsg-1build3（gitit version 0.15.1.1 -plugins），git 2.43.0
服务：systemd gitit.service，WorkingDirectory=/srv/gitit/wiki，监听 0.0.0.0:8138
仓库：/srv/gitit/wiki/wikidata（实测 12 个提交、含默认页与实验页）
演示账号：admin / q1w2e3r4（会话 Cookie 文件 cookies.txt）
本文所有输出为 2026-11-01 实测回显

二、工具概览

Gitit 没有管理 REST/gRPC API，官方扩展形态是 Haskell 库（Network.Gitit）与编译期插件（apt 版未编入）；日常自动化实际可用的四条通道：

通道	载体	能做什么	本文位置
主命令	`/usr/bin/gitit`（7 个选项）	启停、端口/监听/配置控制、默认配置打印、调试	第四章
缓存工具	`/usr/bin/expireGititCache`	失效渲染缓存/feed 缓存	第五章
Git 后端	`git -C wikidata ...`	页面增删改、历史、差异、回滚、备份迁移（与 Web 双通道互感）	第六章
HTTP 表单	`curl` 打 Web 端点	注册/登录、页面 CRUD、上传、检索、订阅读取	第七章

💡 技术拓展：Wiki 引擎的自动化接口形态对比——

形态代表特点
REST API MediaWiki（action API）、Wiki.js 动词化端点+JSON，脚本最友好
存储后端直操 Gitit、Gollum、DokuWiki 无专用 API，直接操作 git/文件 + git 版本能力白送
表单 HTTP 模拟 Gitit（本文第七章）用 curl 走 Web 表单，字段即浏览器提交内容
库/插件嵌入 Gitit Network.Gitit Haskell 编译期扩展，非运维通道

Gitit 属「存储后端直操」为主的设计——这正是它「Wiki 即 Git 仓库」理念的运维侧收益；表单模拟仅在必须复用 Web 会话/权限语义时使用。

形态	代表	特点
REST API	MediaWiki（action API）、Wiki.js	动词化端点+JSON，脚本最友好
存储后端直操	Gitit、Gollum、DokuWiki	无专用 API，直接操作 git/文件 + git 版本能力白送
表单 HTTP 模拟	Gitit（本文第七章）	用 curl 走 Web 表单，字段即浏览器提交内容
库/插件嵌入	Gitit Network.Gitit	Haskell 编译期扩展，非运维通道

三、前置条件

服务在跑：systemctl is-active gitit → active；
以 root（或 wiki 数据属主）登录服务器，对 /srv/gitit/wiki 可写；
第七章 HTTP 操作需先备好登录会话（7.1 节命令）；
第六章直接操作 git 仓库时，git 需要 committer 身份（见 8.1 节排障）。

四、gitit 主命令详解

4.1 全量选项（实测 `--help` 照抄）

gitit --help
Usage:  gitit [opts...]
  -h            --help                  Print this help message
  -v            --version               Print version information
  -p PORT       --port=PORT             Specify port
  -l INTERFACE  --listen=INTERFACE      Specify IP address to listen on
                --print-default-config  Print default configuration
  -f FILE       --config-file=FILE      Specify configuration file

七个选项之外全部行为由配置文件驱动（40+ 参数逐项详解见配置篇）；命令行项覆盖配置文件同名项。

4.2 -v / --version

gitit --version
gitit version 0.15.1.1 -plugins
Copyright (C) 2008 John MacFarlane
This is free software; see the source for copying conditions.  There is no
warranty, not even for merchantability or fitness for a particular purpose.

-plugins 前的减号表示该构建未编入插件功能（dfsg 打包开关），是判断 apt 版能力边界的第一现场。

4.3 --print-default-config

打印带官方注释的默认配置模板（294 行），运维用途是「对照现网配置查缺」与「生成初始配置文件」：

gitit --print-default-config > /srv/gitit/wiki/gitit.cfg
gitit --print-default-config | grep -E "^(port|wiki-title|require-authentication):"
port: 5001
wiki-title: Wiki
require-authentication: modify

4.4 -p / -l（端口与监听）

gitit -p 8138 &
ss -ltn | grep 8138
LISTEN 0      10           0.0.0.0:8138       0.0.0.0:*

gitit -f /srv/gitit/wiki/gitit.cfg -l 127.0.0.1 -p 8138 &
ss -ltn | grep 8138
LISTEN 0      10         127.0.0.1:8138       0.0.0.0:*

-l 收紧到回环后局域网不可达（配置篇 5.1 节），仅配反代使用。

4.5 -f / --config-file

必须显式携带——0.15.1.1 不自动加载工作目录 gitit.cfg（对照实验见配置篇 3.3 节）。生产单元推荐写法：

ExecStart=/usr/bin/gitit -f /srv/gitit/wiki/gitit.cfg

4.6 --debug

每请求向 stdout/gitit.log 打印 Happstack 请求结构与参数解析结果（节选自实测）：

================== Request =================
rqSecure      = False
rqMethod      = GET
rqPaths       = []
rqUri         = /
rqQuery       =

调试路由/表单字段名时的利器（第七章的字段名即靠它确认），生产禁用——每请求转储会迅速撑大日志。

五、expireGititCache 工具详解

随包安装的缓存失效工具（/usr/bin/expireGititCache），用法实测：

expireGititCache 2>&1 | head -2
Usage: expireGititCache base-url [file..]
Example: expireGititCache http://localhost:5001 page1.page foo/bar.hs

无参调用打印用法并以退出码 1 结束（实测 exit=1）。工作方式是向目标 wiki 发失效请求，因此服务必须在跑，否则报错（实测服务停止时）：

expireGititCache http://localhost:8138 "CLI Notes.page"
expireGititCache: user error (openTCPConnection: failed to connect; tried addresses: [[::1]:8138,127.0.0.1:8138])

正常失效效果（use-cache: yes 环境实测）：

find /srv/gitit/wiki/cache -type f | sort
/srv/gitit/wiki/cache/CLI Notes.page
/srv/gitit/wiki/cache/Front Page.page
/srv/gitit/wiki/cache/_site.feed

expireGititCache http://localhost:8138 "CLI Notes.page"; echo "exit=$?"
exit=0

find /srv/gitit/wiki/cache -type f | sort
/srv/gitit/wiki/cache/Front Page.page
/srv/gitit/wiki/cache/_site.feed

要点：文件参数用仓库内相对路径（CLI Notes.page 而非页面名 CLI Notes）；git 命令行批量写入后必须调用它，Web 才会看到新内容（Web 编辑路径自带失效，命令行路径不带）；_site.feed 等 feed 缓存即使 use-cache: no 也存在（use-feed: yes 即缓存 feed）。

六、Git 后端操作系统详解

wikidata/ 是普通 git 仓库，页面为 <页面名>.page 文本文件，全部 git 原生命令即 Wiki 管理命令。

6.1 仓库结构与页面文件格式

ls /srv/gitit/wiki/wikidata
AnonTest.page   CLI Notes.page   Front Page.page   'Gitit User’s Guide.page'   Help.page   MathDemo.page   notes.txt

cat "/srv/gitit/wiki/wikidata/Front Page.page"
---
format: Markdown
...

# Welcome to Gitit!
...

头部 ---/format: .../--- 声明该页解析器（覆盖 default-page-type），正文即 Markdown。非 .page 文件（如上传的 notes.txt）按静态文件服务。

6.2 历史与差异查询

全站历史：

git -C /srv/gitit/wiki/wikidata log --oneline | head -5
27d578b add math page
9d7a3ed anon edit
7c1e9c8 upload notes via web
6914483 Revert "extend CLI Notes"
b3c634f extend CLI Notes

单页历史（-- <路径> 过滤，实测）：

git -C /srv/gitit/wiki/wikidata log --oneline -- "CLI Notes.page"
6914483 Revert "extend CLI Notes"
b3c634f extend CLI Notes
49552a2 add page from command line

任意两版差异：

git -C /srv/gitit/wiki/wikidata diff b3c634f 6914483 -- "CLI Notes.page"
diff --git a/CLI Notes.page b/CLI Notes.page
index 10a6577..88f69b8 100644
--- a/CLI Notes.page
+++ b/CLI Notes.page
@@ -1,5 +1,3 @@
 # CLI Notes
 
 Added directly with git, no web interface.
-
-## Second section via git

单提交详情（Web 编辑的提交作者即登录账号，实测）：

git -C /srv/gitit/wiki/wikidata show --stat cd7b426 | head -9
commit cd7b426a07c7c020998d8722e728847b5ae05bc3
Author: admin <admin@example.com>
Date:   Sun Nov 1 12:44:11 2026 +0000

    first commit from web

 Deploy Test.page | 6 ++++++
 1 file changed, 6 insertions(+)

6.3 回滚与旧版取回

整页回滚到上一版——标准 git revert（注意身份问题，见 8.1）：

git -C /srv/gitit/wiki/wikidata -c user.name="root" -c user.email="root@localhost" revert --no-edit HEAD | tail -2
 1 file changed, 2 deletions(-)

curl -s http://localhost:8138/CLI%20Notes | grep -c "Second section"
0

Web 端立即反映回滚结果（计数从 2 变 0），无需重启或通知 gitit 进程。取回指定历史版本内容（不落盘对比用）：

git -C /srv/gitit/wiki/wikidata show 49552a2:"CLI Notes.page"
# CLI Notes

Added directly with git, no web interface.

把旧版写回当前页并提交的等价操作：git show <rev>:<页> > <页> && git add && git commit。

6.4 命令行编辑（双通道）

新建/修改/删除页面文件后提交，Web 自动感知（实测）：

cd /srv/gitit/wiki/wikidata
cat > "CLI Notes.page" <<'EOF'
# CLI Notes

Added directly with git, no web interface.
EOF
git add "CLI Notes.page"
git -c user.name="root" -c user.email="root@localhost" commit -m "add page from command line" | tail -2
 1 file changed, 3 insertions(+)
 create mode 100644 CLI Notes.page

curl -s http://localhost:8138/CLI%20Notes | grep -oE "Added directly[^<]*"
Added directly with git, no web interface.

⚠️ 注意：use-cache: yes 时命令行提交后 Web 仍可能显示旧渲染，需补一句 expireGititCache http://localhost:8138 "CLI Notes.page"（第五章）。

6.5 备份与迁移

整站备份就是一次 clone（实测 12 个提交完整带走）：

git clone /srv/gitit/wiki/wikidata /root/wikibak
ls /root/wikibak | head -6
AnonTest.page
CLI Notes.page
Front Page.page
Gitit User’s Guide.page
Help.page
MathDemo.page

git -C /root/wikibak log --oneline | wc -l
12

迁移到新服务器：clone 到目标机 gitit 的 repository-path 位置即可，历史、作者、页面全部保留；异地容灾可再 git remote add origin <内网Git服务地址> && git push。

七、HTTP 接口 curl 操作系详解

Gitit 的 Web 端点即「表单 API」，字段名与浏览器提交完全一致。以下每条均实测。

7.1 注册与登录（会话建立）

注册 /_register（POST，字段：username、email、password、password2、destination、register=Register，另有隐藏陷阱字段 full_name_1 必须留空，非空则静默拒绝并回显表单）：

curl -s -c cookies.txt -d "username=admin&email=admin@example.com&full_name_1=&full_name_2=&password=q1w2e3r4&password2=q1w2e3r4&destination=&register=Register" \
     -w "HTTP=%{http_code}\n" http://localhost:8138/_register
HTTP=303

303 = 成功重定向；口令以盐化哈希落 gitit-users。登录 /_login（字段 username、password、destination、login=Login）：

curl -s -b cookies.txt -c cookies.txt -d "username=admin&password=q1w2e3r4&login=Login" \
     -w "HTTP=%{http_code}\n" http://localhost:8138/_login
HTTP=303

当前会话用户查询 /_user（登录态返回用户名，匿名返回空串，实测）：

curl -s -b cookies.txt http://localhost:8138/_user
admin
curl -s http://localhost:8138/_user
（空）

7.2 创建与编辑页面

端点即页面 URL 本身，POST 字段 editedText（正文）、logMsg（变更说明，default-summary 为空时必填，留空被拒）、update=Save。新建无需 sha1：

curl -s -b cookies.txt --data-urlencode "editedText=# Deploy Test

Created via Web UI on 2026-11-01." --data-urlencode "logMsg=first commit from web" \
     --data-urlencode "update=Save" -w "HTTP=%{http_code}\n" -o /dev/null \
     http://localhost:8138/Deploy%20Test
HTTP=303

编辑已有页面必须携带隐藏字段 sha1（当前修订哈希，乐观锁；缺失或过期一律 500）：

SHA1=$(git -C /srv/gitit/wiki/wikidata rev-parse HEAD)
curl -s -b cookies.txt --data-urlencode "sha1=$SHA1" \
     --data-urlencode "editedText=# Deploy Test

Revised." --data-urlencode "logMsg=second edit: revise wording" \
     --data-urlencode "update=Save" -w "HTTP=%{http_code}\n" -o /dev/null \
     http://localhost:8138/Deploy%20Test
HTTP=303

7.3 删除页面

先 GET /_delete/<页> 取确认表单（字段 filetodelete），再 POST 确认（字段 confirm=Yes, delete it!；提交说明强制取 delete-summary，logMsg 无效）：

curl -s -b cookies.txt --data-urlencode "filetodelete=Deploy Test.page" \
     --data-urlencode "confirm=Yes, delete it!" -w "HTTP=%{http_code}\n" -o /dev/null \
     http://localhost:8138/_delete/Deploy%20Test
HTTP=303

git -C /srv/gitit/wiki/wikidata log --oneline -1
082356e Deleted using web interface.

no-delete 名单内页面（默认 Front Page、Help）删除请求被拒：HTTP 200 返回页面本身、仓库无删除提交（实测）。

7.4 上传文件

/_upload（multipart，字段：file、wikiname（留空用原文件名）、overwrite=yes（可选覆盖）、logMsg、upload=Upload）：

echo "test upload content" > /root/notes.txt
curl -s -b cookies.txt -F "file=@/root/notes.txt;type=text/plain" -F "wikiname=notes.txt" \
     -F "logMsg=upload notes via web" -F "upload=Upload" -w "HTTP=%{http_code}\n" \
     http://localhost:8138/_upload
HTTP=200
Upload successful
Uploaded 20 bytes

git -C /srv/gitit/wiki/wikidata log --oneline -1
7c1e9c8 upload notes via web

文件入仓库后按原路径访问，代码类文件带语法高亮渲染：

curl -s http://localhost:8138/notes.txt | grep -oE "test upload content"
test upload content

成功判定看响应体 Upload successful 与仓库新提交；字段名写错（如把 upload 写成 commit）同样返回 200 但只回显表单、无提交——静默失败是这套表单接口最坑的地方，脚本化前建议开 --debug 核对一次真实字段名。超过 max-upload-size（默认 100K）返回 413（实测 50K 限制下 60 KB 文件被拒）。

7.5 读取类端点速查（全部实测）

端点	方法/参数	实测行为
`/_showraw/<页>`	GET	返回页面源文本：`# CLI Notes` 原样输出
`/_search?patterns=<正则>`	GET	全库正则检索，`patterns=Added+directly` 命中 CLI Notes
`/_go`	POST `gotopage=<页>`	303 跳转到目标页
`/_activity`	GET	近期变更列表（含 `add page from command line` 等提交标题）
`/_history/<页>`	GET	单页版本列表（实测含 revert 记录 `Revert "extend CLI Notes"`）
`/_diff/<页>?from=<rev1>&to=<rev2>`	GET	两版对比页，HTTP 200
`/_feed`	GET	Atom XML（需 `use-feed: yes`；locale 非 UTF-8 时 500）
`/_index`	GET	全部页面索引
`/_categories`	GET	分类目录页，HTTP 200
`/_random`	GET	303 随机跳转某页
`/<页>?printable`	GET	打印版视图（实测正文完整输出）
`/_logout`	GET	清除会话

八、注意事项

UTF-8 locale 是硬前提：所有直接调 gitit 的前台会话先 export LANG=C.UTF-8（systemd 单元用 Environment= 注入）；缺失的典型爆点是含 Unicode 标点的页面名在 feed/搜索路径 500（recoverEncode）。
服务重启清空会话：systemctl restart gitit 后旧 Cookie 一律 307，脚本需重建登录态。
无管理 API：不要尝试找 /_api 类 REST 端点——不存在；自动化优先走第六章 git 直操（配合 expireGititCache），必须复用 Web 权限语义时才用第七章表单通道。
插件通道非 CLI：Network.Gitit.Interface 插件是 Haskell 源码编译期扩展，apt 版（-plugins）不可用，与命令行运维无关。

8.1 排障实录：git revert 报 usage 错误

现象：对 wikidata 仓库直接 git revert --no-edit HEAD 失败，输出是 git 用法帮助（--[no-]reference use the 'reference' format...）而非提交结果。定位：gitit 自建仓库未配置 committer 身份（git config user.name 为空），revert 生成提交时因缺身份中止。解决（实测二选一）：

git -C /srv/gitit/wiki/wikidata -c user.name="root" -c user.email="root@localhost" revert --no-edit HEAD
[master 6914483] Revert "extend CLI Notes"
 1 file changed, 2 deletions(-)

或一次性写入仓库配置：git -C /srv/gitit/wiki/wikidata config user.name root && git -C /srv/gitit/wiki/wikidata config user.email root@localhost。同理适用于第六章所有命令行提交场景。

九、常见问题

9.1 编辑页面 HTTP 500

缺 sha1 字段或值过期（乐观锁冲突，响应体为 Happstack 错误页 error was "NotFound"）。先取当前 sha1 再提交（7.2 节）。

9.2 注册返回 200 但账号没建成

陷阱字段 full_name_1 非空被静默拒——留空提交即 303（7.1 节）。

9.3 上传返回 200 但仓库没文件

multipart 字段名不对（正确为 file/wikiname/logMsg/upload），gitit 对未知字段宽容、只回显表单。用 --debug 转储核对（7.4 节）。

9.4 删除页面的 git 提交说明不是我填的

删除说明强制取 delete-summary 配置值（默认 Deleted using web interface.），表单 logMsg 被忽略（7.3 节）。

9.5 expireGititCache 报 openTCPConnection failed

目标 wiki 没在跑或 URL 写错（工具按 base-url 连接，实测服务停止时报 tried addresses: [[::1]:8138,127.0.0.1:8138]）。先 systemctl is-active gitit 确认。

十、参考链接

官方仓库：https://github.com/jgm/gitit （查询日期 2026-11-01）
Hackage 包页：https://hackage.haskell.org/package/gitit （查询日期 2026-11-01）
本专栏配套篇：《Gitit 介绍与选型指南》、《Ubuntu 24.04 安装 Gitit 0.15.1.1 指南》、《Gitit 0.15.1.1 配置参数详解》

Gitit 0.15.1.1 常用 CLI 命令与工具详解

Gitit 0.15.1.1 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、gitit 主命令详解

4.1 全量选项（实测 --help 照抄）

4.2 -v / --version

4.3 --print-default-config

4.4 -p / -l（端口与监听）

4.5 -f / --config-file

4.6 --debug

五、expireGititCache 工具详解

六、Git 后端操作系统详解

6.1 仓库结构与页面文件格式

6.2 历史与差异查询

6.3 回滚与旧版取回

6.4 命令行编辑（双通道）

6.5 备份与迁移

七、HTTP 接口 curl 操作系详解

7.1 注册与登录（会话建立）

7.2 创建与编辑页面

7.3 删除页面

7.4 上传文件

7.5 读取类端点速查（全部实测）

八、注意事项

8.1 排障实录：git revert 报 usage 错误

九、常见问题

9.1 编辑页面 HTTP 500

9.2 注册返回 200 但账号没建成

9.3 上传返回 200 但仓库没文件

9.4 删除页面的 git 提交说明不是我填的

9.5 expireGititCache 报 openTCPConnection failed

十、参考链接

4.1 全量选项（实测 `--help` 照抄）