7418andClaude Opus 4.6
0eabed8c27
**Layout refactor (Phase 1):** - UnifiedTopBar replacing Header.tsx — chat title editing, project folder, commit/push split button, Git branch+dirty badge, terminal/file-tree toggles - PanelZone renders FileTree, GitPanel, PreviewPanel side-by-side on the right - Independent panel toggle states in PanelContext - ResizeHandle unified across all panels - Removed old RightPanel, Header, DocPreview components **Git backend (Phase 2):** - src/lib/git/service.ts — execFile-based Git operations with timeout + injection safety - API routes: status, branches, checkout, log, commit, push, commit-detail, worktrees, derive - Worktree derive creates DB session inheriting source session settings **Git frontend (Phase 3):** - GitPanel with 4 collapsible sections: Status, Branches, History, Worktrees - CommitDialog with commit vs commit-and-push modes - GitBranchSelector with inline error, worktree-occupied branches disabled - GitWorktreeSection with switch-to/derive actions, current/dirty indicators - useGitStatus polled in AppShell, derived into context (no redundant setState) **Terminal (Phase 4):** - electron/terminal-manager.ts — child_process.spawn fallback (PTY upgrade documented) - IPC handlers + TerminalDrawer/TerminalInstance components **Polish (Phase 5):** - Push inline feedback with 4s auto-dismiss - Branch detection fix, commit diff exit-code handling - Removed redundant git state: currentBranch/gitDirtyCount now derived, not setState - useTerminal isElectron uses lazy initializer instead of effect - i18n keys (en + zh), user tutorial docs, handover document Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
198 lines
7.4 KiB
Plaintext
198 lines
7.4 KiB
Plaintext
---
|
||
title: Git 与工作区
|
||
description: 在 CodePilot 中管理代码版本、查看文件、使用终端 — 不用离开聊天窗口。
|
||
---
|
||
|
||
# Git 与工作区
|
||
|
||
CodePilot 不只是一个聊天窗口。你可以在右侧打开文件树、查看 Git 状态、提交代码，甚至打开终端——所有操作都不需要切换到别的应用。
|
||
|
||
这篇文档会带你了解这些功能怎么用。如果你还不熟悉 Git，别担心，我们会从基本概念讲起。
|
||
|
||
---
|
||
|
||
## 先了解几个概念
|
||
|
||
如果你已经熟悉 Git，可以跳过这一节。
|
||
|
||
### 什么是 Git？
|
||
|
||
Git 是一个**版本控制工具**。简单来说，它帮你记录代码的每一次修改，就像文档的"历史记录"功能一样。你可以随时回到之前的版本，也可以和同事协作而不会互相覆盖。
|
||
|
||
几乎所有的软件项目都用 Git 来管理代码。
|
||
|
||
### 常见术语
|
||
|
||
| 术语 | 含义 |
|
||
|------|------|
|
||
| **仓库（Repository）** | 一个被 Git 管理的项目文件夹。你的项目根目录下会有一个隐藏的 `.git` 文件夹，就说明这是一个 Git 仓库。 |
|
||
| **分支（Branch）** | 代码的一条独立时间线。你可以在新分支上开发功能，完成后再合并回主分支。主分支通常叫 `main` 或 `master`。 |
|
||
| **提交（Commit）** | 一次代码快照。每次你觉得改动可以"存档"了，就做一次提交。每次提交都需要写一条简短的说明。 |
|
||
| **暂存（Stage）** | 选择哪些文件要包含在下一次提交中。CodePilot 目前会自动暂存所有改动。 |
|
||
| **推送（Push）** | 把本地的提交上传到远程服务器（比如 GitHub）。团队成员就能看到你的改动了。 |
|
||
| **拉取（Pull）** | 把远程服务器上别人的提交下载到本地。 |
|
||
| **工作树（Worktree）** | 同一个仓库的多个独立工作目录。可以同时在不同分支上工作，不需要反复切换。 |
|
||
|
||
---
|
||
|
||
## 顶栏
|
||
|
||
打开一个对话后，你会看到顶部有一行操作栏。从左到右依次是：
|
||
|
||
- **对话标题** — 点旁边的铅笔图标可以重命名
|
||
- **项目文件夹名** — 点击可以在系统文件管理器中打开
|
||
- 右侧按钮区：**提交** | **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 + `` `），底部会弹出一个终端面板。
|
||
|
||
终端会在当前对话的项目目录中打开，你可以直接运行命令，比如：
|
||
|
||
```bash
|
||
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 等全屏程序，请使用系统终端。日常的命令执行（安装依赖、启动服务、运行测试等）可以正常使用。
|