使用 branch

创建和管理文档 branch，以预览变更、与团队成员协作，并在发布到生产环境之前合并更新。

Branch 是版本控制的一项功能，用于指向存储库中特定的提交。你的部署用分支，通常称为 main，代表用于构建在线文档站点的内容。除非你选择将其合并到部署用分支，否则所有其他 branch 都与在线文档相互独立。

Branch 使你可以为文档创建独立实例，以进行更改、获取评审，并在发布前尝试新方案。你的团队可以在不同 branch 上同时更新文档的不同部分，而不会影响用户在在线站点上看到的内容。

下图展示了一个 branch 工作流示例：在该流程中创建一个功能 branch，完成更改后，再将该功能 branch 合并回 main branch。

我们建议在更新文档时始终基于 branch 开展工作，以保持在线站点稳定，并支持评审流程。

​

Branch 命名规范

使用清晰、具有描述性的名称来说明该 branch 的用途。

推荐使用：

• fix-broken-links
• add-webhooks-guide
• reorganize-getting-started
• ticket-123-oauth-guide

避免使用：

• temp
• my-branch
• updates
• branch1

​

创建 branch

使用 Web 编辑器

1. 点击编辑器工具栏中的 branch 名称。
2. 点击 Create new branch。
3. 输入一个有描述性的名称。
4. 如果你有未保存的更改，选择是将更改带到新 branch 还是保留在当前 branch。
5. 点击 Create branch。

使用本地开发环境

1. 在终端中创建一个 branch

   git checkout -b branch-name
   

   这一条命令会创建该 branch 并同时切换到它。

2. 将 branch 推送到 GitHub

   git push -u origin branch-name
   

   -u 参数会设置跟踪，这样之后推送时只需要运行 git push 即可。

​

在 branch 上保存更改

使用 Web 编辑器

在编辑器工具栏右上角选择 Save as commit 按钮。这会创建一个提交，并自动将你的更改推送到你的 branch。

使用本地开发环境

暂存、提交并推送你的更改。

git add .
git commit -m "Describe your changes"
git push

​

切换 branch

使用 Web 编辑器

1. 点击编辑器工具栏中的 branch 名称以打开 branch 下拉菜单。
2. 按名称搜索 branch 或滚动浏览列表。
3. 点击要切换到的 branch。

下拉菜单中的每个 branch 都会显示一个状态指示器，便于你查看该 branch 是否就绪、正在同步或已失败。

切换 branch 时，未保存的更改将会丢失。请先保存你的工作。

使用本地开发环境

切换到已有的 branch：

git checkout branch-name

或者使用一条命令创建并切换：

git checkout -b new-branch-name

​

合并 branch

当你的更改准备好发布时，创建一个拉取请求（PR；亦称“合并请求”/Merge Request），将你的 branch 合并到部署用分支。