openidea/docs/zh/guide/vcs.mdx

---
title: "版本控制"
description: "使用内置的 Git 集成进行提交、分支、合并、变基、贮藏和查看历史。"
---

OpenIDEA 内置 Git 支持，Git 也是它唯一支持的版本控制系统。

仓库状态（状态、差异、Blame、日志）在进程内读取；所有修改仓库的操作都调用 `git` 可执行文件完成，因此钩子、凭据、签名和你的 Git 配置都和命令行下的行为一致。你需要先安装 Git。OpenIDEA 依次在 `OPENIDEA_GIT`、`PATH` 和常见安装位置中查找；也可以在 **设置 › 版本控制 › Git › Git 可执行文件路径** 中指定路径，并点击 **测试** 检查。

## 功能入口

| 位置                                                | 内容                                                                                                                     |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Git** 主菜单                                      | 提交、推送、拉取、获取、合并、变基、分支、标签、重置、工作树、日志、补丁、贮藏与搁置、当前文件操作、GitHub、远程、克隆。 |
| **提交** 工具窗口（左侧）                           | 本地更改、更改列表、提交消息，以及搁置和贮藏标签页。                                                                     |
| **Git** 工具窗口（底部）                            | **日志**、历史标签页、**控制台**（IDE 执行过的 Git 命令）、**工作树**。                                                  |
| 分支微件（标题栏）                                  | 当前分支，点击打开分支弹窗。                                                                                             |
| **VCS 操作…** 弹窗                                  | 常用 Git 操作的集合。                                                                                                    |
| 项目视图、编辑器和标签页右键菜单中的 **Git** 子菜单 | 针对所选文件的操作。                                                                                                     |

| 操作                       | macOS           | Windows/Linux                |
| -------------------------- | --------------- | ---------------------------- |
| 提交工具窗口               | `⌘0`            | `Alt+0`                      |
| Git 工具窗口               | `⌘9`            | `Alt+9`                      |
| VCS 操作…                  | `⌃V`            | ``Alt+` ``                   |
| 分支…                      | 无              | ``Ctrl+Shift+` ``            |
| 提交…                      | `⌘K`            | `Ctrl+K`                     |
| 提交并推送…                | `⌥⌘K`           | `Ctrl+Alt+K`                 |
| 推送…                      | `⇧⌘K`           | `Ctrl+Shift+K`               |
| 更新项目…                  | `⌘T`            | `Ctrl+T`                     |
| 回滚…                      | `⌥⌘Z`           | `Ctrl+Alt+Z`                 |
| 显示差异                   | `⌘D`            | `Ctrl+D`                     |
| 添加到 VCS                 | `⌥⌘A`           | `Ctrl+Alt+A`                 |
| 新建分支…                  | `⌥⌘N`           | `Ctrl+Alt+N`                 |
| 下一个 / 上一个更改        | `⌃⌥⇧↓` / `⌃⌥⇧↑` | `Ctrl+Alt+Shift+Down` / `Up` |
| 最近的更改（本地历史记录） | `⌥⇧C`           | `Alt+Shift+C`                |

**使用 Git Blame 注解**、**显示 Git 日志**、**显示历史记录**、**拉取…**、**获取**、**合并…**、**变基…**、**贮藏更改…** 和 **解决冲突…** 没有默认快捷键，常用的话可以在[键位映射](/zh/guide/keymap)中自行分配。

## 获取仓库

- **Git › 克隆…** 打开 **克隆仓库**。填写 **URL：** 和 **目录：**，需要时勾选 **浅克隆，历史记录截断为** N 个提交。侧栏中的 **GitHub** 会列出你的 GitHub 仓库（见 [GitHub](/zh/guide/github)）。
- 新建项目时，在新建项目对话框中勾选 **创建 Git 仓库**。
- **Git › 创建 Git 仓库…** 会在你选择的目录（默认是项目根目录）里执行 `git init`，并立即注册这个新仓库；在终端里创建的仓库同样会被识别。

OpenIDEA 会找到包含项目的仓库，以及向下最多四层的嵌套仓库（跳过 `node_modules`、`target`、`build` 等目录）。状态、提交、获取和更新覆盖所有仓库；分支和日志操作针对所选仓库。子模块显示为嵌套仓库，但没有子模块相关命令。

