跳转到主要内容
Git 是一种版本控制系统，可用于跟踪文档的变更并与团队成员协作。借助 Git，你可以查看项目中每个文件在不同时间点发生了哪些变更、是谁在什么时间做出的变更，以及变更的原因。如有需要，也可以轻松恢复到文件的早期版本。 Web 编辑器会在后台执行 Git 操作。理解 Git 之后，你可以更高效地使用 Web 编辑器，并与在本地开发环境中工作的团队成员协作。

​
为什么为文档选择 Git？

Git 为管理文档提供了一些关键功能。
  • 版本历史：查看每个文件的更改内容、更改时间以及更改原因。
  • 协作：多人可以同时在不同部分进行编辑。
  • 安全性：可以放心尝试，而不会破坏线上文档。
  • 审查流程：团队成员可以在发布前审查更改。
  • 恢复：撤销错误或恢复到之前的版本。

​
初次接触 Git？

如果你完全不熟悉 Git 和版本控制，可以按下面的步骤开始入门。
1

先使用网页编辑器。

网页编辑器 会自动处理 Git 操作。
  • 在编写时即可直观看到所有更改。
  • 一键创建分支。
  • 在不使用 Git 命令的情况下发布并创建拉取请求 (PR) 。
这样你就可以在不使用命令行的前提下学习 Git 概念。
2

在实践中学习。

当你使用网页编辑器时，其实已经在使用 Git。
  • 保存更改 会创建一次提交。
  • Create branch 会创建一个 Git 分支。
  • Publish 会发起一个供审查的拉取请求 (PR) 。
3

在需要时探索本地开发。

你可以完全通过网页编辑器和控制台管理文档，但也可以在本地环境中工作，自定义你的工作流。
  • 在你喜欢的编辑器中创建和编辑文件。
  • 使用命令行 Git、GitHub Desktop，或编辑器中的扩展。
  • 在发布前在本地预览更改。
  • 与其他工具集成，例如支持工单、问题跟踪和设计系统。

​
核心 Git 概念

分支指向存储库中的某个特定提交。你的线上文档是从部署用分支构建的。你可以创建任意数量的其他分支，这些分支上的更改尚未发布到线上文档。如果你想把某个分支的更改合并进线上文档，可以通过拉取请求 (PR；亦称“合并请求”/Merge Request) 将该分支合并到部署用分支。使用分支可以在不影响线上文档的情况下进行修改、安全试验新功能，并在发布前获取评审。
将某个存储库的完整副本下载到你的电脑上，包括所有文件和完整历史。克隆后，你会获得在本地工作所需的一切。
git clone https://github.com/your-org/your-repo
在特定时间点保存的更改快照。每个提交都包含一条描述更改内容的消息，并在项目历史中创建一条永久记录。
当两个人以不同方式修改了文件的同一部分时就会发生冲突。Git 会要求你手动选择保留哪一处修改，或者将两处修改合并。
你的项目的主分支。对该分支的更改会自动发布到你的文档站点。通常称为 main，但你可以将任意分支设为部署用分支。
Diff (差异) 用于显示文件两个版本之间的更改。在审查拉取请求时，Diff 会突出显示相较于文件原始版本有哪些不同。
将一个分支上的更改合并到另一个分支。通常会在评审之后，通过拉取请求将功能开发合并进部署用分支。
从远程存储库获取最新更改到你的本地副本，使你始终与他人的工作保持同步。
git pull
一种提议将某个分支上的更改合并到线上文档的方式。它允许在更改上线之前进行评审和讨论。通常称为 PR，在 GitLab 中也称为 merge request (合并请求) 。
将你的本地提交发送到远程存储库。这样可以让其他人获取到你的更改，并且可能触发自动部署。
git push
托管在服务器上的存储库版本。本地存储库通过连接远程存储库来推送和拉取更改。
你的文档源代码，包括构成文档站点页面的所有文件及其历史。Web 编辑器会连接到你的文档存储库以访问和修改 content。
为下一次提交准备特定的更改。暂存可以帮助你将更改组织成逻辑清晰的多次提交。
git add filename.mdx

​
Web 编辑器如何使用 Git

Web 编辑器通过 GitHub 应用 或 GitLab 集成 连接到你的 Git 存储库，并自动化常见的 Git 操作。 当你：
  • 打开文件：编辑器会从你的存储库获取最新版本，确保你始终在处理最新内容。
  • 进行更改：编辑器会将你的更改作为草稿进行跟踪，当你准备保存时可生成一次提交。
  • 保存更改：编辑器会基于你的更改创建一次提交，将你的工作保存在项目历史中。
  • 创建 branch：编辑器会在你的存储库中创建一个新的 branch，任何具有存储库访问权限的人都可以使用它来协作并审阅更改。
  • 在你的部署用分支上发布：编辑器会直接向你的部署用分支提交并推送，从而立即发布你的更改。
  • 在其他分支上发布：编辑器会创建一个拉取请求 (PR；亦称“合并请求”/Merge Request) ，以便你在将更改合并到部署用分支之前先获取他人的反馈。

​
常见工作流程

​
直接发布到部署用分支

  1. 在网页编辑器中打开文件。
  2. 进行修改。
  3. 点击 Publish。
  4. 修改会同步到存储库并自动部署。

​
在功能 branch 上工作

要在 Web 编辑器中创建拉取请求 (PR) ，你必须启用一条 branch 保护规则，要求更改在合并到部署用分支之前先通过拉取请求。如果没有 branch 保护规则，branch 上的更改在发布时会直接合并到部署用分支。
  1. 在编辑器工具栏的 branch 下拉菜单中创建新的 branch。
  2. 在该 branch 上进行更改并保存。
  3. 点击 Publish 以创建拉取请求 (PR) 。
  4. 准备好后合并该拉取请求。

​
在发布前审查更改

1

创建一个 feature branch。

在一个独立于部署用分支的 branch 中进行更改，这样你就可以在发布前共享并审查这些更改。
2

进行你的更改。

编辑文件并将更改提交到 feature branch。
3

创建一个 pull request。

创建一个拉取请求 (PR；亦称“合并请求”/Merge Request) ，以提议将 feature branch 上的更改合并到部署用分支。
4

审查 diff。

检查你的更改。拉取请求会逐行显示与文件原始版本之间的差异。
5

获取团队反馈。

团队成员可以针对特定行或整体更改发表评论。根据反馈进行修改，并将其提交到 feature branch。
6

批准后合并。

合并拉取请求，将更改发布到在线文档站点。

​
Git 最佳实践

每个团队都会形成自己的工作流和偏好，但下面这些是帮助你入门的一般最佳实践。
  • 编写有描述性的提交信息：使用主动语态，具体说明更改内容。Fix broken link in API docs 比 update page 提供更多信息。
  • 使用有意义的 branch 名称：branch 名称应说明该 branch 的用途。使用类似 update-api-reference 这样信息量大的名称，而不是 temp 或 my-branch 这类泛泛的名字。
  • 让 branch 变更保持聚焦：让一个 branch 上的更改专注于某个特定任务或项目。这会让代码审查更容易，并减少冲突。
  • 合并后删除 branch：在不再需要时删除 branch，以保持存储库整洁。
  • 先 pull 再 push：始终在 push 之前先 pull 最新更改，以避免冲突。Web 编辑器会自动执行这一步。
  • 先自查再发起审查：在创建拉取请求 (PR；亦称“合并请求”/Merge Request) 之前先检查 diff。