变更、代码评审与 Git
在 Halo 的「变更」里查看工作区 Git 仓库的改动和差异，让 AI 做快速评审或团队评审，再暂存、提交并推送。
直接对 Halo 说
把刚才的改动提交并推送
Halo 会在工作区里用自己的命令行运行 git：看一下改了什么，写好提交信息，提交后推送到远程仓库，再告诉你提交号。
前提：工作区文件夹是 Git 仓库，并且这台电脑上的 Git 已经能推送到这个远程仓库（比如你在终端里推送过一次）。
AI 评审要在 变更 里点按钮开始，Halo 不能在对话里替你启动一次评审。
开始之前
打开变更
- 在会话页，点顶栏的 ⋯ 更多 › 变更（「评审、暂存并提交 Git 变更」）。也可以按 ⌃⇧G。在 macOS 上是 Control 键，不是 Command 键。
- 窗口很窄或在 Android 应用里时，点顶栏的 更多，再点 变更。
- 画布里打开一个变更标签页，顶栏显示仓库名和当前分支。
变更有三页，在标签页顶部切换：
| 页面 | 用来做什么 |
|---|---|
| 变更 | 文件列表、差异、暂存和提交 |
| 总览与评审（带「AI」标记） | 改动统计、按文件夹分布，以及 AI 评审 |
| 提交图 | 只读的提交历史，见 提交图 |
每个工作区只有一个变更标签页。打开或切回这个标签页、Halo 窗口回到前台、点 刷新 时，内容会重新加载。你看着的时候有文件被改动，顶部会出现「N 个文件有新变更」，点 刷新 更新，点 关闭 忽略。Halo 不会在后台轮询，也不会在启动时运行 Git。
在对话里点评审任务卡片，也会打开变更。通过 远程访问 打开的浏览器和 Android 应用也能用变更，Git 在运行 Halo 的那台电脑上执行。
没有工作区时，菜单里没有 变更。只想看 AI 在某一条回复里改了哪些文件，用回复下面的 查看变更，不需要 Git。
找到哪些仓库
Halo 在两个位置找 Git 仓库：工作区文件夹本身，以及它下一级的文件夹。
- 文件夹里有
.git就算一个仓库。.git是文件的情况（工作树、子模块）也算。 - 以
.开头的文件夹和符号链接文件夹会被跳过，最多检查 1,000 个子文件夹。 - 更深层的仓库找不到。想看它，让工作区直接指向那个文件夹。
找到多个仓库时，顶栏的仓库名变成一个选择器，标题是「此空间中的仓库」，每一项显示分支和相对路径。工作区文件夹本身排在最前，其余按名称排序。
当前分支显示在仓库名旁边。HEAD 处于分离状态时显示「HEAD 分离于 <提交号>」，仓库还没有提交时显示「尚无提交」。变更里不能切换分支。
选择比较范围
点顶栏的比较范围（「比较：…」）选择要看哪一部分改动：
| 选项 | 比较的是 | 说明 |
|---|---|---|
| 未提交的变更 | HEAD 和工作区文件，包括未跟踪的新文件 | 默认选项 |
| 已暂存的变更 | HEAD 和暂存区 | — |
| 自上次评审以来 | 上次开始 AI 评审时的文件和现在 | 还没评审过时不能选，提示「请先进行一次评审」 |
| 与分支比较… | 从当前分支和所选分支的分叉点到现在 | 从 分支 或 远程分支 里选，选择器注明「从分叉点开始比较」 |
| 与提交比较… | 所选提交和现在的工作区文件 | 从 标签 或 最近的提交 里选 |
- 仓库还没有提交时，与分支比较… 和 与提交比较… 不能选。
- 选择器可以搜索，最多列出 60 项，提交号显示前 7 位。
- 选了分支或提交后，范围显示为「与 <分支或提交> 比较」。
- 在 提交图 里点一个提交，会多出一个范围「提交 <提交号>」：这个提交和它的第一个父提交比较。
没有改动时，变更显示「无变更」「没有已暂存的内容」「自上次评审以来没有变更」「与 <分支或提交> 无差异」或「空提交」。
文件列表
在 未提交的变更 范围里，文件分成三组：冲突、已暂存的变更、变更。其他范围只有一组 变更。
- 冲突 组注明「请在终端中解决这些问题，或让 AI 处理。」变更里不能编辑冲突。
- 用 树形 / 列表 切换显示方式，默认树形。
- 在「筛选文件（例如 src/**）」里输入路径筛选，点 清除筛选 恢复。
- 隐藏生成文件 默认打开：隐藏锁文件、压缩文件、快照，以及在
.gitattributes中标记为linguist-generated的文件。列表会显示「已隐藏 N 个生成文件」，点 显示 查看。 - 列表最多显示 5,000 个文件，超出时提示「正在显示前 N 个文件」。
- 文件列表的宽度可以拖动，双击分隔线恢复默认。画布较窄时，文件列表收进 文件列表 抽屉。
并排显示、折叠、列表宽度、树形和隐藏生成文件这些选择保存在当前设备上。
阅读差异
差异按文件卡片从上往下排列。工具栏上有：
| 控件 | 作用 |
|---|---|
| 上一处变更 / 下一处变更 | 在改动之间跳转，快捷键 Shift F7 / F7 |
| 并排显示 | 默认打开。画布宽度不足 640 px 时改为单栏，提示「并排显示需要更宽的画布」 |
| 折叠无变更区域 | 默认打开 |
| 折叠所有文件 / 展开所有文件 | 一次收起或展开所有卡片 |
差异是只读的，不能在里面直接修改。要改文件，点 在编辑器中打开，文件会在画布的编辑器标签页里打开。
选中差异里的一段文字，可以 添加到对话，引用会带上文件、哪一侧和比较范围，见 会话里的引用。
大文件的限制：
| 情况 | 显示 |
|---|---|
| 某一侧超过 2 MiB | 「过大，无法显示（大小）」 |
| 二进制文件 | 「二进制文件」和大小 |
| 改动 1,500 行及以上，或生成文件 | 「差异较大 · N 行」，点 加载差异 才显示 |
| 整体差异非常大 | 「大型差异 · 一次显示一个文件」 |
暂存、取消暂存和丢弃
- 把鼠标移到文件行上。未暂存的文件有 暂存 和 丢弃，已暂存的文件有 取消暂存。
- 要整组操作，点组标题上的 全部暂存 或 全部取消暂存。差异卡片上也有 暂存文件 / 取消暂存文件。
- 暂存和取消暂存立即生效，不会确认。
冲突文件不能暂存、取消暂存或丢弃。变更里只能整个文件暂存，不能按代码块或按行暂存。
丢弃 每次都会先确认：
- 已跟踪的文件：「丢弃对 <文件名> 的变更？」「此操作在 Halo 中无法撤销。」只丢弃工作区里的改动，已暂存的部分保留。
- 未跟踪的新文件：「将 <文件名> 移至回收站？」「Git 中没有这个新文件的副本。你可以从回收站恢复它。」文件会移到系统回收站，不会被直接删除。
注意
丢弃已跟踪文件的改动后，Halo 里没有撤销。没把握时先提交，或先复制一份。
提交和推送
提交框在文件列表下方。它显示当前分支名，但不能在这里切换分支。
- 暂存要提交的文件。
- 在「提交信息（按 ⌘↵ 提交）」里写提交信息。变更不会替你生成提交信息。
- 点 提交 N 个已暂存文件，或按 ⌘↵。没有暂存文件时按钮提示「暂存要提交的文件」，没写提交信息时提示「输入提交信息」。
- 想提交后立刻推送，点主按钮旁边的 ▾（更多提交选项），选 提交并推送。
- 想改上一次提交，在同一个菜单里选 修正上一次提交。提交信息框为空时，沿用原来的提交信息。仓库还没有提交时不能选。
提交会运行仓库里的提交钩子。钩子拒绝时显示「提交钩子拒绝了本次提交。」，点 显示输出 查看原因。
推送时，分支已有上游就直接 git push；没有上游，就推送到 origin（或唯一的远程仓库）并设为上游。提交成功但推送失败时，显示「已提交 <提交号>，但推送失败」，提交仍然保留。
提交最长等 5 分钟，推送和拉取最长等 3 分钟。
同步和发布分支
分支名旁边的按钮显示 ↑待推送 ↓待拉取 的提交数。这些数字来自上一次获取（fetch），鼠标悬停时提示「计数来自上次获取。点击即可拉取并推送。」
点这个按钮，Halo 会：
- 运行
git pull --ff-only，只做快进，不合并也不变基。 - 本地有待推送的提交时，再推送。
点下就执行，不会确认。完成后提示「已与 <上游> 同步」。
分支还没有上游时，按钮显示 发布分支。点它会把分支推送到远程仓库并设为上游，完成后提示「已发布 <分支名>」。
不能快进时（本地和远程各有新提交），同步会停下，请在终端里合并，或在对话里让 AI 处理。
提交图
从 3.0.4 起，变更有第三页 提交图：只读的提交历史，每条分支线一条泳道，每次加载 300 个提交，往下滚动继续加载。
- 用 所有分支 选择要看的分支。
- 在「按作者筛选（Enter）」或「搜索提交信息（Enter）」里输入后按 Enter。
- 点一个提交，变更 页会显示这个提交和它第一个父提交的差异，比较范围变成「提交 <提交号>」，提交框里显示这个提交的标题。
提交图里不能检出或重置。
AI 评审
AI 评审读当前比较范围里的改动和周边代码，写一份评审报告。它在这个工作区里新建一个评审对话，在后台运行：你当前的对话不受影响，也不会切到新对话。
- 在变更里选好 比较范围，比如 未提交的变更。
- 切到 总览与评审，找到 AI 评审 卡片（「将在此空间新建一个评审对话」）。
- 点 快速评审 或 团队评审，评审立即开始，不会再确认。
- 卡片上显示进度，并注明「你可以离开此页面」。想中止，点 停止。
- 评审完成后，报告显示在卡片里。
| 快速评审 | 团队评审 | |
|---|---|---|
| 谁来评审 | 一个智能体读改动和周边代码，写出报告 | 三个智能体分别评审架构、回归问题以及性能与提示词，再相互质疑彼此的发现 |
| 通常耗时 | 1–3 分钟 | 5–15 分钟 |
| Token 消耗 | — | 约为快速评审的 4–6 倍 |
| 项目规范 | 先读 AGENTS.md、CLAUDE.md 等规范文件 | 同左 |
注意
团队评审会启动 3 个子智能体，约消耗 4–6 倍 Token。评审用的是工作区平常用的模型和账号，费用由你的账号或 API 提供商收取。
评审时 AI 只读不写：不改文件、不构建、不执行 Git 写操作。仓库里的内容只当作材料，不当作给 AI 的指令。范围里没有改动时不能评审（「没有可评审的变更」）。改动的文件超过 400 个时，多出的部分按文件夹汇总。团队评审暂时用不了时，卡片显示「团队评审暂不可用」；团队工具中途失败时，会退回一个评审者，报告里会说明。
读评审报告
报告用界面语言写成，固定分为五部分：结论、必须修、需要你决定、建议、结构摘要。每条发现都标出 路径:行号，点链接打开那个文件的差异页。
卡片上的操作：
| 操作 | 作用 |
|---|---|
| 打开对话 | 打开评审对话。你可以接着说，比如「把必须修的问题改掉」 |
| 将完整报告添加到对话 | 把整份报告作为引用放进输入框 |
| 重新评审 ▾ | 再评审一次，选「快速评审 · 单个智能体」或「团队评审 · 3 个子智能体，消耗更多 Token」 |
卡片还显示评审时间、用时和 Token 数。评审之后文件又变了，卡片提示「基于 <时间> 时的变更，之后又有 N 个文件被修改。」
- 每次开始评审，Halo 会给当时的文件拍一个快照，自上次评审以来 范围就是和它比较。快照是 Git 里没有被引用的对象，
git gc可能清理掉它（默认约两周），之后显示「上次评审的快照已不可用」。 - 每个仓库只保留最近一次评审。删掉评审对话后，卡片显示「评审对话已被删除」。
- 评审对话是一个普通对话，标题是「评审 · <范围> · N 个文件」，出现在会话列表和 任务面板 里。第一条消息是评审任务卡片，点它回到变更的总览页。
- 报告不会作为行内批注写进差异里。
回复下的查看变更
AI 在一条回复里用文件工具改了文件，回复下面会出现「修改了 N 个文件 · +增加 −删除 · 查看变更」。
- 点 查看变更。画布打开一个只读的标签页，标题是「<时间> 的回复」，顶部写着「此回复中编辑了 N 个文件 · 只读」。
- 每次编辑显示为一段差异，整文件写入显示写入的全部内容。
- 点 转到回复 回到那条回复，点 打开文件 或 在编辑器中打开 查看文件。
这个视图不需要 Git，也没有仓库、比较范围、暂存和提交。它注明「仅显示通过文件工具所做的编辑，通过命令所做的修改不包含在内。」AI 用命令行改的文件，要在 变更 里看。
安装 Git
变更需要 Git 2.23 或更新版本。Halo 第一次需要 Git 时才去找它，不在启动时检查。找不到时，最多每 60 秒重新找一次。
Halo 依次查找 PATH 里的 git、/opt/homebrew/bin、/usr/local/bin 和 /usr/bin。
没装 Xcode Command Line Tools 的 Mac，/usr/bin/git 无法运行，变更显示「Git 无法在这台电脑上运行」。在终端里运行下面的命令，装完后点 重试：
xcode-select --installHalo 从不弹出账号密码、SSH 或 GPG 的输入框，联网的 Git 操作在后台运行，不会等你输入。推送前，先在终端里对这个仓库推送一次，让 Git 保存好凭据。
Halo 自动读取仓库时，不会运行仓库配置里指定的程序（过滤器、fsmonitor、外部 diff、textconv）。你点击的写操作按 Git 平常的方式运行，包括钩子、LFS 和凭据助手。
完成
变更里列出了改动的文件，提交后这些文件从「未提交的变更」里消失；AI 评审卡片里出现带「结论」和「必须修」的报告。看到这些，就说明变更和 AI 评审都在正常工作。
遇到问题
此空间不是 Git 仓库
Halo 只在工作区文件夹和它下一级的文件夹里找仓库。确认仓库在这两个位置之一，不是更深的目录，也不是以 . 开头的文件夹或符号链接。必要时在 工作区 里把文件夹改成仓库所在的文件夹。
Git 未安装
按 安装 Git 里你的系统操作。Windows 桌面版可以直接点 安装 Git。
Git 无法在这台电脑上运行
macOS 缺少 Xcode Command Line Tools。在终端里运行 xcode-select --install，装完后点 重试。
Git 需要你先登录。请在终端中推送一次，然后重试。
Halo 不会替 Git 输入凭据。在终端里对这个仓库运行一次 git push，按提示登录，然后回到变更再试。
Git 还不知道你是谁
在终端里设置提交者信息，再提交：
git config --global user.name "zhangsan"
git config --global user.email "zhangsan@example.com"无法快进。请在终端中合并，或让 AI 来完成。
本地和远程各有新的提交，同步只做快进。在终端里合并或变基，或者在对话里让 AI 处理，然后再点同步。
远程仓库有你尚未获取的提交。请先同步，再推送。
先点分支旁的同步按钮拉取，再提交并推送。
拉取会覆盖你未提交的变更
先提交或丢弃这些改动，再同步；也可以在终端里自己处理。
你当前不在任何分支上，因此没有可推送的内容
HEAD 处于分离状态。在终端里切换到一个分支，或让 AI 切换。变更里不能切换分支。
另一个 Git 进程正在使用此仓库
终端或其他工具正在操作这个仓库。等它结束后重试。
Git 响应时间过长。请重试。
提交超过 5 分钟、推送或拉取超过 3 分钟没有完成。检查网络和提交钩子，然后重试。
「自上次评审以来」不能选
还没有做过 AI 评审，或上次评审的快照已被 git gc 清理。重新评审一次即可。
AI 改了文件，回复下的查看变更里却没有
回复的变更视图只显示 AI 用文件工具做的编辑，命令行做的修改不在里面。打开 ⋯ 更多 › 变更 查看仓库里的全部改动。
下一步
- 从 Claude Code / Codex 迁移：用已有的订阅、
CLAUDE.md和技能在 Halo 里写代码 - Agent 引擎：选择 Claude Code、Codex 等引擎来执行编码任务
- 工作区：把工作区指向你的项目文件夹