第11章 Zed 编辑器 Git 集成使用指南

Zed 内置 Git 支持，无需离开编辑器即可管理版本控制。Git 面板会显示工作区状态、暂存区内容和分支信息。在命令行所做的更改会立即反映在 Zed 中。

对于 Zed 未原生支持的操作，你可以使用集成终端。

激活仓库

当项目根目录位于 Git 仓库中，或位于某个仓库的子目录下时，其中的所有仓库会立即激活。

如果项目根目录不是仓库（例如主目录或包含多个项目的文件夹），则位于项目根目录下的仓库会立即激活；更深层的仓库则会在打开其中文件时激活，本地项目和远程项目均如此。

未激活的仓库同样会被完整索引并支持搜索；仅 Git 相关功能（状态、差异、分支）需等待激活后才可用。

此行为与 file_scan_depth 设置相关，但不取决于其具体数值：任何非零的 file_scan_depth 都会延迟激活未直接位于项目根目录下的仓库；对于层级达到或超过该限制值的仓库，在其目录按需索引之前甚至不会被发现。 在多文件夹项目中，深度和激活状态是分别从每个根目录开始测量的。

将 file_scan_depth 设置为 0 可关闭延迟激活：所有发现的仓库都将立即激活。

Git 面板

Git 面板展示工作区状态和 Git 暂存区。