## 提交更改

**提交** 工具窗口按组列出更改：**合并冲突**、**更改**（每个更改列表一组）和 **未跟踪的文件**。选择 **视图选项 › 分组依据 › 暂存状态** 后，更改会分为 **已暂存的更改** 和 **未暂存的更改**。

<Steps>
  <Step title="选择要提交的内容">
    勾选要包含的文件。未跟踪的文件和冲突默认不勾选，并且只勾选活动更改列表中的更改。`Space`
    切换所选项。部分暂存的文件只包含已暂存的代码块。
  </Step>
  <Step title="填写提交消息">
    在消息框中输入。**提交消息历史记录** 按钮（或 `⌃M` / `Ctrl+M`）提供最近 20 条消息。合并、拣选或还原过程中，消息会从
    Git 预先填入；其他情况下使用 `commit.template`。
  </Step>
  <Step title="提交">
    点击 **提交**，或在消息框中按 `⌘Enter` / `Ctrl+Enter`。**提交并推送…**（在消息框中按 `⌥⌘Enter` /
    `Ctrl+Alt+Enter`）会在提交后推送。
  </Step>
</Steps>

勾选 **修改**（`⌃⌥M` / `Alt+M`）可以修正上一次提交，按钮会变为 **修正提交**。

双击文件（或按 `Enter`）查看差异；**预览差异** 会在树旁边直接显示。文件右键菜单包括 **显示差异**、**跳转到源代码**、**回滚…**、**添加到 VCS**、**添加到 .gitignore**、**暂存**、**取消暂存**、**移动到其他更改列表…**、**搁置更改…**、**创建补丁…**、**以补丁形式复制到剪贴板**、**显示历史记录**、**显示本地历史记录** 和 **使用 Git Blame 注解**。

### 部分提交

只想提交文件的一部分时，从提交工具窗口打开它的差异。每个变更块在边栏中都有 **包含在提交中** 复选框，取消勾选不想提交的块即可，树中该文件的复选框会变为部分选中。OpenIDEA 通过临时索引提交选中的块，工作区和暂存区都保持不变。选择粒度是代码块，不是单行。

习惯使用暂存区的话，差异工具栏里也有 **暂存更改 (git add hunk)**。

### 更改列表

更改列表用来给本地更改分组，不影响 Git。默认列表名为 **更改**，新的更改进入活动列表。更改列表按项目保存在 `.openidea/changelists.json` 中。

- **新建更改列表…**、**编辑更改列表…**（`F2` 或 `⇧F6` / `Shift+F6`）、**删除更改列表**、**设置活动更改列表**。
- **移动到其他更改列表…**（`⇧⌘M` / `Alt+Shift+M`），或者直接在列表之间拖动文件。
- 右键某个更改列表选择 **提交…**，只提交这个列表。

### 提交选项与检查

**提交** 按钮旁的齿轮按钮（**提交选项**）包含：

- **作者:**：以其他身份提交（`Name <email>`），以及 **签署提交**。
- **提交检查**：**重新格式化代码**、**优化导入**、**清理**（应用 fix-all 代码操作）和 **运行 Git 钩子**（关闭时加 `--no-verify`）。
- **高级提交检查**：**分析代码**（语言服务器报告的错误和警告）和 **检查 TODO**（新增行中的 TODO 和 FIXME）。

提交前，OpenIDEA 还会对以下情况发出警告：在分离 HEAD 或变基过程中提交、文件名在其他系统上可能有问题、文件大于 50 MB、CRLF 换行符。出现警告时第一次提交会被拦下，点击 **仍然提交** 继续。没有“运行测试”这一检查。

### 模态提交

在 **设置 › 版本控制 › 提交** 中关闭 **使用非模态提交界面** 后，就没有提交工具窗口了：**本地更改**、**搁置** 和 **贮藏** 变成 Git 工具窗口的标签页，**提交…** 会打开 **提交更改** 对话框。

## 编辑器中的更改标记

