Git 与工作树
本手册介绍如何选择本地或工作树模式、检查文件改动、提交和推送，以及将工作树中的未提交改动带回原项目。直接修改原项目时选本地；需要独立尝试方案或并行开展任务时选新工作树。
先选择任务方式
Git 用于保存文件版本，分支用于区分修改路线，工作树是同一仓库的另一份工作目录。
| 对比项 | 本地新会话 | 新工作树会话 |
|---|---|---|
| 适用场景 | 接着原项目中的文件继续修改 | 尝试新方案，或独立处理另一项任务 |
| 创建结果 | 新会话，继续使用原项目目录 | 新会话和独立工作目录 |
| 修改位置 | 原项目文件 | 工作树目录中的文件 |
| 与其他会话的关系 | 使用相同目录的会话共用文件 | 使用不同工作树的任务分别修改各自目录 |
| 成果处理 | 在原项目提交、推送 | 在工作树提交、推送，或将未提交改动带回本地 |
提交是保存到本机仓库，推送是上传远程仓库，合并是将一个分支的提交并入另一分支。三者是不同操作。
开始前的准备
- 打开 DeepWorks，选择一个本地工作区。
- 确认该目录是 Git 仓库，且至少有一次提交。普通文件夹可先在
Git 评审中初始化并完成首次提交。 - 如果提示
Git 不可用，按界面提示安装并重新检测；安装完成后必要时重启 DeepWorks。 - 需要推送时，先确认仓库已配置远端，且本机具有访问权限。
常用入口：左侧新会话开始任务，右侧工具栏的Git 评审检查改动，账号菜单中的设置 → Git调整 Git 规则。
本地会话
创建并执行任务
- 点击
新会话，在输入区选择工作区。 - 选择
本地和需要使用的本地分支。 - 输入任务并发送，例如
修改首页按钮文案。修改直接写入原项目目录。 - 打开
Git 评审，确认环境信息显示本地，分支名称正确，再检查文件改动。
切换本地分支会切换原项目目录的分支。当前目录有未提交改动时，界面会要求先提交更改再切换；不要将切换分支当作另建独立工作目录。已被其他工作树使用的分支不能直接在本地检出。
提交与推送
- 检查改动内容后，点击
环境信息 → 提交或推送。 - 填写提交信息。留空时会尝试自动生成，提交前仍应核对内容。
- 如需一并提交未暂存的修改，勾选
包含未暂存的更改。 - 点击
提交保存本地版本；需要上传时点击提交并推送。没有待提交改动时，可直接推送已有提交。
未配置远端时无法推送。推送成功后，可到远程仓库核对对应分支和提交。
新工作树会话
创建独立目录
- 点击
新会话，选择本地工作区。 - 选择
新工作树和起点分支，例如main。 - 输入任务并发送。发送第一条消息时，系统才开始创建工作树和会话。
- 创建耗时较长时会显示进度，包括检查项目状态、创建工作树、创建会话和完成。
- 创建成功后，打开
Git 评审，确认环境信息显示工作树。后续对话在该工作树中继续执行。
工作树从所选分支的已提交版本创建，不会带入原目录中尚未提交的修改；工作树中的修改也不会自动同步回原项目。
在已有会话中新建工作树
在本地会话中打开Git 评审，点击本地 → 新建工作树。系统创建独立工作树后，将其绑定到当前会话。可以通过进度提示确认创建与绑定是否完成。
使用此入口前，需要已有会话和有效分支。如果尚未创建或选择会话，或当前处于没有分支名的 HEAD 状态，入口可能不可用。新工作树仍基于已提交版本创建，不会自动搬走原目录的未提交改动。
创建失败时
新会话创建工作树失败时，界面会显示失败阶段，并在能够识别原因时补充提示。
| 提示或现象 | 处理方式 |
|---|---|
| 未检测到可用的 Git | 安装 Git 2.17 或更高版本，重新检测后重试 |
| 所选分支在本地不存在 | 重新选择本地已有分支 |
| 工作树目录已被占用 | 关闭失败浮层后重试；持续失败时联系支持人员 |
| 创建或绑定失败 | 先确认会话实际处于哪个目录，保留提示信息，再重试 |
看到失败提示时，不要仅凭目录已经出现就认为会话已成功切换。以会话中的环境信息和成功提示为准。
检查文件改动
在Git 评审的审查区域选择需要检查的范围。
| 审查范围 | 查看内容 |
|---|---|
| 未暂存 | 尚未加入暂存区的改动 |
| 已暂存 | 已加入暂存区、等待提交的改动 |
| 提交 | 当前提交的改动 |
| 分支 | 当前工作分支相对目标分支的差异 |
某个范围显示0 个文件，不代表其他范围没有改动。本地会话共用同一目录时，也可能看到该目录其他会话产生的修改。
文件列表默认可能收起。点击工具栏显示文件列表展开，再选择文件查看差异；也可以使用跳转到文件、刷新变更和自动换行。
选择在哪里继续处理成果
创建分支并留在工作树
工作树尚无分支时，可能显示 HEAD 或创建分支。点击环境信息 → 创建分支，输入新分支名称并确认。
成功后，当前工作树切换到新分支，原项目目录的分支不变，未提交改动保留在工作树中。创建分支不会自动提交文件；继续任务后按需提交和推送。
将未提交改动带回本地
- 先处理原项目目录中已有的未提交改动，避免覆盖正在进行的工作。
- 在工作树会话中点击
工作树 → 本地。 - 输入原工作区中已存在、且没有被其他工作树占用的本地分支名。
- 等待状态检查完成，核对目标位置和将携带的改动数量。
- 点击
检出。成功后确认环境显示本地和目标分支，再检查原目录中的文件。
此操作携带的是当前工作树的未提交改动，不会把工作树已有提交自动合并到目标分支。已经提交的成果需要通过分支合并等 Git 流程处理。完成检出也不等于已经提交或推送。
常见问题
为什么新工作树里看不到原目录刚改的内容
新工作树基于起点分支的已提交版本。需要这些修改时，先在原分支正确提交，再基于包含该提交的分支创建工作树。
为什么本地会话里看到其他任务的改动
多个本地会话可能共用同一项目目录。需要分开处理时，为不同任务建立独立工作树。
为什么不能检出本地
检查原目录是否还有未提交改动、输入的本地分支是否存在、分支是否被其他工作树占用，以及 Git 状态是否读取成功。按界面提示处理后重试。
怎样确认操作完成
检查环境类型、分支名和文件内容三项是否符合预期；提交后核对本地提交，推送后再核对远程分支。