你可以通过 {#action git_panel::ToggleFocus} 打开 Git 面板，或点击状态栏中的 Git 图标。

在面板中，你可以一目了然地查看项目状态：当前激活的仓库和分支、已修改的文件以及每个文件在暂存区的当前状态。

Zed 会持续监控你的仓库，使你在命令行所做的更改能够即时反映。

配置

打开设置编辑器（macOS 上按 Cmd+,，Linux/Windows 上按 Ctrl+,）以自定义 Git 行为。相关设置分布在两个页面中：

• 面板 > Git 面板：面板位置、树状与平铺视图、状态显示样式
• 版本控制：边距指示器、内联 blame、代码块样式

移动 Git 面板

Git 面板默认停靠在左侧。要将其移动到右侧或底部，请进入 Panels > Git Panel，修改 Git Panel Dock 设置。

切换到树形视图

Git 面板默认以扁平列表显示变更文件。如果想按文件夹层级组织，可以在面板右键菜单中切换 Tree View，或在 Panels > Git Panel 中开启。

行内 Blame

Zed 会在当前行显示 Git blame 信息。要关闭该功能，或设置延迟显示，请前往 Version Control > Inline Git Blame。

隐藏行号槽指示器

行号槽中标记新增、修改、删除行的彩色条可以隐藏。进入 Version Control > Git Gutter，将 Visibility 设为 "Hide" 即可。

提交信息行宽

Zed 默认在 72 个字符处换行提交信息（Git 惯例）。要修改此设置，在 Settings 中搜索 "Git Commit"，调整 Preferred Line Length。

项目 Diff

通过打开 Project Diff（{#kb git::Diff}），可以在 Zed 中查看 Git 捕获的所有变更。该视图可从命令面板或 Git 面板中通过 {#action git::Diff} 动作进入。

Project Diff 中展示的所有变更与普通 multibuffer 的行为完全一致：它们都是文件的可编辑片段。

你可以通过标签栏上的按钮或对应快捷键，对单个 hunk 或整个文件执行暂存/取消暂存。

Word Diff 高亮

默认情况下，Zed 会在被修改的行内高亮具体变更的单词，方便快速定位改动。要全局关闭此功能，打开 Settings Editor，进入 Languages & Tools > Miscellaneous，关闭 Word Diff Enabled。

如果只想针对特定语言关闭 word diff，可以在 settings.json 中添加：

{
  "languages": {
    "Markdown": {
      "word_diff_enabled": false
    }
  }
}

Diff 视图样式

Zed 提供两种 diff 显示模式：split（左右分栏对比）和 unified（行内显示变更），默认为 split 视图。

更改 diff 视图

打开设置编辑器（{#kb zed::OpenSettings}），搜索 “diff view style”。选择 Split 或 Unified。

若要更改默认设置，请在 settings.json 中添加以下内容：

{
  "diff_view_style": "unified"
}

有关设置编辑器的更多信息，请参阅Configuring Zed。

Split 与 Unified 的区别

• Split：并排显示原始版本和修改版本。适用于比较文件结构或审阅大型变更。
• Unified：在单个视图中内联显示更改，并标记增删内容。适用于聚焦特定行变更。

随时可以切换这两种模式。该偏好设置适用于Project Diff、File History 和 Stash Diff View。这些差异视图作为multibuffers 运行，允许同时编辑多个摘录。

File History

File History 显示单个文件的提交历史记录。每条条目显示提交者、时间戳和提交消息。选中某次提交后，将打开差异视图，仅显示该提交中针对该文件所做的更改。

查看 File History 的方法：

• 在 Project Panel 中右键点击文件，选择 “View File History”
• 在 Git Panel 中右键点击文件，选择 “View File History”
• 右键点击编辑器标签页，选择 “View File History”
• 使用 Command Palette 搜索 “file history”

Fetch, Push, and Pull

在 Zed 中，可以通过 Git Panel 上的按钮或通过 Command Palette 中的相应操作（{#action git::Fetch}、{#action git::Push} 和 {#action git::Pull}）从 Git 仓库执行 fetch、push 或 pull 操作。

Push 配置

Zed 遵循 Git 的 push 配置。执行 push 时，Zed 按以下顺序检查：

1. 当前分支配置的 pushRemote
2. Git 配置中的 remote.pushDefault
3. 分支的跟踪远程仓库

这与 Git 的标准行为一致，因此如果你已在 .gitconfig 中通过 git config 配置了 pushRemote 或 pushDefault，Zed 将会使用这些设置。

远程仓库

当你的仓库拥有多个远程仓库时，Zed 会在 Git 面板中显示一个远程仓库选择器。点击推拉操作旁边的远程按钮，即可选择该操作使用的远程仓库。

暂存工作流

Zed 主要有两种暂存工作流：使用 Project Diff 或直接在面板中操作。

使用 Project Diff

在 Project Diff 视图中，你可以聚焦于每个代码块（hunk），并通过点击标签栏按钮或使用 {#action git::StageAndNext} ({#kb git::StageAndNext}) 快捷键逐个暂存它们。

类似地，使用 {#action git::StageAll} ({#kb git::StageAll}) 快捷键可以同时暂存所有代码块，随后立即使用 {#action git::Commit} ({#kb git::Commit}) 提交。

使用 Git 面板

从面板中，你可以直接输入提交信息并点击提交按钮，或使用 {#action git::Commit}。这会自动暂存所有已跟踪文件（条目复选框中会显示 [·] 以表示），并提交它们。

可以使用每个独立条目的复选框来暂存特定条目。使用面板顶部的按钮或 {#action git::StageAll} 可以暂存所有更改。

条目被分组到不同的区域（默认分为已跟踪和未跟踪），每个区域都可以独立暂存，而不影响其他区域。点击区域标题上的复选框，或使用 {#action git::StageSection} / {#action git::UnstageSection}（这些操作作用于包含选中条目的区域）。这些操作也可以通过右键点击条目访问。默认未绑定快捷键；如果你经常使用它们，请在键位映射的 GitPanel 上下文中进行绑定。

要在编辑器中打开已更改的文件而不进入差异视图，请在 Git 面板中右键点击该文件并选择View File。要改用差异视图查看更改，请使用Open Diff ({#kb menu::Confirm}) 或Open Diff (File)。

提交

Zed 提供两个提交文本域：

1. 第一个位于 Git 面板的最底部。按下 {#kb git::Commit} 会立即提交所有已暂存的更改。
2. 第二种方式是通过 {#action git::ExpandCommitEditor} 操作，或者聚焦 Git Panel 的提交输入框时按下 {#kb git::ExpandCommitEditor}。

撤销提交

在 Zed 的 Git Panel 中提交后，提交输入框下方会出现一个状态栏，显示刚提交的内容。 在这里可以点击"Uncommit"按钮，它相当于执行 git reset HEADˆ--soft 命令。

配置提交行长

默认情况下，Zed 将提交行长设为 72，你可以在本地的 settings.json 文件中修改。

有关设置 preferred-line-length 的更多信息，请参阅Configuration一节。

分支管理

创建和切换分支

使用 {#action git::Branch} 创建新分支，或用 {#action git::Switch}、{#action git::CheckoutBranch} 切换到已有分支。

在Git worktree中工作时，切换到该 worktree 后用分支选择器即可创建或检出你想使用的分支。

删除分支

要删除分支，先用 {#action git::Switch} 打开分支切换器，找到要删除的分支，然后选择删除选项。为防止误删，Zed 会在删除前要求确认。

注意：当前检出的分支无法删除，请先切换到其他分支。

Git Worktrees

Git worktree 允许你在磁盘上同时保留同一仓库的多个检出。 当你需要同时处理多个分支或任务，又不想 stash、重新构建或打乱主检出目录中的文件时，这个功能非常有用。

在标题栏的项目选择器旁打开 worktree 选择器，或运行 {#action git::Worktree}。 在选择器中，你可以：

• 基于当前分支或默认分支创建新的关联 worktree
• 输入名称创建命名 worktree，或让 Zed 自动生成一个
• 将当前工作区切换到已有的 worktree
• 在新窗口中打开已有的 worktree
• 删除项目中当前未打开的关联 worktree

Worktree 管理

新建的 worktree 默认处于 detached HEAD 状态。切换到新 worktree 后，使用 worktree 选择器旁边的分支选择器来创建新分支，或检出某个现有且未使用的分支。这样可以避免 Zed 在多个 worktree 中意外检出同一个分支。

新建 worktree 所使用的目录由 git.worktree_directory 设置控制。默认情况下，Zed 会在相对于仓库工作目录的 ../worktrees 路径下创建 worktree。

示例见 All Settings。

初始化配置

要在 Zed 创建关联的 worktree 之后执行初始化步骤，可以使用 create_worktree 任务钩子。针对 agent 专属的工作流，请参阅 Worktree Isolation。

多根工作区

如果你的项目包含多个 Git 仓库（即多根文件夹），在通过选择器创建新 worktree 时，Zed 会为每个仓库创建一个关联的 worktree。项目中非 Git 的文件夹会原样包含在新的工作区中。

合并冲突

当你在合并、rebase 或 pull 之后遇到合并冲突时，Zed 会在文件中高亮显示冲突区域，并在每个冲突上方显示解决按钮。

查看冲突

存在冲突的文件会以警告图标显示在 Git 面板中。你还可以在 Project Diff 视图中看到冲突，每个冲突区域都会高亮显示：

• 来自当前分支的更改以绿色高亮
• 来自传入分支的更改以蓝色高亮

解决冲突

每个冲突区域都显示三个按钮：

• 使用 [分支名]：保留其中一个分支的更改（会显示实际的分支名称，如 "main"）
• 使用 [另一个分支]：保留另一个分支的更改（如 "feature-branch"）
• 使用双方：保留两组更改，且本分支的更改排在前面

点击按钮即可解决该冲突。冲突标记会被移除，并替换为你选择的内容。解决文件中的所有冲突后，暂存该文件并提交，即可完成合并。

提示：对于需要手动编辑的复杂冲突，你可以直接编辑文件。删除冲突标记（<<<<<<<、=======、>>>>>>>），保留你希望保留的内容即可。

Stashing

Git stash 允许你临时保存未提交的更改，并将工作目录还原到干净状态。当你需要快速切换分支或拉取更新，同时又不想提交未完成的工作时，这一功能尤为有用。

Creating Stashes

若要暂存所有当前更改，请使用 {#action git::StashAll} 操作。该操作会将已暂存和未暂存的更改（包括未跟踪的文件）保存到一个新的 stash 条目中，并清理工作目录。

若要仅暂存已跟踪的更改，保留未跟踪文件，请使用 {#action git::StashTracked} 操作。若要仅暂存已暂存的更改，保留未暂存的更改，请使用 {#action git::StashStaged} 操作；此功能需要 git 2.35 或更高版本。

Git 面板的溢出菜单会根据当前的 Group By 模式提供对应的选项：按 Tracked & Untracked 分组时显示 Stash Tracked，按 Staged & Unstaged 分组时显示 Stash Staged。Stash All 始终可用。

执行上述任一操作前，系统都会提示输入可选的 stash 名称。如果直接确认且名称为空，git 将自动生成其常规的 WIP on ... 描述。

Managing Stashes

Zed 提供 stash 选择器，可通过 {#action git::ViewStash} 或 Git 面板的溢出菜单访问。在 stash 选择器中，你可以：

• 查看 stash 列表：浏览所有已保存的 stash 及其描述和时间戳
• 打开 diff：查看每个 stash 中具体存储了哪些更改
• 应用 stash：将 stash 中的更改应用到工作目录，同时保留该 stash 条目
• 弹出 stash：应用 stash 中的更改，并从列表中移除该 stash 条目
• 丢弃 stash：直接删除不需要的 stash 条目，而不应用其更改

Quick Stash Operations

为了提升操作效率，Zed 提供了直接操作最近一次 stash 的快捷动作：

• 应用最新 stash：使用 {#action git::StashApply} 应用最近的 stash，但不删除它
• 弹出最新 stash：使用 {#action git::StashPop} 应用并删除最近的 stash

Stash Diff 视图

要查看某个 stash 的内容，在 stash 选择器中选中它，然后按 {#kb stash_picker::ShowStashItem}。在 diff 视图中，可以使用以下快捷键：

Git 中的 AI 支持

Zed 目前支持由 LLM 驱动的提交信息生成。 将焦点放在 Git Panel 的提交信息编辑器中，点击左下角的铅笔图标，或使用 {#action git::GenerateCommitMessage} 动作，也可以通过 {#kb git::GenerateCommitMessage} 快捷键，即可让 AI 生成提交信息。

注意：你需要配置 LLM provider，可以使用自己的 API key，或使用 Zed 托管的 AI 模型。 访问 AI Quick Start 了解如何配置 AI。

你可以在 agent 设置中添加 commit_message_model 字段来指定此任务偏好的模型。 详情参见 Feature-specific models。

{
  "agent": {
    "commit_message_model": {
      "provider": "anthropic",
      "model": "claude-4-5-haiku"
    }
  }
}

若要为模型添加自定义提交指令，可以使用全局 AGENTS.md 文件，位于 macOS 和 Linux 上的 ~/.config/zed/AGENTS.md，Windows 上的 %APPDATA%\Zed\AGENTS.md。

若要添加仅作用于提交信息生成的自定义指令，可以在 agent 设置中使用 commit_message_instructions 字段：

{
  "agent": {
    "commit_message_instructions": "Use the Conventional Commits format: <type>(<scope>): <description>."
  }
}

这些指令会连同其他指令文件（如 .rules 或 AGENTS.md）一起发送给模型。若需添加同时适用于提交信息代理的通用指令，请修改全局 AGENTS.md 文件。该文件在 macOS 和 Linux 上位于 ~/.config/zed/AGENTS.md，在 Windows 上位于 %APPDATA%\Zed\AGENTS.md。

Zed v1.4.0 之前，此功能通过已移除的 Rules Library 实现。详见 从 Rules 迁移。

Git 集成

Zed 与主流 Git 托管服务集成，使 Git 提交哈希及 Issue、Pull Request 和 Merge Request 的引用可点击。

目前，Zed 支持指向以下托管服务的链接： GitHub、 GitLab、 Bitbucket、 SourceHut、 Tangled 和 Codeberg。

自托管实例

Zed 通过检查 Git 远程 URL 中的关键词自动识别托管服务。例如，若您的自托管 URL 包含 gitlab、gitea 或其他可识别的服务名称，Zed 将自动注册该托管服务，无需额外配置。

如果自托管 Git 实例的 URL 不包含识别关键词，可手动配置 Zed 以生成指向您实例的可点击链接。添加 git_hosting_providers 设置即可让提交哈希和永久链接解析到指定域名：

{
  "git_hosting_providers": [
    {
      "provider": "gitlab",
      "name": "Corp GitLab",
      "base_url": "https://git.example.corp"
    }
  ]
}

provider 字段指定你使用的托管服务类型。支持的 provider 值包括 github、gitlab、bitbucket、gitea、forgejo、sourcehut 和 tangled。name 是可选的，用作实例的显示名称；base_url 则是你自托管服务器的根 URL。

如果你同时使用多个自托管实例，可以配置多个自定义 provider。

永久链接

Zed 可以打开或复制指向 Git 托管服务中特定文件或代码选区的永久链接。这些链接非常适合在特定 commit 中分享文件的某一行或某一段行。

对于编辑器中的当前选区，你可以使用 {#action editor::CopyPermalinkToLine} 或 {#action editor::OpenPermalinkToLine}，从 Command Palette （搜索 permalink）、通过 自定义快捷键， 或右键点击并选择 Copy Permalink to Line 来操作。

从文件标签或 Project Panel 中，你还可以针对整个文件（无具体行选区）Open File Permalink 或 Copy File Permalink。

Diff Hunk 快捷键

查看包含更改的文件时，Zed 会显示 diff hunk，你可以展开或折叠它们以进行详细审查：

• 展开所有 diff hunk：{#action editor::ExpandAllDiffHunks}（{#kb editor::ExpandAllDiffHunks}）
• 折叠所有 diff hunk：按 Escape（绑定到 {#action editor::Cancel}）
• 切换选中的 diff hunk：{#action editor::ToggleSelectedDiffHunks}（{#kb editor::ToggleSelectedDiffHunks}）
• 在 hunk 之间导航：{#action editor::GoToHunk} 和 {#action editor::GoToPreviousHunk}

提示：按 Escape 是折叠所有已展开 diff hunk 并返回更改概览的最快方式。

Action 参考

并非所有操作都有默认快捷键，但可通过自定义键位映射进行绑定。

Git CLI 配置

如果你希望在从命令行提交时，也将 Zed 用作git 提交信息编辑器，可以使用 zed --wait：

git config --global core.editor "zed --wait"

或者将以下内容添加到你的 shell 环境变量中（例如 ~/.zshrc、~/.bashrc 等）：

export GIT_EDITOR="zed --wait"