Git

在会话内直接完成暂存、提交、分支、贮藏、推送与拉取，并对任何可能导致工作丢失的操作设有安全防护。

Kaiwu 可以在会话的工作区中直接调用 Git。审查代码改动与提交代码一气呵成，无需切换到终端。

但 Kaiwu 特意没有提供历史记录修改功能。应用内不包含 reset、rebase、cherry-pick 或 drop 等操作。这类操作一旦在手机上误触，就会导致心血付诸东流。它们应当留在能够使用 shell、且精力高度集中的场合下进行。

Git 的写操作受权限控制，需前往 设置 → 功能 → 版本控制操作手动开启。该功能目前处于实验阶段，且默认处于关闭状态。如果仅读取代码仓库状态和差异，无需开启任何权限—— 详见代码对比与审查。

Git 标签页是当前会话的代码仓库状态界面。

支持的操作

审查已修改的文件及差异
暂存与取消暂存改动
针对整份文件或支持的特定行/代码块（hunk）进行选择
提交暂存的内容
开启 Git 写操作权限时，执行 fetch、pull 与 push
当前目录不是代码仓库时，进行 Git 初始化
将本地仓库发布到 GitHub
切换分支
创建分支
发布尚未关联上游的分支
打开、复用及检出 PR 或 MR
在基于独立工作树的会话中打开 PR 或 MR
查看和管理由 Kaiwu 创建的暂存记录（stash）
浏览提交历史，查看历史提交的差异

代码仓库配置

通过 Kaiwu 初始化 Git

如果当前选择的目录不是 Git 仓库，Kaiwu 不会直接报错中止，而是会提供一个初始化操作选项。

确认之后，Kaiwu 会针对该目录执行 git init，随后刷新 Git 状态。

初始化包含的操作：

为当前目录创建仓库元数据
保持目录原有内容不变
不会暂存文件
不会生成初始提交
不会创建或发布远程仓库

如果在执行该操作时，当前目录已经是 Git 仓库，Kaiwu 会将其视为成功并刷新状态。

将本地仓库发布到 GitHub

当 Git 仓库尚未检测到 GitHub 远程地址时，你可以直接在 Kaiwu 的 Git 标签页中将其发布至 GitHub。

发布表单支持配置以下项：

GitHub 所有者（包含当前认证账号有权限的组织）
仓库名称
可见性：私有、公开，或在 GitHub 支持该所有者时选择内部公开
HTTPS 或 SSH 形式的远程 URL
创建仓库后是否推送当前分支
所选远程名称已存在时的处理方式

Kaiwu 会先创建 GitHub 仓库，随后通过自有的 SCM 后端更新本地 Git 远程配置。即使使用 GitHub CLI 作为网络适配层，Kaiwu 也不会让 gh repo create 直接修改本地 Git 状态。

认证匹配顺序：

Kaiwu 中已关联的 GitHub 账号 Token
本地或受管环境中已完成认证的 gh CLI

若两者均未提供，Kaiwu 会说明缺失的认证信息，并引导你关联 GitHub 账号，或安装/认证 gh。

当前支持范围：

支持发布到 GitHub 仓库。
目前不支持直接从 Kaiwu 创建 GitLab 和 Bitbucket 仓库。
发布操作完全由用户主动触发；未经用户明确操作，Kaiwu 绝不会自动创建仓库、远程分支、提交或执行推送。

远程操作

无需离开当前会话，即可在远程操作区域完成日常的网络同步。

Kaiwu 会根据仓库状态和支持的功能，提供以下操作：

Fetch：更新远程引用
Pull：当前分支可快进（fast-forward）时拉取
Push：当前分支已关联上游时推送
发布分支：当前分支尚未关联上游时显示
发布到 GitHub：当前仓库没有 GitHub 远程地址时显示

发布分支

如果当前分支尚未设置上游追踪分支，Kaiwu 会将常规的推送操作替换为发布。

与桌面端 Git 客户端类似，发布操作会一步完成设置上游并推送分支。

你可以从分支菜单触发该操作；在需要时，也可以直接在常规显示 push/pull 的远程操作区中触发。

远程操作的安全机制

Kaiwu 在远程工作流上保持相对保守的策略：

pull 仅支持快进（fast-forward）模式
pull 要求工作树必须保持干净
当 HEAD 处于游离（detached）状态时禁止 push
本地分支落后于上游分支时禁止 push
存在冲突时禁止 push、pull 和 revert

这些规则是后端强制遵循的不变式。Kaiwu 会直接在界面上解释被阻止的原因，绝不提供可能被 Git 拒绝、或可能导致重写历史的操作。

提交历史

历史子标签页展示当前仓库过去的提交记录。

点开某次提交会开启一个详情标签页，其差异查看逻辑与“审查”功能完全一致：

差异渐进式渲染
文件区块支持折叠
详情面板保留标签页状态

这种设计旨在让“查看当前改动”与“检查历史提交”遵循相同的使用直觉，而非割裂成两套互不相干的工具。

典型使用场景：

查看先前某次提交修改了哪些内容
将当前改动与已知的稳定提交进行比对
打开历史提交排查后，随时切回当前的审查界面

提交暂存的内容

