difftab 0.5.2 → 0.5.3

package/dist/server/main.js

@@ -75,13 +75,48 @@ const GLOBAL_CONFIG = ["-c", "core.quotePath=false"];
 * 模式，而我们的路径全部来自 URL query——`path=*` 会让 `git diff HEAD -- '*'` 回一份
 * **整仓 diff**，正是红线明令禁止、会把浏览器主线程冻上数十秒的那件事；而一个真实存在、
 * 名字里带 `*` 的文件同样会匹配到别人身上，页面在 A 的标题下显示 B 的补丁。
+*
+* **`GIT_NO_LAZY_FETCH=1` 同样是只读承诺的一部分**：partial clone（`--filter=blob:none`）里缺的
+* 对象，git 默认会当场从 promisor remote 取回来并写进 `.git/objects`——任何一条要读 blob 的命令
+* （`diff`、`cat-file`）都会触发，而提交历史正是去读那些从没检出过的旧 blob。关掉之后缺对象就是
+* 一次非零退出（实测 128：`could not fetch … from promisor remote`），不联网、不写库。它是
+* git 2.44 才有的变量，更老的 git 不认——那一档的防线在 `history.ts`（partial clone 下直接拒）。
 */
 const GIT_ENV = {
 	GIT_OPTIONAL_LOCKS: "0",
 	GIT_TERMINAL_PROMPT: "0",
-	GIT_LITERAL_PATHSPECS: "1"
+	GIT_LITERAL_PATHSPECS: "1",
+	GIT_NO_LAZY_FETCH: "1"
 };
 /**
+* **每一条 `git diff` 都紧跟在子命令之后带上这两个开关**，由 `runGitRaw` 注入，不留给调用点挑：
+* - `--no-textconv`：`.gitattributes` 里 `diff=<驱动>` + `diff.<驱动>.textconv` 会让补丁那一形态
+*   对两侧各起一次外部程序，配了 `cachetextconv` 时还把结果写进 `refs/notes/textconv/<驱动>`
+*   ——实测补丁形态（工作区 diff 与提交 diff 都是）会写，`--numstat` / `--name-status` 不写，加上
+*   本开关后一条都不写。numstat 那几条也带：二进制与行数的判定得与补丁看的是同一份内容；
+* - `--no-ext-diff`：`diff.external` / `GIT_EXTERNAL_DIFF` 同理是一个外部程序。
+*
+* 代价是配了 textconv 的文件（`.docx`、加密文件）按原始字节比——二进制就说二进制。冒烟逐条
+* 断言 `diff` 的 argv 里两者都在。
+*/
+const DIFF_GUARDS = ["--no-ext-diff", "--no-textconv"];
+/** `-c` 全局选项排在子命令之前，`diff` 的两道外部程序开关紧跟在子命令之后。 */
+function argvOf(args) {
+	const [subcommand, ...rest] = args;
+	return subcommand === "diff" ? [
+		...GLOBAL_CONFIG,
+		subcommand,
+		...DIFF_GUARDS,
+		...rest
+	] : [...GLOBAL_CONFIG, ...args];
+}
+/**
+* 缺对象的那几种报法（`GIT_NO_LAZY_FETCH` 之下的 partial clone）：实测 `could not fetch … from
+* promisor remote`，前面还有一行 `lazy fetching disabled`。**在这里分类一次**，而不是让每个调用点
+* 各自记得 catch——漏 catch 的那条路会把「内容不在本地」说成「路径不存在」或一条 500。
+*/
+const MISSING_OBJECT = /promisor remote|lazy fetching disabled/;
+/**
 * stdout 的**兜底**上限：没有它，一个几百 MB 的文件的 diff 会被整个读进内存，而这条路径
 * 上没有任何东西会先失败。产品语义那道 5MB 闸不在这里，由调用方按次传 `maxStdoutBytes`
 *——**能不能渲染取决于补丁多大，而不是文件多大**，一个 6MB 的数据文件改一行照样该看得见。
@@ -111,7 +146,7 @@ var GitError = class extends Error {
 function runGitRaw(args, cwd, options = {}) {
 	const limit = Math.min(options.maxStdoutBytes ?? MAX_STDOUT_BYTES, MAX_STDOUT_BYTES);
 	return new Promise((resolvePromise, rejectPromise) => {
-		const argv = [...GLOBAL_CONFIG, ...args];
+		const argv = argvOf(args);
 		const child = spawn("git", argv, {
 			cwd,
 			env: {
@@ -166,6 +201,10 @@ function runGitRaw(args, cwd, options = {}) {
 				rejectPromise(new GitError("overflow", argv, stderr, code));
 				return;
 			}
+			if (code !== 0 && MISSING_OBJECT.test(stderr)) {
+				rejectPromise(new GitError("missing-object", argv, stderr, code));
+				return;
+			}
 			resolvePromise({
 				stdout: Buffer.concat(out),
 				stderr,
@@ -224,8 +263,17 @@ function parseGitVersion(output) {
 		minor: Number(m[2])
 	};
 }
-function tooOld(v) {
-	return v.major < MIN_GIT.major || v.major === MIN_GIT.major && v.minor < MIN_GIT.minor;
+/** `v` 不低于 `min`。版本比较只此一份——启动下限与 `GIT_NO_LAZY_FETCH` 那道下限共用。 */
+function atLeast(v, min) {
+	return v.major > min.major || v.major === min.major && v.minor >= min.minor;
+}
+/**
+* 完整对象名：SHA-1 40 位 / SHA-256 64 位小写十六进制。**判据只此一份**——status 解析
+* `# branch.oid` 与提交历史校验请求里的 sha 用的是同一条，两份漂开时前端拿 `BranchState.oid` 去比
+* 的东西与后端认的对象名就不是一回事了。
+*/
+function isOid(value) {
+	return /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(value);
 }
 /**
 * 前置检查 + 定位，一次做完。两条命令并发跑：串行等于把两次进程启动开销叠加进 300ms
@@ -235,13 +283,14 @@ async function locateRepo(cwd) {
 	const [version, located] = await Promise.all([runGit(["--version"], cwd), runGit([
 		"rev-parse",
 		"--show-toplevel",
-		"--git-dir"
+		"--git-dir",
+		"--git-common-dir"
 	], cwd)]).catch((cause) => {
 		if (cause instanceof GitError && cause.kind === "missing") throw new PreflightError("git-missing", "git was not found on your PATH. Install git and try again.");
 		throw cause;
 	});
 	const parsed = version.code === 0 ? parseGitVersion(version.stdout) : null;
-	if (parsed && tooOld(parsed)) throw new PreflightError("git-too-old", `difftab needs git ${MIN_GIT.major}.${MIN_GIT.minor} or newer (for --porcelain=v2), but found ${parsed.major}.${parsed.minor}.`);
+	if (parsed && !atLeast(parsed, MIN_GIT)) throw new PreflightError("git-too-old", `difftab needs git ${MIN_GIT.major}.${MIN_GIT.minor} or newer (for --porcelain=v2), but found ${parsed.major}.${parsed.minor}.`);
 	if (located.code !== 0) {
 		const bare = await runGit(["rev-parse", "--is-bare-repository"], cwd);
 		if (bare.code === 0 && bare.stdout.trim() === "true") throw new PreflightError("bare-repo", "this is a bare repository — it has no working tree to show changes for.");
@@ -250,10 +299,13 @@ async function locateRepo(cwd) {
 	const lines = located.stdout.split("\n");
 	const root = lines[0]?.trim();
 	const gitDir = lines[1]?.trim();
-	if (!root || !gitDir) throw new PreflightError("not-a-repo", "this directory is not inside a git repository.");
+	const commonDir = lines[2]?.trim();
+	if (!root || !gitDir || !commonDir) throw new PreflightError("not-a-repo", "this directory is not inside a git repository.");
 	return {
 		root,
-		gitDir: isAbsolute(gitDir) ? gitDir : resolve(root, gitDir)
+		gitDir: isAbsolute(gitDir) ? gitDir : resolve(root, gitDir),
+		commonDir: resolve(cwd, commonDir),
+		gitVersion: parsed
 	};
 }
 /**
@@ -276,6 +328,23 @@ function repoNameOf(repo) {
 * 变回未出生状态，缓存的正结果会让 diff 从此全部 fatal。
 */
 async function resolveDiffBase(root) {
+	const oid = await headOid(root);
+	if (oid !== null) return {
+		ref: "HEAD",
+		oid
+	};
+	const empty = await emptyTree(root);
+	return {
+		ref: empty,
+		oid: empty
+	};
+}
+/**
+* HEAD 此刻指向的提交；**`null` 即 HEAD 未出生**（空仓库、`checkout --orphan` 之后）。「未出生」的
+* 判据只此一份——diff 基准退回空树与提交列表说「没有提交」用的是同一条：`rev-parse --verify` 在
+* 未出生时退 1；指着一个缺失的对象时却退 0 并照样印出 oid（实测），那不是未出生。
+*/
+async function headOid(root) {
 	const head = await runGit([
 		"rev-parse",
 		"--verify",
@@ -283,16 +352,21 @@ async function resolveDiffBase(root) {
 		"HEAD"
 	], root);
 	const oid = head.stdout.trim();
-	if (head.code === 0 && oid) return {
-		ref: "HEAD",
-		oid
-	};
+	return head.code === 0 && oid ? oid : null;
+}
+/**
+* 某个对象名所在格式下的空树哈希：64 位即 SHA-256，其余按 SHA-1。提交历史手里已经有一个对象名，
+* 用它的长度就能定格式，不必为根提交再问一次 `--show-object-format`。
+*/
+function emptyTreeOf(oid) {
+	return oid.length === 64 ? EMPTY_TREE.sha256 : EMPTY_TREE.sha1;
+}
+/**
+* 本仓库对象格式下的空树哈希——空仓库的 diff 基准。手上还没有任何对象名，只能问 git。
+*/
+async function emptyTree(root) {
 	const format = await runGit(["rev-parse", "--show-object-format"], root);
-	const empty = (format.code === 0 ? format.stdout.trim() : "sha1") === "sha256" ? EMPTY_TREE.sha256 : EMPTY_TREE.sha1;
-	return {
-		ref: empty,
-		oid: empty
-	};
+	return (format.code === 0 ? format.stdout.trim() : "sha1") === "sha256" ? EMPTY_TREE.sha256 : EMPTY_TREE.sha1;
 }
 
 //#endregion
@@ -346,6 +420,23 @@ function contains(base, target) {
 	return rel === "" || !rel.startsWith("..") && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
 }
 /**
+* 只过**字面量那道**：拒绝绝对路径、含 `\0` 的、以及 `relative()` 走出去的那些，回归一化后的
+* 路径。**只给不落磁盘的路径用**——提交历史里的路径只拼进 pathspec 与 `<rev>:<path>`，那个文件
+* 在工作区里可能早已不在，`realpath` 那道既无从验、也没有东西需要它保护。凡是真要落磁盘的，
+* 一律走下面的 `resolveInRepo`。
+*/
+function literalRepoPath(root, path, allowRoot = false) {
+	if (path.includes("\0") || isAbsolute(path)) throw new WorktreeError("invalid-path", "invalid path");
+	if (path === "" && !allowRoot) throw new WorktreeError("invalid-path", "invalid path");
+	const abs = path === "" ? resolve(root) : resolve(root, path);
+	const rel = relative(root, abs);
+	if (!contains(root, abs) || rel === "" && !allowRoot) throw new WorktreeError("invalid-path", "invalid path");
+	return {
+		abs,
+		path: rel.split(sep).join("/")
+	};
+}
+/**
 * 把请求里的路径落到磁盘上，**两道边界一次过完**。
 *
 * 1. **字面量那道**：拒绝绝对路径、含 `\0` 的、以及 `relative()` 走出去的那些。
@@ -359,13 +450,7 @@ function contains(base, target) {
 * 只取 `abs` 的写法把这份结果扔掉了，才不得不在外面补一条 `endsWith('/')`）。
 */
 async function resolveInRepo(root, path, options) {
-	if (path.includes("\0") || isAbsolute(path)) throw new WorktreeError("invalid-path", "invalid path");
-	if (path === "") {
-		if (options.allowRoot !== true) throw new WorktreeError("invalid-path", "invalid path");
-	}
-	const abs = path === "" ? resolve(root) : resolve(root, path);
-	const rel = relative(root, abs);
-	if (!contains(root, abs) || rel === "" && options.allowRoot !== true) throw new WorktreeError("invalid-path", "invalid path");
+	const { abs, path: normalized } = literalRepoPath(root, path, options.allowRoot === true);
 	const realRoot = await realpath(root);
 	if (options.follow) {
 		let real;
@@ -386,7 +471,7 @@ async function resolveInRepo(root, path, options) {
 	}
 	return {
 		abs,
-		path: rel.split(sep).join("/")
+		path: normalized
 	};
 }
 /**
@@ -469,6 +554,226 @@ async function inspectFile(root, path) {
 	};
 }
 
+//#endregion
+//#region src/server/git/history.ts
+/** 一页多少条。取 `PAGE_SIZE + 1` 条来判 `hasMore`，不另起一次计数。 */
+const PAGE_SIZE = 50;
+/**
+* 每条提交恰好六段：`-z` 让记录之间以 NUL 分隔，`%x00` 让字段之间也是 NUL。主题行（`%s`）
+* 不含 NUL 与换行，作者名里的空格、正文（`%b`）里的换行都不是分隔符；根提交的 `%P` 是一个空段，
+* 不是缺段。
+*/
+const LOG_FORMAT = "--format=%H%x00%P%x00%an%x00%at%x00%s%x00%b";
+const FIELDS$1 = 6;
+/**
+* `log` 的 argv，**整条是字面量**，冒烟逐段钉着它：
+* - `--no-show-signature`：用户配了 `log.showSignature` 时 `log` 会对每条提交起一次 gpg；
+* - **不带 `-p` / `--stat` / 任何 diff 选项**：一旦算 diff，`diff.external` 与 textconv 驱动就
+*   都在射程内，而白名单只看子命令；
+* - 末尾的 `--`：`rev` 之后的任何东西都不再被当成选项。
+*
+* `rev` 必须已过 `assertOid`——它拼在 revision 位置，`GIT_LITERAL_PATHSPECS` 管不到那里，
+* `--output=<路径>` 在那个位置就是一次写文件。
+*/
+function logArgs(rev, count, skip) {
+	return [
+		"log",
+		"--no-show-signature",
+		"--no-color",
+		"-z",
+		LOG_FORMAT,
+		`--max-count=${count}`,
+		...skip === void 0 ? [] : [`--skip=${skip}`],
+		rev,
+		"--"
+	];
+}
+/**
+* 请求里的提交只认**完整的十六进制对象名**（SHA-1 40 位 / SHA-256 64 位）：不认缩写、不认
+* `HEAD~3` 一类 revision 表达式，更不认 `-` 开头的值。前端手里的 sha 全部来自后端自己的输出，
+* 用不着任何 revision 语法。
+*/
+function assertOid(value) {
+	if (!isOid(value)) throw new WorktreeError("invalid-path", "not a full commit hash");
+	return value;
+}
+/**
+* `log -z` + `LOG_FORMAT` 的解析：按六段一组切。正文含 NUL 也不会错位——git 输出 `%b` 时在第一个
+* NUL 处截断（实测：`hash-object --literally` 造一条「Reverts\0<sha>\0tail」的说明，回来的正文就是
+* `Reverts`），于是每条记录在输出里恒为六段。
+*/
+function parseLog(output) {
+	const segments = output.split("\0");
+	const commits = [];
+	for (let i = 0; i + FIELDS$1 <= segments.length; i += FIELDS$1) {
+		const [sha = "", parents = "", author = "", time = "", subject = "", body = ""] = segments.slice(i, i + FIELDS$1);
+		const id = sha.replace(/^\n/, "");
+		if (!isOid(id)) continue;
+		commits.push({
+			sha: id,
+			parents: parents === "" ? [] : parents.split(" "),
+			author,
+			time: Number(time),
+			subject,
+			body: body.trimEnd()
+		});
+	}
+	return commits;
+}
+/**
+* 提交列表的一页。`head` 缺省即「从 HEAD 起」，并把 HEAD 此刻的 oid 回传当锚点；之后每一页
+* 都带着它再 `--skip`——按 HEAD 往下数时，agent 在两次翻页之间提交一次，第二页就重复第一页的
+* 最后一条。空仓库（HEAD 未出生）是一页空列表，不是错误。
+*/
+async function listCommits(root, query) {
+	const rev = query.head === void 0 ? "HEAD" : assertOid(query.head);
+	const result = await runGit(logArgs(rev, 51, query.skip), root);
+	if (result.code !== 0) {
+		if (query.head !== void 0) throw new WorktreeError("not-found", "no such commit");
+		if (await headOid(root) === null) return {
+			head: null,
+			commits: [],
+			hasMore: false
+		};
+		throw new Error("HEAD points to a commit that cannot be read");
+	}
+	const commits = parseLog(result.stdout);
+	return {
+		head: query.head ?? commits[0]?.sha ?? null,
+		commits: commits.slice(0, 50),
+		hasMore: commits.length > 50
+	};
+}
+/**
+* 把请求里的 sha 落成 `CommitRange`。**对比端只在这里定一次**：三条路各自去找父提交时，将来
+* 改一处（比如合并提交换个父）漏改另一处，文件清单、补丁与图片就是对着三个不同的父在比，而
+* 不报错。
+*
+* 一次 `log -1` 同时做校验与取元数据：对象名合法不等于是本仓库里的一个提交——`log` 对不存在
+* 的对象以 128 退出，对树与 blob **以 0 退出、输出为空**，对附注标签则剥到它指向的提交（实测）。
+* 所以判据是「回来的那条正好就是问的这个 sha」，退出码只是其中一半。
+*/
+async function resolveCommit(repo, sha) {
+	assertOid(sha);
+	await refuseLazyFetch(repo);
+	const result = await runGit(logArgs(sha, 1), repo.root);
+	const [commit] = result.code === 0 ? parseLog(result.stdout) : [];
+	if (commit?.sha !== sha) throw new WorktreeError("not-found", "no such commit");
+	const [first] = commit.parents;
+	if (first !== void 0) return {
+		commit,
+		parent: first
+	};
+	return {
+		commit,
+		parent: await isShallowBoundary(repo, sha) ? null : emptyTreeOf(sha)
+	};
+}
+/** 浅克隆边界上的提交没有父可比。补丁与图片两条路据此拒绝，而不是拿空树去比。 */
+function requireParent(range) {
+	if (range.parent === null) throw new WorktreeError("unsupported", "shallow clone: this commit has no parent to compare with");
+	return range.parent;
+}
+/**
+* 这条提交是不是浅克隆的边界：共享 git 目录下的 `shallow` 文件逐行列着它们（实测 `--depth 1` 之后
+* 正好是 HEAD 那一条）。只在 `%P` 为空时才读——根提交与边界只有这一处分得开。**不缓存**：
+* `fetch --deepen` 会改这个文件，而这条路只在根提交上走。
+*/
+async function isShallowBoundary(repo, sha) {
+	try {
+		return (await readFile(join(repo.commonDir, "shallow"), "utf8")).split("\n").some((line) => line.trim() === sha);
+	} catch {
+		return false;
+	}
+}
+/** `GIT_NO_LAZY_FETCH` 的版本下限（git 2.44）。 */
+const LAZY_FETCH_SWITCH = {
+	major: 2,
+	minor: 44
+};
+/**
+* **老 git + partial clone 下提交历史整个拒绝**。`GIT_NO_LAZY_FETCH` 是 git 2.44 才有的变量，更老
+* 的 git 不认它：缺的 blob 照样当场从 promisor remote 取回来写进 `.git/objects`，而提交历史读的
+* 恰恰是那些从没检出过的旧 blob——工作区 diff 只碰 HEAD 里已检出的那一份，不在此列。
+*
+* 版本是启动时 `locateRepo` 解析好的（解析不出按新的算，与启动下限同一取向），partial clone 的记号
+* 读共享 git 目录下的 `config`——与进行中的操作同一个取向：读状态文件，不为它往白名单里添
+* `config`。新 git 上一次文件都不读；老 git 上每次读一个小文件，不另设缓存。
+*/
+async function refuseLazyFetch(repo) {
+	if (repo.gitVersion === null || atLeast(repo.gitVersion, LAZY_FETCH_SWITCH)) return;
+	let config = "";
+	try {
+		config = await readFile(join(repo.commonDir, "config"), "utf8");
+	} catch {
+		return;
+	}
+	if (isPartialCloneConfig(config)) throw new WorktreeError("unsupported", "commit history in a partial clone needs git 2.44 or newer");
+}
+/**
+* 一份 git `config` 正文里有没有 partial clone 的记号：`extensions.partialClone = <名>`，或
+* `remote.<名>.promisor` 为真——git 的布尔值只写键名、`true` / `yes` / `on` / `1` 都算，不区分大小写。
+*/
+function isPartialCloneConfig(config) {
+	return /^\s*(?:partialclone\s*=|promisor\s*(?:$|=\s*"?(?:true|yes|on|1)\b))/im.test(config);
+}
+/**
+* `diff --name-status -z -M` 的解析。**重命名记录占三段**：`R<score>` `<旧路径>` `<新路径>`——
+* 与 numstat 同为旧在前、与 porcelain 的 `2 ` 记录相反。平铺切分会把旧路径当成下一条记录的
+* 状态字段。没开 `-C`，`C` 不会出现；认不出的状态字母整条跳过，不猜。
+*/
+function parseNameStatus(output) {
+	const segments = output.split("\0");
+	const files = [];
+	for (let i = 0; i < segments.length;) {
+		const status = segments[i] ?? "";
+		const letter = status[0];
+		if (letter === "R" || letter === "C") {
+			const oldPath = segments[i + 1] ?? "";
+			const path = segments[i + 2] ?? "";
+			if (letter === "R") files.push({
+				path,
+				oldPath,
+				status: "R"
+			});
+			i += 3;
+			continue;
+		}
+		if (letter === "A" || letter === "M" || letter === "D" || letter === "T") {
+			files.push({
+				path: segments[i + 1] ?? "",
+				status: letter
+			});
+			i += 2;
+			continue;
+		}
+		i += status === "" ? 1 : 2;
+	}
+	return files;
+}
+/** 一次提交的元数据 + 改了哪些文件（相对第一父）。 */
+async function readCommit(repo, sha) {
+	const { commit, parent } = await resolveCommit(repo, sha);
+	if (parent === null) return {
+		...commit,
+		files: [],
+		shallow: true
+	};
+	const output = await runGitStrict([
+		"diff",
+		parent,
+		commit.sha,
+		"--name-status",
+		"-z",
+		"-M",
+		"--"
+	], repo.root);
+	return {
+		...commit,
+		files: parseNameStatus(output)
+	};
+}
+
 //#endregion
 //#region src/server/git/image.ts
 /**
@@ -501,9 +806,17 @@ async function baseBlobSize(root, baseRef, normalizedPath) {
 * 长大。`new` 侧走 `inspectFile`——与 payload 同一条链，NUL ∧ 扩展名两半都过；`old` 侧带
 * `maxStdoutBytes` 去撞，超限即就地掐断 git。
 */
-async function readImageBytes(root, path, side) {
+async function readImageBytes(repo, path, side, commit) {
+	const { root } = repo;
 	const mime = imageMimeOf(path);
 	if (mime === null) throw new WorktreeError("invalid-path", "not an image");
+	if (commit !== void 0) {
+		const resolved = await resolveCommit(repo, commit);
+		return {
+			buffer: await readBlob(root, side === "new" ? resolved.commit.sha : requireParent(resolved), literalRepoPath(root, path).path),
+			mime
+		};
+	}
 	if (side === "new") {
 		const file = await inspectFile(root, path);
 		if (file.kind === "too-large") throw new WorktreeError("too-large", "image too large");
@@ -514,22 +827,26 @@ async function readImageBytes(root, path, side) {
 		};
 	}
 	const [base, { path: normalized }] = await Promise.all([resolveDiffBase(root), resolveInRepo(root, path, { follow: false })]);
+	return {
+		buffer: await readBlob(root, base.ref, normalized),
+		mime
+	};
+}
+/** `cat-file blob <rev>:<path>`，带 `maxStdoutBytes` 去撞 5MB。 */
+async function readBlob(root, rev, normalizedPath) {
 	let result;
 	try {
 		result = await runGitRaw([
 			"cat-file",
 			"blob",
-			blobRef(base.ref, normalized)
+			blobRef(rev, normalizedPath)
 		], root, { maxStdoutBytes: MAX_BYTES });
 	} catch (cause) {
 		if (cause instanceof GitError && cause.kind === "overflow") throw new WorktreeError("too-large", "image too large");
 		throw cause;
 	}
 	if (result.code !== 0) throw new WorktreeError("not-found", "no such file in the diff base");
-	return {
-		buffer: result.stdout,
-		mime
-	};
+	return result.stdout;
 }
 
 //#endregion
@@ -577,7 +894,7 @@ function parseNumstat(output) {
 	return records;
 }
 /**
-* 「基准 → 工作区」这条路径上的 numstat 记录；不在差异里就是 `null`。这一次调用同时回答
+* 「基准 → 工作区」（或提交历史里「父 → 提交」）这条路径上的 numstat 记录；不在差异里就是 `null`。这一次调用同时回答
 * 三个问题，所以它取代了原先那次 `diff --name-only`：
 * 1. **它是不是已跟踪的**。已跟踪是 **HEAD ∪ index**，而 `ls-files` 只答得出 index——
 *    `git rm` 之后已暂存的删除在 index 里已经没有了，status 却照样报 `1 D.`、基准侧也
@@ -589,21 +906,10 @@ function parseNumstat(output) {
 * 重命名同样要传两个路径 + `-M`：只传新路径时 git 无法配对，numstat 会把它算成一个全
 * 新增文件（行数因此是整份文件），与补丁那一侧的退化是同一回事。
 */
-async function readNumstat(root, base, path, oldPath) {
-	/**
-	* **一次查询可以回不止一条记录**，所以必须按路径挑、不能取 `[0]`：传了两个路径而 git
-	* **配不上对**时（`git mv` 之后把内容全部重写、留在工作区不 `git add`——status 照报
-	* `R100`，所以 `oldPath` 是有的），它会拆成「删掉旧的」+「新增新的」两条并按路径排序。
-	* 取 `[0]` 就是掷硬币：实测那条 60,000 行的改名里排在前面的是旧文件那条 100 行的删除，
-	* 于是行数闸放它过去，一份 6 万行的补丁照旧发给浏览器。二进制同理。
-	*
-	* 挑中之后**合并**而不是取一条：那份补丁里两个文件都在，前端要渲染的是两者之和。挑的是
-	* `path` 字段——git 的重命名检测发生在 pathspec 过滤**之后**，配上对与配不上对的记录
-	* 都落在我们给的这两个路径里，因此不必再比 `record.oldPath`。
-	*/
-	const mine = parseNumstat(await runGitStrict(oldPath ? [
+async function readNumstat(root, range, path, oldPath) {
+	const args = oldPath ? [
 		"diff",
-		base,
+		...range,
 		"--numstat",
 		"-z",
 		"-M",
@@ -612,12 +918,24 @@ async function readNumstat(root, base, path, oldPath) {
 		oldPath
 	] : [
 		"diff",
-		base,
+		...range,
 		"--numstat",
 		"-z",
 		"--",
 		path
-	], root)).filter((record) => record.path === path || oldPath !== void 0 && record.path === oldPath);
+	];
+	/**
+	* **一次查询可以回不止一条记录**，所以必须按路径挑、不能取 `[0]`：传了两个路径而 git
+	* **配不上对**时（`git mv` 之后把内容全部重写、留在工作区不 `git add`——status 照报
+	* `R100`，所以 `oldPath` 是有的），它会拆成「删掉旧的」+「新增新的」两条并按路径排序。
+	* 取 `[0]` 就是掷硬币：实测那条 60,000 行的改名里排在前面的是旧文件那条 100 行的删除，
+	* 于是行数闸放它过去，一份 6 万行的补丁照旧发给浏览器。二进制同理。
+	*
+	* 挑中之后**合并**而不是取一条：那份补丁里两个文件都在，前端要渲染的是两者之和。挑的是
+	* `path` 字段——git 的重命名检测发生在 pathspec 过滤**之后**，配上对与配不上对的记录
+	* 都落在我们给的这两个路径里，因此不必再比 `record.oldPath`。
+	*/
+	const mine = parseNumstat(await runGitStrict(args, root)).filter((record) => record.path === path || oldPath !== void 0 && record.path === oldPath);
 	if (mine.length === 0) return null;
 	return {
 		binary: mine.some((record) => record.binary),
@@ -653,7 +971,23 @@ async function worktreeSize(abs) {
 async function imageDiff(root, base, path, abs, oldPath) {
 	const basePath = oldPath ?? path;
 	const [oldSize, info] = await Promise.all([baseBlobSize(root, base.ref, basePath), worktreeStat(abs)]);
-	const largest = Math.max(oldSize ?? 0, info?.size ?? 0);
+	return imagePayload(oldSize === null ? null : {
+		path: basePath,
+		size: oldSize,
+		version: base.oid
+	}, info === null ? null : {
+		path,
+		size: info.size,
+		version: worktreeVersion(info)
+	});
+}
+/**
+* 两侧元数据 → payload，工作区与提交两条路共用。**5MB 按侧卡**：任一侧超过就整个回 `too-large`；
+* `size` 取两侧里大的那个（取不到给 0）。两份各写时阈值或取哪一侧的体积漂开，同一张图在两个视图
+* 里一个说太大、一个照常画。
+*/
+function imagePayload(old, fresh) {
+	const largest = Math.max(old?.size ?? 0, fresh?.size ?? 0);
 	if (largest > 5242880) return {
 		kind: "too-large",
 		size: largest,
@@ -661,16 +995,8 @@ async function imageDiff(root, base, path, abs, oldPath) {
 	};
 	return {
 		kind: "image",
-		old: oldSize === null ? null : {
-			path: basePath,
-			size: oldSize,
-			version: base.oid
-		},
-		new: info === null ? null : {
-			path,
-			size: info.size,
-			version: worktreeVersion(info)
-		}
+		old,
+		new: fresh
 	};
 }
 /**
@@ -697,22 +1023,33 @@ async function imageDiff(root, base, path, abs, oldPath) {
 * 重命名退化成一个全新增文件。两个路径都来自 status 的 `2 ` 记录，无需额外查询。
 */
 async function trackedDiff(root, base, path, abs, oldPath, stat) {
-	if (stat?.binary) return imageMimeOf(path) === null ? { kind: "binary" } : imageDiff(root, base, path, abs, oldPath);
+	return gatedPatch(root, {
+		range: [base.ref],
+		path,
+		oldPath,
+		stat,
+		image: () => imageDiff(root, base, path, abs, oldPath),
+		size: async () => await worktreeSize(abs) ?? 0
+	});
+}
+async function gatedPatch(root, source) {
+	const { range, path, oldPath, stat } = source;
+	if (stat?.binary) return imageMimeOf(path) === null ? { kind: "binary" } : source.image();
 	if (stat && stat.lines > 5e4) return {
 		kind: "too-large",
-		size: await worktreeSize(abs) ?? 0,
+		size: await source.size(),
 		reason: "lines"
 	};
 	const args = oldPath ? [
 		"diff",
-		base.ref,
+		...range,
 		"-M",
 		"--",
 		path,
 		oldPath
 	] : [
 		"diff",
-		base.ref,
+		...range,
 		"--",
 		path
 	];
@@ -722,7 +1059,7 @@ async function trackedDiff(root, base, path, abs, oldPath, stat) {
 	} catch (cause) {
 		if (cause instanceof GitError && cause.kind === "overflow") return {
 			kind: "too-large",
-			size: await worktreeSize(abs) ?? 0,
+			size: await source.size(),
 			reason: "size"
 		};
 		throw cause;
@@ -794,10 +1131,53 @@ async function readDiff(root, query) {
 	const { abs, path } = await resolveInRepo(root, query.path, { follow: false });
 	const oldPath = query.oldPath ? (await resolveInRepo(root, query.oldPath, { follow: false })).path : void 0;
 	const [base, listed] = await Promise.all([resolveDiffBase(root), inIndex(root, path)]);
-	const stat = await readNumstat(root, base.ref, path, oldPath);
+	const stat = await readNumstat(root, [base.ref], path, oldPath);
 	if (listed || stat !== null) return trackedDiff(root, base, path, abs, oldPath, stat);
 	return untrackedDiff(root, path);
 }
+/**
+* 一次提交里单个文件的补丁（相对第一父）。三道闸与工作区那条同一份（`gatedPatch`）；两侧都在
+* 对象库里，没有未跟踪那条路、也不读磁盘——路径因此只过字面量那道边界（文件在工作区里可能
+* 早已不在），归一化后的那份照样拼进 `<rev>:<path>`。numstat 不回记录即「这次提交没动它」，
+* 是坏请求。
+*/
+async function readCommitDiff(repo, sha, query) {
+	const { root } = repo;
+	const path = literalRepoPath(root, query.path).path;
+	const oldPath = query.oldPath ? literalRepoPath(root, query.oldPath).path : void 0;
+	const resolved = await resolveCommit(repo, sha);
+	const parent = requireParent(resolved);
+	const { commit } = resolved;
+	const range = [parent, commit.sha];
+	const stat = await readNumstat(root, range, path, oldPath);
+	if (stat === null) throw new WorktreeError("not-found", "file not changed in this commit");
+	return gatedPatch(root, {
+		range,
+		path,
+		oldPath,
+		stat,
+		image: () => commitImageDiff(root, parent, commit.sha, path, oldPath),
+		size: async () => await baseBlobSize(root, commit.sha, path) ?? await baseBlobSize(root, parent, oldPath ?? path) ?? 0
+	});
+}
+/**
+* 提交里图片的两侧，**都读对象库**：旧侧 `<parent>:<旧路径或路径>`、新侧 `<sha>:<路径>`，与
+* 工作区 diff 的旧侧同一条 `cat-file -s`。`version` 是两端的对象名——提交不可变，这两个身份
+* 永远不会换内容。
+*/
+async function commitImageDiff(root, parent, sha, path, oldPath) {
+	const basePath = oldPath ?? path;
+	const [oldSize, newSize] = await Promise.all([baseBlobSize(root, parent, basePath), baseBlobSize(root, sha, path)]);
+	return imagePayload(oldSize === null ? null : {
+		path: basePath,
+		size: oldSize,
+		version: parent
+	}, newSize === null ? null : {
+		path,
+		size: newSize,
+		version: sha
+	});
+}
 
 //#endregion
 //#region src/server/git/file.ts
@@ -823,6 +1203,82 @@ async function readFileContent(root, path) {
 	}
 }
 
+//#endregion
+//#region src/server/git/refs.ts
+/**
+* 十一段，**每段都以 `%00` 收尾（含最后一段）**：`for-each-ref` 没有 `-z`，记录之间是换行，于是
+* 整份输出按 NUL 切开后恰好十一段一组、下一条的 refname 前面多一个换行。后五段是解引用形态——附注
+* 标签的本体是标签对象，作者与时间为空、主题是标签说明，`%(*…)` 才是它指向的对象。只用 git 2.11
+* 已有的 atom：`refname:lstrip` 更晚，前缀在下面剥。
+*/
+const REF_FORMAT = "--format=%(refname)%00%(symref)%00%(objectname)%00%(authorname)%00%(committerdate:unix)%00%(subject)%00%(*objectname)%00%(*objecttype)%00%(*authorname)%00%(*committerdate:unix)%00%(*subject)%00";
+const FIELDS = 11;
+/**
+* `for-each-ref` 的 argv，**整条是字面量**，冒烟逐段钉着它：atom 里有 `%(signature)` 一族，用上就
+* 是每条 ref 起一次 gpg，而白名单只看子命令。不带 `--sort`——三组本来就要在 JS 里分，排序一起做，
+* 不多一段要钉的参数面。
+*/
+const REF_ARGS = [
+	"for-each-ref",
+	REF_FORMAT,
+	"refs/heads",
+	"refs/remotes",
+	"refs/tags"
+];
+/** 前缀 → 组。次序就是三组在列表里的次序。 */
+const KINDS = [
+	["refs/heads/", "local"],
+	["refs/remotes/", "remote"],
+	["refs/tags/", "tag"]
+];
+const ORDER = {
+	local: 0,
+	remote: 1,
+	tag: 2
+};
+/** `REF_FORMAT` 的解析：十一段一组切，滤掉 symref，附注标签取解引用那几段。 */
+function parseRefs(output) {
+	const segments = output.split("\0");
+	const refs = [];
+	for (let i = 0; i + FIELDS <= segments.length; i += FIELDS) {
+		const [rawName = "", symref = "", objectSha = "", objectAuthor = "", objectTime = "", objectSubject = "", peeledSha = "", peeledType = "", peeledAuthor = "", peeledTime = "", peeledSubject = ""] = segments.slice(i, i + FIELDS);
+		if (symref !== "") continue;
+		const refname = rawName.replace(/^\n/, "");
+		const match = KINDS.find(([prefix]) => refname.startsWith(prefix));
+		if (match === void 0) continue;
+		const [prefix, kind] = match;
+		const [sha, author, time, subject] = peeledSha === "" ? [
+			objectSha,
+			objectAuthor,
+			objectTime,
+			objectSubject
+		] : peeledType === "commit" ? [
+			peeledSha,
+			peeledAuthor,
+			peeledTime,
+			peeledSubject
+		] : [
+			peeledSha,
+			"",
+			"",
+			""
+		];
+		refs.push({
+			kind,
+			name: refname.slice(prefix.length),
+			sha,
+			author,
+			time: Number(time) || 0,
+			subject
+		});
+	}
+	return refs.sort((a, b) => ORDER[a.kind] - ORDER[b.kind] || b.time - a.time);
+}
+/** 本地、远程、标签三组。空仓库与没有任何 ref 时 git 输出为空、exit 0，回一个空列表。 */
+async function listRefs(root) {
+	return { refs: parseRefs(await runGitStrict(REF_ARGS, root)) };
+}
+
 //#endregion
 //#region src/server/git/operation.ts
 /**
@@ -946,6 +1402,7 @@ function parseStatus(raw) {
 	let head = "";
 	let detached = false;
 	let upstream = null;
+	let oid;
 	for (let i = 0; i < segments.length; i += 1) {
 		const rec = segments[i];
 		if (!rec) continue;
@@ -954,7 +1411,9 @@ function parseStatus(raw) {
 				const sp = rec.indexOf(" ", 2);
 				const key = sp === -1 ? rec.slice(2) : rec.slice(2, sp);
 				const value = sp === -1 ? "" : rec.slice(sp + 1);
-				if (key === "branch.head") {
+				if (key === "branch.oid") {
+					if (isOid(value)) oid = value;
+				} else if (key === "branch.head") {
 					head = value;
 					detached = value === "(detached)";
 				} else if (key === "branch.ab") {
@@ -1020,7 +1479,8 @@ function parseStatus(raw) {
 		branch: {
 			head,
 			detached,
-			upstream
+			upstream,
+			...oid === void 0 ? {} : { oid }
 		},
 		files
 	};
@@ -2094,7 +2554,7 @@ async function startServer(repo, options = {}) {
 			}
 			/**
 			* 图片字节，**唯一一个正文不是 JSON 的 API 端点**。`path` / `side` 都必填：`old` 是
-			* diff 基准里的 blob、`new` 是工作区那份。只服务图片扩展名表里的路径、`Content-Type`
+			* diff 基准里的 blob、`new` 是工作区那份；带 `commit` 时两侧都读对象库（第一父 / 提交本身）。只服务图片扩展名表里的路径、`Content-Type`
 			* 按表给精确 MIME（`nosniff` 之下类型错一个字浏览器就不画），非图片一律 400——判据与
 			* 5MB 那道闸都在 git 那侧，这里只把字节发出去。前端加的 `v=` 戳这里不看。
 			*/
@@ -2109,10 +2569,57 @@ async function startServer(repo, options = {}) {
 					sendError(res, 400, "bad-request", "side must be old or new");
 					return;
 				}
-				const image = await readImageBytes(repo.root, path, side);
+				const commit = url.searchParams.get("commit");
+				const image = await readImageBytes(repo, path, side, commit ?? void 0);
 				send(res, 200, image.buffer, image.mime);
 				return;
 			}
+			/**
+			* 提交列表的一页。`head` 缺省即「从 HEAD 起」，响应里回传的 `head` 就是之后各页要带的锚点；
+			* `skip` 缺省为 0。两者的合法性（完整对象名、非负整数）在这里与 git 那侧各判一半：
+			* 数字归这里，对象名归 `assertOid`——它也是 `/api/commit` 那条路的同一把钥匙。
+			*/
+			case "/api/commits": {
+				const head = url.searchParams.get("head");
+				const rawSkip = url.searchParams.get("skip") ?? "0";
+				if (!/^\d{1,9}$/.test(rawSkip)) {
+					sendError(res, 400, "bad-request", "skip must be a non-negative integer");
+					return;
+				}
+				sendJson(res, 200, await listCommits(repo.root, {
+					head: head ?? void 0,
+					skip: Number(rawSkip)
+				}));
+				return;
+			}
+			case "/api/commit": {
+				const sha = url.searchParams.get("sha");
+				if (!sha) {
+					sendError(res, 400, "bad-request", "sha is required");
+					return;
+				}
+				sendJson(res, 200, await readCommit(repo, sha));
+				return;
+			}
+			/** 一次提交里单个文件的补丁（相对第一父）。`oldPath` 只有重命名传，与 `/api/diff` 同。 */
+			case "/api/commit-diff": {
+				const sha = url.searchParams.get("sha");
+				const path = url.searchParams.get("path");
+				if (!sha || !path) {
+					sendError(res, 400, "bad-request", "sha and path are required");
+					return;
+				}
+				const oldPath = url.searchParams.get("oldPath");
+				sendJson(res, 200, await readCommitDiff(repo, sha, {
+					path,
+					...oldPath ? { oldPath } : {}
+				}));
+				return;
+			}
+			/** 分支列表：本地、远程、标签。无参数，前端每次打开列表时取一次。 */
+			case "/api/refs":
+				sendJson(res, 200, await listRefs(repo.root));
+				return;
 			/** SSE。**三道校验在上面已经统一走过**，这里没有例外分支。 */
 			case "/api/events": {
 				const headers = {
@@ -2162,6 +2669,10 @@ async function startServer(repo, options = {}) {
 				sendError(res, 400, cause.code, cause.message);
 				return;
 			}
+			if (cause instanceof GitError && cause.kind === "missing-object") {
+				sendError(res, 400, "unsupported", "not available locally (partial clone); difftab does not fetch");
+				return;
+			}
 			const detail = cause instanceof Error ? cause.message : String(cause);
 			sendError(res, 500, "internal", detail);
 		});