在 GitHub Docs 上使用 Git

本文介绍为文档存储库创建主题分支、提交更改以及将更改推送回远程存储库的过程。

本文假设你已在本地克隆文档存储库，并且你将在本地计算机上进行更改，而不是在 GitHub 或 codespace 中进行更改。有关详细信息，请参阅“克隆仓库”。

设置主题分支并进行更改

若要使本地分支与其远程分支保持同步并避免合并冲突，请在处理文档时执行以下步骤。

在终端中，将当前工作目录更改为克隆文档存储库的位置。例如：
```
cd ~/my-cloned-repos/docs
```
切换到默认分支：main。
```
git checkout main
```
从远程存储库获取最新的提交。
```
git pull origin main
```
切换到主题分支或创建主题分支。
- 若要启动新项目，请从 main 创建新的主题分支。
```
git checkout -b YOUR-TOPIC-BRANCH
```
  注意：可以使用正斜杠作为分支名称的一部分，以包含用户名：
```
git checkout -b my-username/new-codespace-policy
```
- 若要处理现有项目，请切换到主题分支，并从 main 合并更改。
```
git checkout YOUR-TOPIC-BRANCH
git merge main
```
  如果遇到合并冲突，请按照本文后面解决合并冲突的步骤操作。
打开首选文本编辑器，根据需要编辑文件，然后保存更改。

提交和推送更改

准备好提交更改时，打开终端并使用 git status 检查主题分支的状态。请确保看到的更改集正确。

git status
On branch YOUR-TOPIC-BRANCH

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)
        deleted:    example-deleted-file.md
        modified:   example-changed-file.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        example-new-file.md

暂存已更改的文件，使它们准备好提交到主题分支。
- 如果创建了新文件或更新了现有文件，请使用 git add FILENAME [FILENAME...]。例如：
```
git add example-new-file.md example-changed-file.md
```
  这会将文件的更新版本添加到 Git 的暂存区域，可从中提交更改。若要取消暂存文件，请使用 git reset HEAD FILENAME。例如，git reset HEAD example-changed-file.md。
- 如果删除了文件，请使用 git rm FILENAME [FILENAME...]。例如：
```
git rm example-deleted-file.md
```
提交更改。
```
git commit -m "Commit message title (max 72 characters)

Optional fuller description of what changed (no character limit).
Note the empty line between the title and the description,
and the closing quotation mark at the end of the commit message."
```
这会在本地提交暂存更改。现在，可以将此提交和任何其他未推送的提交推送到远程存储库。

若要删除此提交，请使用 git reset --soft HEAD~1。运行此命令后，不再提交更改，但更改的文件保留在暂存区域中。可以进行进一步的更改，然后再次执行 add 和 commit 操作。
将更改推送到 GitHub 上的远程存储库。
- 首次推送分支时，可以选择添加上游跟踪分支。这使你能够在没有附加参数的情况下对该分支使用 git pull 和 git push。
```
git push --set-upstream origin YOUR-TOPIC-BRANCH
```
- 如果之前已推送此分支并设置了上游跟踪分支，可以使用：
```
git push
```

提交最佳做法

相比包含大型、不集中的变更组的提交，更倾向于包含小型、集中的变更组的提交，因为这有助于编写其他人员可以轻松理解的提交消息。新项目或类别的初始提交是一个例外。这些提交有时很大，因为它们通常同时引入许多裸版文章，为后续工作提供组织方案。
如果要整合反馈或希望向特定人员或团队提交一组更改以供评审，则 @mention 你要整合其建议的人员。例如：“整合来自 @octocat 的反馈”或“更新计费配置步骤 - 抄送 @monalisa 以确保准确性”。
如果一个提交解决了一个问题，则可以在该提交中引用该问题编号，指向该提交的链接将出现在问题对话时间线中：“解决 #1234 - 添加在升级前备份 VM 的步骤。”

注意：通常不通过提交来关闭问题。若要关闭问题，请打开一个拉取请求并向说明添加“关闭 #1234”。合并拉取请求时，链接的问题将关闭。有关详细信息，请参阅“将拉取请求链接到议题”。
使提交消息清晰、详细且必要。例如：“添加有关 2FA 的概念文章”，而不是“添加信息”。
完成一天的工作后，尽量不要将未提交的更改留在本地分支中。找到一个良好的停止点，提交并推送更改，以便将工作备份到远程存储库。
只有在你进行了几次提交后，才可向上推送到 GitHub。每次提交后都进行推送会给 Slack 上的操作通道带来干扰，并导致不必要的生成运行。

解决合并冲突

尝试将包含不同更改的两个分支合并到文件的同一部分时，你将遇到合并冲突。在我们的工作流中，这种情况最常发生在将 main 向下合并到本地主题分支时。

可通过两种方法处理合并冲突：

在文本编辑器中编辑文件，然后选择要保留的更改。然后，从命令行将更新的文件提交到主题分支。
在 GitHub 上解决合并冲突。

通过编辑文件并提交更改来解决合并冲突

在命令行上，记下包含合并冲突的文件。
在文本编辑器中打开其中第一个文件。

在该文件中，查找合并冲突标记。

 <<<<<<< HEAD
 Here are the changes you've made.
 =====================
 Here are the changes from the main branch.
 >>>>>>> main

确定要保留的更改，删除不需要的更改和合并冲突标记。如果需要进行进一步的更改，可以同时执行此操作。例如，可以将上一代码示例中显示的五行更改为单行：
```
Here are the changes you want to use.
```
如果有多个文件存在合并冲突，请重复上述步骤，直到解决所有冲突。

注意：在解决合并冲突时，应小心谨慎。你有时只需接受自己的更改，有时将使用分支 main 中的上游更改，有时将合并这两组更改。如果你不确定最佳解决方案，请小心替换上游的更改，因为这些更改可能是出于你不知道的特定原因而进行的。
在终端中，暂存你刚刚修改的文件。
```
git add changed-file-1.md changed-file-2.md
```

提交文件。

git commit -m "Resolves merge conflicts"

将提交的更改推送到 GitHub 上的远程存储库。
```
git push
```

创建拉取请求

建议尽早在 GitHub 上打开拉取请求。将拉取请求创建为草稿，直至你准备好对其进行评审。每次推送更改时，提交都会添加到拉取请求。

注意：单击 GitHub 上每个页面顶部的“拉取请求”，可以快速访问已创建的拉取请求。

有关详细信息，请参阅“创建拉取请求”。