在 GitHub 文档上使用 Git

本文档描述了为文档仓库创建主题分支、提交更改并将更改推送回远程仓库的过程。

本文假设您已经在本地克隆了文档仓库，并且将在本地计算机上进行更改，而不是在 GitHub 或代码空间中。有关更多信息，请参阅克隆仓库。

设置主题分支并进行更改

为了使本地分支与远程保持同步并避免合并冲突，请在编写文档时遵循以下步骤。

在终端中，将当前工作目录更改为您克隆文档仓库的位置。例如
```
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 - 添加在升级前备份虚拟机的步骤”。

注意

我们通常不通过提交来关闭问题。要关闭问题，请打开一个拉取请求并在描述中添加 “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 每个页面顶部的 Pull requests 快速访问您创建的拉取请求。

了解更多信息，请参阅创建拉取请求。