> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 文档相关的 Git 概念

> 学习用于文档即代码工作流的 Git 版本控制基础知识，包括仓库、branch、commit 和拉取请求协作。

Git 是一种版本控制系统，可用于跟踪文档的变更并与团队成员协作。借助 Git，你可以查看项目中每个文件在不同时间点发生了哪些变更、是谁在什么时间做出的变更，以及变更的原因。如有需要，也可以轻松恢复到文件的早期版本。

Web 编辑器会在后台执行 Git 操作。理解 Git 之后，你可以更高效地使用 Web 编辑器，并与在本地开发环境中工作的团队成员协作。

<div id="why-git-for-documentation">
  ## 为什么为文档选择 Git？
</div>

Git 为管理文档提供了一些关键功能。

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

<div id="new-to-git">
  ## 初次接触 Git？
</div>

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

<Steps>
  <Step title="先使用网页编辑器。">
    [网页编辑器](/zh/editor/index) 会自动处理 Git 操作。

    * 在编写时即可直观看到所有更改。
    * 一键创建分支。
    * 在不使用 Git 命令的情况下发布并创建拉取请求 (PR) 。

    这样你就可以在不使用命令行的前提下学习 Git 概念。
  </Step>

  <Step title="在实践中学习。">
    当你使用网页编辑器时，其实已经在使用 Git。

    * **保存更改** 会创建一次提交。
    * **Create branch** 会创建一个 Git 分支。
    * **Publish** 会发起一个供审查的拉取请求 (PR) 。
  </Step>

  <Step title="在需要时探索本地开发。">
    你可以完全通过网页编辑器和控制台管理文档，但也可以在本地环境中工作，自定义你的工作流。

    * 在你喜欢的编辑器中创建和编辑文件。
    * 使用命令行 Git、GitHub Desktop，或编辑器中的扩展。
    * 在发布前在本地预览更改。
    * 与其他工具集成，例如支持工单、问题跟踪和设计系统。
  </Step>
</Steps>

<div id="core-git-concepts">
  ## 核心 Git 概念
</div>

<AccordionGroup>
  <Accordion title="分支">
    分支指向存储库中的某个特定提交。你的线上文档是从部署用分支构建的。你可以创建任意数量的其他分支，这些分支上的更改尚未发布到线上文档。如果你想把某个分支的更改合并进线上文档，可以通过拉取请求 (PR；亦称“合并请求”/Merge Request) 将该分支合并到部署用分支。

    使用分支可以在不影响线上文档的情况下进行修改、安全试验新功能，并在发布前获取评审。
  </Accordion>

  <Accordion title="克隆">
    将某个存储库的完整副本下载到你的电脑上，包括所有文件和完整历史。克隆后，你会获得在本地工作所需的一切。

    ```bash theme={null}
    git clone https://github.com/your-org/your-repo
    ```
  </Accordion>

  <Accordion title="提交">
    在特定时间点保存的更改快照。每个提交都包含一条描述更改内容的消息，并在项目历史中创建一条永久记录。
  </Accordion>

  <Accordion title="冲突">
    当两个人以不同方式修改了文件的同一部分时就会发生冲突。Git 会要求你手动选择保留哪一处修改，或者将两处修改合并。
  </Accordion>

  <Accordion title="部署用分支">
    你的项目的主分支。对该分支的更改会自动发布到你的文档站点。通常称为 `main`，但你可以将任意分支设为部署用分支。
  </Accordion>

  <Accordion title="Diff">
    Diff (差异) 用于显示文件两个版本之间的更改。在审查拉取请求时，Diff 会突出显示相较于文件原始版本有哪些不同。
  </Accordion>

  <Accordion title="合并">
    将一个分支上的更改合并到另一个分支。通常会在评审之后，通过拉取请求将功能开发合并进部署用分支。
  </Accordion>

  <Accordion title="拉取">
    从远程存储库获取最新更改到你的本地副本，使你始终与他人的工作保持同步。

    ```bash theme={null}
    git pull
    ```
  </Accordion>

  <Accordion title="拉取请求">
    一种提议将某个分支上的更改合并到线上文档的方式。它允许在更改上线之前进行评审和讨论。通常称为 PR，在 GitLab 中也称为 merge request (合并请求) 。
  </Accordion>

  <Accordion title="推送">
    将你的本地提交发送到远程存储库。这样可以让其他人获取到你的更改，并且可能触发自动部署。

    ```bash theme={null}
    git push
    ```
  </Accordion>

  <Accordion title="远程">
    托管在服务器上的存储库版本。本地存储库通过连接远程存储库来推送和拉取更改。
  </Accordion>

  <Accordion title="存储库">
    你的文档源代码，包括构成文档站点页面的所有文件及其历史。Web 编辑器会连接到你的文档存储库以访问和修改 `content`。
  </Accordion>

  <Accordion title="暂存">
    为下一次提交准备特定的更改。暂存可以帮助你将更改组织成逻辑清晰的多次提交。

    ```bash theme={null}
    git add filename.mdx
    ```
  </Accordion>
