Git 版本控制参考
Git 面板管理当前 app 工作区的版本。需要按完整团队流程操作时，参见使用 Git 与启心代码管理协作。
何时查这页
- 不确定 Stage、Commit、Pull、Push 的顺序。
- 想接入启心代码管理或其他远程仓库。
- 需要查看旧提交、创建分支或处理认证失败。
- 准备让 AI 生成提交信息，但不确定它会读取哪些变更。
实际入口
编辑器左侧 Activity Bar 点击 Git 图标。数字徽标表示当前未提交变更数量。
Git 面板上方提供：
- 当前分支菜单和新建分支。
- 当前远程菜单、启心代码管理和添加远程。
- Commit 信息输入框。
- Refresh、Fetch、Pull、Push 和 Commit 操作。
下方在 Changes 与 History 之间切换。
Changes
Changes 按未暂存和已暂存显示当前修改。点击文件打开 diff。
| 操作 | 作用 | 风险 |
|---|---|---|
| Stage | 把文件加入下一次 Commit | 不会自动 Push |
| Unstage | 从本次 Commit 移出，保留工作区修改 | 低 |
| Discard | 放弃未暂存修改；未跟踪文件会被删除 | 不可撤销 |
| Commit | 把 staged 变更记录到当前分支 | 仍只在本机 |
| Push | 把本地分支提交发送到所选远程 | 会影响团队共享状态 |
推荐每次只 Stage 一个业务目的相关的文件。Commit 前逐个检查 diff，确保没有密钥、客户数据或机器专属配置。
分支与历史
分支
- 分支菜单显示本地分支和已获取的远程分支。
- 创建并切换新分支适合独立功能或修复。
- 切换前先保存编辑器内容并处理未提交变更。
History
History 显示提交、当前 HEAD、分支和 tag 标记。双击历史提交会切到该提交用于查看。
如果切换后处于 detached HEAD，不要直接继续团队开发。需要从旧版本继续时，创建新分支。工作区有修改或冲突时，Theseus 会要求选择保留、stash 或放弃；理解影响后再确认。
远程与同步
启心代码管理
新建 app 时可直接启用。已有 app 可从远程菜单连接或切换到启心代码管理。使用前需要 Qixin 登录、有效账号名称和对应权限。
连接后仍要人工选择 Stage 和 Commit；启用远程不会把所有未提交修改自动提交。
自定义远程
从远程菜单选择添加远程，填写名称和 URL。不要在 URL 中嵌入用户名、密码或 token。
Fetch、Pull、Push
| 操作 | 用途 |
|---|---|
| Fetch | 更新远程分支信息，不改当前工作区 |
| Pull | 把远程当前分支合入本地；可能产生冲突 |
| Push | 上传当前分支提交 |
开始任务先 Fetch/Pull，完成验证后 Commit/Push。Push 前再次确认当前分支和远程。
AI 生成 Commit 信息
先 Stage 目标文件，再点击生成按钮。AI 只应基于 staged diff 生成候选信息；人工检查并编辑后再 Commit。
提交信息应说明业务结果，而不是只写“update”或文件名。不要因为信息由 AI 生成就跳过 diff 审查。
凭据
- HTTPS 认证失败时，按面板提示输入用户名和访问令牌后重试。
- SSH 远程使用本机 SSH key 和 agent。
- 不要把凭据写入远程 URL、app 文件、提交信息或 AI 对话。
Git 面板只在桌面编辑器可用；运行页和 runtime-only 环境不提供工程 Git 操作。ZIP 导出也不包含 Git 历史。
成功表现
- 当前分支和远程与团队计划一致。
- Commit 只包含本任务 staged 文件，工作区剩余修改清晰可解释。
- Push 后远程出现同一提交，其他成员可以 Pull。
- History 能追溯业务变更，提交信息清楚。
- app 在另一台开发机 Pull 后仍能打开、Build 和验证。
常见问题
Pull 前有未提交修改
先 Commit，或明确选择 stash、保留或放弃。不要在不理解冲突后果时强行 Pull。
Push 被拒绝
先 Fetch，确认远程是否有新提交；需要时 Pull 并解决冲突，再重新验证和 Push。
认证失败
HTTPS 检查访问令牌权限，SSH 检查 key 和 agent。不要通过把 token 放进 URL 来绕过。
Discard 后想恢复
Discard 没有撤销保证；未跟踪文件会被删除。重要修改应先 Commit、备份或确认不再需要。
切到旧提交后无法正常 Push
很可能处于 detached HEAD。为该提交创建分支，再明确后续合并方式。
AI 可以怎么帮
AI 可以解释 diff、建议提交拆分、生成候选信息和分析冲突。例如：
只读检查当前 Git 状态和 diff。按业务目的建议最少的独立 Commit，指出不应提交的文件，并为 staged 变更生成候选信息。不要 Stage、Commit、Pull 或 Push。
必须人工确认
- 当前分支、远程和仓库归属正确。
- staged 内容不含凭据、客户数据或无关修改。
- Pull、Discard、stash、分支切换和历史切换不会丢失工作。
- Commit、Push 和团队合并已经获得授权并完成验证。