编辑器边栏会标出相对于 HEAD 新增、修改和删除的行。点击标记会弹出窗口，提供 **上一个更改**、**下一个更改**、**回滚**、**显示差异** 和 **复制原始文本**。光标位于已更改的行上时执行 **回滚…**，只回滚这些行。

## 回滚、添加与忽略

- **回滚…** 打开 **回滚更改**：选择文件，可选 **删除已添加文件的本地副本**。
- **添加到 VCS** 添加未跟踪的文件。新建或删除文件时，OpenIDEA 会询问是否在 Git 中添加或删除；可在 **设置 › 版本控制 › 确认** 中修改。
- **添加到 .gitignore** 把规则写入最近的 `.gitignore` 或 `.git/info/exclude`。

## 差异查看器

差异在编辑器标签页中打开。

| 操作                | macOS         | Windows/Linux              |
| ------------------- | ------------- | -------------------------- |
| 下一个 / 上一个差异 | `F7` / `⇧F7`  | `F7` / `Shift+F7`          |
| 下一个 / 上一个文件 | `⌃⇧→` / `⌃⇧←` | `Alt+Shift+Right` / `Left` |
| 接受左侧            | `⌃⌘→`         | `Ctrl+Alt+R`               |
| 接受右侧            | `⌃⌘←`         | `Ctrl+Alt+A`               |
| 跳转到源代码        | `F4` 或 `⌘↓`  | `F4`                       |
| 差异设置            | `⇧⌘D`         | `Ctrl+Shift+D`             |

工具栏可以在 **并排查看器** 和 **统一查看器** 之间切换，并设置空白处理（**不忽略**、**修剪空白**、**忽略空白**、**忽略空白和空行**）、高亮方式（按词、按行或不高亮）、**折叠未更改的片段**、**同步滚动** 和 **对齐更改**。右侧是工作区文件时可以直接编辑，也可以 **还原更改** 或 **暂存更改 (git add hunk)**。边栏中的箭头可以把一侧的更改应用到另一侧。

其他比较方式：

- 对当前文件或文件夹使用 **与分支或修订比较…** 和 **与修订版比较…**（文件夹会显示变更文件列表）。
- **比较对象…**（在项目视图中按 `⌘D` / `Ctrl+D`）、**比较文件**、**比较目录**（可向左/向右复制）和 **视图 › 与剪贴板比较**。

## 分支

点击标题栏的分支微件（或 **Git › 分支…**）打开分支弹窗，输入文字即可搜索分支和操作。弹窗中有 **最近**、**本地**、**远程** 和 **标签** 分组，顶部有 **更新项目…**、**提交…**、**推送…**、**新建分支…** 和 **签出标签或修订…**。齿轮按钮可以切换按前缀分组、显示最近分支和显示标签。

选中分支（`→` 或 `Enter`）查看它的操作：

- **签出**、**从 '…' 新建分支…**、**签出并变基到 '…'**
- **与 '…' 比较**、**显示与工作树的差异**、**显示历史记录**
- **将 '…' 变基到 '…'**、**将 '…' 合并到 '…'**；远程分支还有 **使用变基拉取到 '…'** / **使用合并拉取到 '…'**
- **更新**、**推送…**、**重命名…**、**添加到收藏夹**、**删除**

如果本地更改阻止签出，可以选择 **智能签出**（贮藏、签出、再恢复）、**强制签出** 或 **不签出**。删除的分支可以通过通知中的 **恢复** 找回。

有多个仓库时，弹窗会显示所有仓库共有的分支，以及每个仓库各自的子菜单。

## 与远程同步

- **获取** 会获取所有仓库。OpenIDEA 还会在后台检查传入的提交（打开项目 20 秒后检查一次，之后每 15 分钟一次），见 Git 设置中的 **显式检查远程上的传入提交**。
- **更新项目…**（`⌘T` / `Ctrl+T`）以合并或变基方式拉取所有仓库，未提交的更改会先贮藏再恢复。只有开启 **更新前显示选项** 时才会显示 **更新项目** 对话框。
- **拉取…** 把选定的远程分支拉取到当前分支，可选 `--rebase`、`--ff-only`、`--no-ff`、`--squash` 等选项。
- **推送…**（`⇧⌘K` / `Ctrl+Shift+K`）列出待推送的提交及其文件。可以修改目标分支、选择远程，并选择 **强制 (with lease)**、**设置上游** 或推送标签。受保护分支（默认 `master; main`）禁止强制推送。推送被拒绝时，OpenIDEA 会提供合并或变基后重新推送。
- **管理远程…** 添加、编辑和删除远程。

