Git 与工作区

CodePilot 不只是一个聊天窗口。你可以在右侧打开文件树、查看 Git 状态、提交代码，甚至打开终端——所有操作都不需要切换到别的应用。

这篇文档会带你了解这些功能怎么用。如果你还不熟悉 Git，别担心，我们会从基本概念讲起。

先了解几个概念

如果你已经熟悉 Git，可以跳过这一节。

什么是 Git？

Git 是一个版本控制工具。简单来说，它帮你记录代码的每一次修改，就像文档的"历史记录"功能一样。你可以随时回到之前的版本，也可以和同事协作而不会互相覆盖。

几乎所有的软件项目都用 Git 来管理代码。

常见术语

顶栏

打开一个对话后，你会看到顶部有一行操作栏。从左到右依次是：

• 对话标题 — 点旁边的铅笔图标可以重命名
• 项目文件夹名 — 点击可以在系统文件管理器中打开
• 右侧按钮区：提交 | Git | 终端 | 文件树

这些按钮控制右侧面板和底部终端的开关。你可以同时打开多个面板。

提交按钮

点击「提交全部」会弹出提交对话框，让你输入提交说明。有两个选项：

• 提交 — 只保存到本地
• 提交并推送 — 保存到本地，同时上传到远程服务器

按钮右侧的小箭头 ▾ 可以展开菜单，单独触发推送。

Git 按钮

按钮上直接显示了当前分支名和改动文件数（比如 main · 3），方便你随时了解状态。点击后在右侧打开 Git 面板。

文件树

点击顶栏最右边的文件树按钮，右侧会展开项目的文件目录。

你可以：

• 浏览文件 — 展开文件夹，查看项目结构
• 预览文件 — 点击一个文件，会在旁边打开预览面板，显示文件内容和语法高亮
• 添加到聊天 — 右键点击文件旁的加号，可以把文件作为上下文附加到当前对话

文件树面板的宽度可以拖动左边缘来调整。

文件预览

在文件树中点击一个文件，预览面板会自动打开。

• 源码视图 — 带语法高亮和行号的代码展示
• 渲染视图 — 对于 Markdown 和 HTML 文件，可以切换到渲染后的效果

顶部有两个切换按钮：Source（源码）和 Preview（预览）。

预览面板也支持拖动左边缘调整宽度。点击顶部的复制按钮可以复制文件全部内容。

Git 面板

Git 面板分为四个折叠区块。点击标题可以展开或收起。

状态

显示当前仓库的核心信息：

• 当前分支 和它跟踪的远程分支
• 领先/落后 — 你本地有多少提交还没推送，远程有多少提交你还没拉取
• 变更文件 — 列出所有修改过的文件。每个文件前有一个字母标记：
  • M 修改（Modified）
  • A 新增（Added）
  • D 删除（Deleted）
  • R 重命名（Renamed）
  • ? 未跟踪的新文件（Untracked）

已跟踪的变更（M/A/D/R）排在前面，未跟踪的文件单独一组显示在下方。如果没有任何变更，会显示"所有更改都已提交"。

分支

展开后可以看到项目的所有本地分支。点击一个分支名就能切换过去。

注意：如果当前有未提交的改动，分支切换会被禁用，你需要先提交或暂存改动。被其他工作树占用的分支也会标注并禁用。

如果切换失败，错误信息会直接显示在分支列表上方，方便你了解原因。

历史

显示最近的提交记录。每条记录包括：

• 提交哈希值（前 7 位）
• 提交说明
• 作者和时间

点击一条记录可以查看该提交的详细改动（diff）。

提交或切换分支后，历史列表会自动刷新。

工作树

如果你需要同时在多个分支上工作，可以使用 Git 的工作树功能。

工作树列表会显示：

• 每个工作树对应的分支名
• 路径
• 是否是当前工作树（会高亮并标记"当前"）
• 是否有未提交的改动（橙色圆点）

你可以：

• 切换到工作树 — 点击右侧箭头按钮，会打开（或创建）一个绑定到该工作树目录的新对话
• 派生新工作树 — 点击底部的「派生工作树」按钮，输入新分支名，确认后会自动创建工作树目录和对应的对话

终端

点击顶栏的终端按钮，或者按下快捷键 Ctrl + `` （macOS 上是 Cmd + `` ），底部会弹出一个终端面板。

终端会在当前对话的项目目录中打开，你可以直接运行命令，比如：

npm install
npm run dev
git status

终端面板的高度可以拖动顶部边缘来调整。再次按下快捷键或点击终端按钮即可关闭。

当前版本的终端适合运行简单命令和查看输出。对于需要完整终端功能的场景（比如 vim 或 htop），建议使用系统自带的终端应用。

面板布局

所有面板都在聊天区域的右侧打开，终端在底部。你可以：

• 同时打开多个面板 — 比如同时显示 Git 面板和文件树
• 调整宽度 — 每个面板的左边缘都可以拖动
• 调整终端高度 — 拖动终端的顶部边缘
• 独立开关 — 每个面板的关闭按钮互不影响

面板不会挤压聊天区域到不可用的程度——每个面板都有最小和最大宽度限制。

常见问题

Git 面板显示"不是 Git 仓库"

你的项目目录还没有被 Git 管理。在终端中运行 git init 初始化一个新仓库，或者直接克隆一个已有的仓库。

无法切换分支

最常见的原因是有未提交的改动。先把当前改动提交，或者让 Claude 帮你 stash（暂存到临时区域），然后再切换。

推送失败

可能的原因：

• 还没有设置远程仓库 — 在终端中运行 git remote add origin <你的仓库地址>
• 没有推送权限 — 检查你的 SSH key 或 token 配置
• 远程有你本地没有的提交 — 先拉取最新代码再推送

终端里的程序显示不正常

当前版本的终端使用简化的实现，不支持完整的终端模拟。如果你需要运行 vim、htop 等全屏程序，请使用系统终端。日常的命令执行（安装依赖、启动服务、运行测试等）可以正常使用。