提交编辑器位于 Git 标签页的底部。

提交信息生成器

Kaiwu 在提交编辑器中内置了生成提交信息功能。

该功能默认开启。
它通过单次执行任务给出建议的提交信息。
在适用情况下，它会以当前选中的暂存范围作为输入。
最终填入的是建议的提交信息文本，而非生成器内部使用的结构化响应载荷。
你可以在设置 → 版本控制中选择后端模型并添加自定义指令。

推荐使用场景：

需要快速生成符合 Conventional Commit 规范的提交信息
仅暂存了仓库的部分改动，希望提交信息精准匹配该范围
先生成草稿，再手动微调后提交

生成器仅提供文本建议，绝不会自动执行提交。

精细化暂存提交

基于 SCM 后端及其能力，Kaiwu 支持多种提交流程：

文件级选择
代码行/代码块级选择
整个工作树直接提交

日常暂存无需切出到终端，即可按需组织出粒度更清晰的提交。

分支管理

Git 标签页顶部的分支摘要展示了当前分支及分支状态。

在分支菜单中，你可以：

查看当前所在分支
切换到其他分支
创建新分支
在当前分支没有上游时将其发布
将 PR 或 MR 检出到当前工作树
在基于独立工作树的会话中打开 PR 或 MR

存在未提交改动时切换分支

当本地存在未提交改动并尝试切换分支时，Kaiwu 提供两种处理策略：

将改动保留在当前分支
将改动带到目标分支

除非你在设置中修改了分支切换偏好，否则 Kaiwu 默认每次都会询问。

将改动保留在当前分支

Kaiwu 会针对当前分支创建或更新一条受管暂存（stash），随后检出目标分支。

适用场景：

当前的修改属于当前分支
希望在目标分支上获得干净的检出环境

将改动带到目标分支

Kaiwu 会尝试将未提交的改动顺延带到新分支。

如果本地改动可能被覆盖而导致 Git 阻止检出，Kaiwu 会自动转入临时的 stash/apply 流程，确保改动随你一起迁移。

适用场景：

不小心在错误的分支上开始编写代码
未提交的修改需要带到新分支继续开发

受管暂存

在分支切换工作流中，Kaiwu 会创建并跟踪自有的 stash 记录。

这些记录在 Git 标签页中显示为受管暂存。

在暂存界面中，你可以：

查看所有 Kaiwu 受管暂存记录
打开暂存详情视图
检查暂存差异
恢复暂存（restore）
丢弃暂存（discard）

何时会生成暂存

常见情况：

切换分支时选择了将改动保留在当前分支
Kaiwu 需要借助临时暂存安全完成将改动带到目标分支流程

临时暂存是分支切换的内部安全机制。一旦带入并应用成功，该记录会自动清理；如果 Git 提示存在冲突，Kaiwu 会保留该暂存，以便你手动排查或恢复。

恢复与丢弃

恢复：将暂存改动重新应用到工作树，操作成功后自动删除该暂存记录
丢弃：直接删除暂存记录，不应用改动

如果在恢复过程中 Git 报告冲突，Kaiwu 会保留该暂存，绝不静默丢弃。

锁文件恢复

如果在分支检出期间 Git 提示存在残留的 index.lock，Kaiwu 会弹出针对性的恢复提示。

经你确认后，Kaiwu 会向 Git 查询具体的锁路径，并仅移除该仓库 Git 目录下经过验证的 index.lock 文件。随后重新尝试刚才失败的检出操作一次。

在锁文件恢复流程中，Kaiwu 不会执行 git clean、git reset 或更大范围的代码仓库清理。

安全红线

只要操作存在丢失代码的风险，Kaiwu 宁可直接拒绝，也不会盲目尝试：

初始化仓库和发布到 GitHub 都必须经过你的明确确认。
只要仓库状态显示当前操作不安全，发布、push 和 pull 都会被直接阻止。
pull 仅支持快进，且 pull 与 revert 都要求干净的工作树。
HEAD 处于游离状态或存在冲突时，禁止 push、pull 和 revert。
本地分支落后于上游分支时，禁止 push。
残留锁恢复只会移除仓库自有的 Git 目录下经过验证的 index.lock。
reset、rebase、cherry-pick、drop 等破坏性历史编辑操作完全不在应用中暴露。

使用限制

行级暂存仅适用于文本差异；二进制文件和冲突情况回退为整文件操作。
提交信息生成器依赖守护进程对执行任务的支持。
仓库发布目前仅支持 GitHub。暂不支持发布到 GitLab 和 Bitbucket。

Sapling

Git 并非唯一的后端支持。Kaiwu 同时支持了 Sapling，但它既没有达到与 Git 同等的完备度，也不是完全只读——因此，在将 Kaiwu 接入 Sapling 工作区前，建议了解其支持边界：

领域	Sapling
读取	状态、文件差异、提交差异、日志
提交	创建提交、提交指定路径、撤回提交（back out）
工作副本	放弃改动
远程操作	Fetch、pull 和 push——但不支持发布新仓库
分支与暂存	不支持
行级暂存	不支持——仅支持路径级（文件级）选择

所有涉及分支与暂存的功能均为 Git 独享，单行级暂存亦是如此。

Git

Git