HTTPS 密码和 SSH 口令通过对话框询问，可以选择记住；保存的 HTTPS 凭据列在 **设置 › 版本控制 › Git › 密码** 中。

## 合并、变基与冲突

**Git › 合并…** 和 **Git › 变基…** 打开对话框，提供常用的 Git 选项（`--no-ff`、`--ff-only`、`--squash`、`--no-commit`；`--onto`、`--rebase-merges`、`--keep-empty`）。合并、变基、拣选或还原进行中时，标题栏会显示一个微件，提供 **解决冲突…** 以及继续 / 中止；Git 菜单中的 **中止合并**、**继续变基**、**跳过提交**、**中止变基** 以及拣选、还原对应的操作也会变为可用。合并通过提交来完成。

出现冲突时，通知和 **冲突** 对话框会列出相关文件。对每个文件选择 **接受您的**、**接受他们的** 或 **合并…**。

**合并…** 打开三方合并编辑器：左侧是你的版本，中间是结果，右侧是他们的版本。

- 点击边栏中的箭头接受某处更改，点叉号忽略它。按住修饰键可以用某一侧解决整个冲突。
- 工具栏可以应用所有不冲突的更改（左侧、右侧或两侧）、**解决简单冲突**、任意比较其中两个版本，并显示剩余的更改和冲突数。
- 点击 **应用** 保存结果并标记为已解决，或者对整个文件选择 **接受您的** / **接受他们的**。

带冲突标记的文件顶部会显示横幅和 **解决冲突…**，冲突标记也会作为错误报告。在文本编辑器中，**接受您的（光标处的冲突）**、**接受他们的（光标处的冲突）**、**全部接受（光标处的冲突）** 可以逐个解决冲突。

## Git 日志

Git 工具窗口的 **日志** 标签页显示提交图。

- **过滤**：文本或哈希（支持正则和区分大小写）、分支、用户、日期和路径；**最近使用的过滤条件** 可以找回之前的过滤。
- **转到哈希/分支/标签**（在日志中按 `⌘F` / `Ctrl+F`）。
- **图形选项**：按日期、拓扑或传入优先排序；仅第一父提交；不显示合并提交。
- **视图选项**：引用显示方式、详情面板，以及列（**作者**、**日期**、**哈希**、**签名**、**GitHub 提交检查**）。
- 左侧的分支面板可以按分支过滤日志，并提供分支操作。
- 详情面板显示变更文件、提交消息、提交者、包含该提交的分支以及签名。

右键提交可以选择 **复制修订号**（`⌥⇧⌘C` / `Ctrl+Alt+Shift+C`）、**创建补丁…**、**拣选**、**签出修订**、**浏览此修订版本的仓库**、**与本地比较**、**将当前分支重置到此处…**、**还原提交**、**撤消提交…**、**新建分支…**、**新建标签…**、**在浏览器中查看** 等。选中两个提交时，**比较版本** 会比较它们。

### 改写历史

在日志中可以 **编辑提交消息…**、**修补提交…**、**压缩到…**、**丢弃提交**、**压缩提交…** 和 **从此处进行交互式变基…**。交互式变基对话框可以对提交执行 pick、reword、edit、squash、fixup、drop，并调整顺序。这些操作也可以用于已推送的提交：改写前会先确认，之后推送需要强制推送。受保护分支上已推送的提交不能被改写。

限制：交互式变基不支持包含合并提交的范围；**撤消提交…** 只能用于最新的提交（其更改会放回某个更改列表）。

### 标签、重置与工作树

- **Git › 新建标签…** 在某个提交上创建标签（填写消息时为附注标签）。日志中的 **新建标签…** 创建轻量标签。
- **Git › 重置 HEAD…** 和 **将当前分支重置到此处…** 支持 **软**、**混合**（默认）、**硬** 和 **保留** 四种模式。
- **Git › 新建工作树…** 和 **工作树…** 用于创建、列出、删除工作树，以及在新窗口中打开。