</AccordionGroup>

<div id="how-the-web-editor-uses-git">
  ## Web 编辑器如何使用 Git
</div>

Web 编辑器通过 [GitHub 应用](/zh/deploy/github) 或 [GitLab 集成](/zh/deploy/gitlab) 连接到你的 Git 存储库，并自动化常见的 Git 操作。

当你：

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

<div id="common-workflows">
  ## 常见工作流程
</div>

<div id="publish-directly-to-your-deployment-branch">
  ### 直接发布到部署用分支
</div>

<Tabs>
  <Tab title="使用网页编辑器">
    1. 在[网页编辑器](https://dashboard.mintlify.com/editor)中打开文件。
    2. 进行修改。
    3. 点击 **Publish**。
    4. 修改会同步到存储库并自动部署。
  </Tab>

  <Tab title="使用本地开发">
    1. 拉取最新变更：`git pull`
    2. 在你的编辑器中编辑文件。
    3. 暂存变更：`git add filename.mdx`
    4. 提交：`git commit -m "Update documentation"`
    5. 推送：`git push`
    6. 变更会自动部署。
  </Tab>
</Tabs>

<div id="work-on-a-feature-branch">
  ### 在功能 branch 上工作
</div>

<Tabs>
  <Tab title="使用 Web 编辑器">
    <Note>
      要在 Web 编辑器中创建拉取请求 (PR) ，你必须启用一条 branch 保护规则，要求更改在合并到部署用分支之前先通过拉取请求。如果没有 branch 保护规则，branch 上的更改在发布时会直接合并到部署用分支。
    </Note>

    1. 在编辑器工具栏的 branch 下拉菜单中创建新的 branch。
    2. 在该 branch 上进行更改并保存。
    3. 点击 **Publish** 以创建拉取请求 (PR) 。
    4. 准备好后合并该拉取请求。
  </Tab>

  <Tab title="使用本地开发">
    1. 创建一个 branch：`git checkout -b feature-name`
    2. 在本地进行更改并提交。
    3. 推送 branch：`git push -u origin feature-name`
    4. 创建一个拉取请求 (PR) 。
    5. 准备好后合并该拉取请求。
  </Tab>
</Tabs>

<div id="review-changes-before-publishing">
  ### 在发布前审查更改
</div>

<Steps>
  <Step title="创建一个 feature branch。">
    在一个独立于部署用分支的 branch 中进行更改，这样你就可以在发布前共享并审查这些更改。
  </Step>

  <Step title="进行你的更改。">
    编辑文件并将更改提交到 feature branch。
  </Step>

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

  <Step title="审查 diff。">
    检查你的更改。拉取请求会逐行显示与文件原始版本之间的差异。
  </Step>

  <Step title="获取团队反馈。">
    团队成员可以针对特定行或整体更改发表评论。根据反馈进行修改，并将其提交到 feature branch。
  </Step>

  <Step title="批准后合并。">
    合并拉取请求，将更改发布到在线文档站点。
  </Step>
</Steps>

<div id="git-best-practices">
  ## Git 最佳实践
</div>

每个团队都会形成自己的工作流和偏好，但下面这些是帮助你入门的一般最佳实践。

* **编写有描述性的提交信息**：使用主动语态，具体说明更改内容。`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。