在 GitHub Docs 上使用 Git

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

本文档假设您已经将文档存储库克隆到本地，并且您将在本地计算机上进行更改，而不是在 GitHub.com 或 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.com 上的远程存储库。
- 第一次推送分支时，您可以选择添加上游跟踪分支。这允许您在该分支上使用git pull和git push，而无需其他参数。
```
git push --set-upstream origin YOUR-TOPIC-BRANCH
```
- 如果您之前已经推送过此分支，并且设置了上游跟踪分支，则可以使用
```
git push
```

提交的最佳实践

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

注意：我们通常不会通过提交来关闭问题。要关闭问题，请打开拉取请求并在描述中添加“关闭 #1234”。当拉取请求合并时，链接的问题将被关闭。有关更多信息，请参阅“将拉取请求链接到问题”。
使提交消息清晰、详细且具有命令性。例如：“添加有关 2FA 的概念性文章”，而不是“添加信息”。
在您结束一天的工作时，尽量不要在本地分支中留下未提交的更改。找到一个合适的停止点，提交并推送您的更改，以便将您的工作备份到远程存储库。
仅在您进行了一些提交后才推送到 GitHub.com。每次提交后推送会增加 Slack 上我们运营渠道的噪音，并导致不必要的构建运行。

解决合并冲突

当您尝试合并包含对文件相同部分的不同更改的两个分支时，您将遇到合并冲突。在我们的工作流程中，这最常发生在将main合并到本地主题分支时。

有两种方法可以处理合并冲突

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

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

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

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

 <<<<<<< 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.com 上的远程仓库。
```
git push
```

创建拉取请求

我们建议您尽早地在 GitHub 上打开您的拉取请求。在您准备好进行审查之前，将拉取请求创建为草稿。每次您推送更改时，您的提交都会被添加到拉取请求中。

注意：您可以通过点击 GitHub.com 上每个页面顶部的拉取请求快速访问您创建的拉取请求。

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