## 贮藏、搁置与补丁

**贮藏** 使用 `git stash`：

- **贮藏更改…**：填写消息，可选 **保留索引** 和 **包括未跟踪的文件**。贮藏总是包含全部更改，不能只贮藏部分文件。
- **取消贮藏更改…**：应用或弹出某个贮藏，恢复索引，或基于它新建分支。
- 提交工具窗口的 **贮藏** 标签页列出所有贮藏，可以应用、弹出和删除。

**搁置** 由 IDE 管理，以补丁形式保存在 `.openidea/shelf` 中：

- **搁置更改…**：选择文件并命名，之后这些更改会被还原。
- **取消搁置…**：以三方合并的方式把搁置（或其中某个文件）应用到你选择的更改列表。
- **搁置** 标签页列出所有搁置，支持查看差异、与本地比较、导出补丁、重命名和删除。

在 Git 设置中打开 **在同一个标签页中合并显示贮藏和搁置**，两者会显示在同一个标签页里。

**Git › 补丁** 包含 **创建补丁…**、**应用补丁…** 和 **从剪贴板应用补丁…**。

## Blame 与历史

- **使用 Git Blame 注解** 在边栏中逐行显示作者和日期（也可以从边栏右键菜单打开）。点击某条记录会在日志中打开对应提交。在 Git 设置中打开 **为当前行显示内联 Git Blame**，会在光标所在行末尾显示作者。
- 注解行的右键菜单中，**标注上一版本** 会打开该提交之前版本的文件（已注解），与这个提交的版本并排显示。
- **标注指定版本…** 可选择文件的任意版本，把该版本（已注解）与工作区文件并排显示。
- **显示历史记录** 在 Git 工具窗口的标签页中打开文件历史。
- **显示所选内容的历史记录** 列出修改过所选行的提交。
- **显示当前修订版** 在日志中定位光标所在行的提交。

### 本地历史记录

本地历史记录独立于 Git 保存文件快照，包括已删除的文件，以及重构前自动记录的状态等带标签的快照。

- **Git › 当前文件 › 本地历史记录**（或项目视图中的 **本地历史记录 › 显示历史记录**）打开文件或文件夹的历史。选中某个版本后点击 **还原**（已删除的文件为 **恢复**）。
- **添加标签…** 给当前状态打标记。
- **最近的更改**（`⌥⇧C` / `Alt+Shift+C`）列出整个项目最近的编辑。

保留策略在 **设置 › 外观与行为 › 系统设置** 的 **本地历史记录** 部分设置：默认保留 5 个工作日、每个项目 512 MB。超过 2 MB 的文件不会自动保存快照。

## 设置

**设置 › 版本控制** 包含以下页面：

| 页面         | 主要选项                                                                                                                                       |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **提交**     | 非模态提交界面、提交后清空消息、提交消息检查（主题与正文之间空行、主题和正文长度、右边距）、默认提交检查。                                     |
| **确认**     | 新建或删除文件时的处理方式、**更新前显示选项**、丢弃提交前确认、在项目视图中高亮包含修改的目录、历史记录行数上限。                             |
| **目录映射** | 检测到的仓库（只读）。                                                                                                                         |
| **问题导航** | 把提交消息中的问题编号变成链接的正则规则（内置 JIRA、YouTrack 和 GitHub 预设）。                                                               |
| **日志**     | 引用和时间的显示方式、显示哪些列。                                                                                                             |
| **搁置**     | 应用后从搁置中移除文件。                                                                                                                       |
| **Git**      | Git 可执行文件、内联 Blame、提交警告、默认签署、推送选项和受保护分支、更新方式（合并或变基）、传入提交检查、已保存的密码、合并显示贮藏和搁置。 |
| **GitHub**   | 见 [GitHub](/zh/guide/github)。                                                                                                                |

## 暂不支持

- Mercurial、Subversion、Perforce 等其他版本控制系统。
- 子模块命令、编辑目录映射。
- 按行的部分提交（只支持按代码块）以及按文件贮藏。
- 除大文件警告外的 Git LFS 支持。