在 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
```

提交最佳实践

优先考虑包含少量、集中更改的提交，而不是包含大量、分散更改的提交，因为这将有助于您编写其他人易于理解的提交消息。一个例外是新项目或类别的初始提交。这些提交有时很大，因为它们通常会立即引入许多文章的基本版本，以便为后续工作提供组织方案。
如果您要合并反馈或希望向特定人员或团队解决一组更改以供审查，请@提及您要合并其建议的人员。例如：“合并来自 @octocat 的反馈”或“更新计费配置步骤 - 抄送 @monalisa 以确保准确性”。
如果提交解决了某个问题，您可以在提交中引用问题编号，并且提交的链接将显示在问题对话时间线上：“解决 #1234 - 添加升级前备份 VM 的步骤”。

注意

我们通常不会通过提交关闭问题。要关闭问题，请打开拉取请求并将“Closes #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 上每个页面顶部的**拉取请求**快速访问您创建的拉取请求。

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