如何在 GitHub 上创建一个 Pull Request

介绍

Git 是一个开源的分布式版本控制系统，使得协作软件项目更加可管理。许多项目将它们的文件保存在 Git 存储库中，而像 GitHub 这样的平台使得分享和贡献代码变得更加容易、有价值和有效。

托管在公共存储库中的开源项目通过拉取请求受益于更广泛的开发者社区所做的贡献，这些请求要求项目接受您对其代码存储库所做的更改。

本教程将指导您通过命令行向 Git 存储库发出拉取请求，以便您可以为开源软件项目做出贡献。

先决条件

您的本地计算机上应安装有 Git。您可以通过以下指南检查 Git 是否已安装在您的计算机上，并完成操作系统的安装过程。

您还需要拥有或创建一个 GitHub 帐户。您可以通过 GitHub 网站 github.com 进行创建，并可以选择登录或创建您的帐户。

截至 2020 年 11 月，GitHub 移除了基于密码的身份验证。因此，您需要创建个人访问令牌或添加您的 SSH 公钥信息，以便通过命令行访问 GitHub 存储库。

最后，您应该确定要为之做出贡献的开源软件项目。您可以通过阅读此介绍来更加了解开源项目。

创建存储库的副本

存储库，或简称repo，实质上是项目的主文件夹。存储库包含所有相关项目文件，包括文档，并且还存储了每个文件的修订历史。在 GitHub 上，存储库可以有多个协作者，并且可以是公共的或私有的。

为了在开源项目上工作，您首先需要创建存储库的副本。为此，您应该分叉存储库，然后克隆它，以便您有一个本地的工作副本。

分叉存储库

您可以通过浏览器导航到您想要为其做出贡献的开源项目的 GitHub URL 来分叉存储库。

GitHub 存储库的 URL 将引用与存储库所有者关联的用户名，以及存储库名称。例如，DigitalOcean Community（用户名：do-community）是 cloud_haiku 项目存储库的所有者，因此该项目的 GitHub URL 为：

https://github.com/do-community/cloud_haiku

在上面的示例中，do-community 是用户名，cloud_haiku 是存储库名称。

一旦您确定了要为其做出贡献的项目，您可以导航到以下格式的 URL：

https://github.com/username/repository

或者，您可以使用 GitHub 搜索栏搜索该项目。

当您在存储库的主页面时，Fork 按钮将显示在页面右上角，在您的用户图标下方：

!GitHub 分叉

单击Fork 按钮开始分叉过程。在您的浏览器窗口中，您将收到有关正在处理您正在分叉的存储库的通知：

!GitHub 分叉中

一旦过程完成，您的浏览器将转到类似于先前存储库屏幕的屏幕，只是在顶部您将在存储库名称之前看到您的用户名，并且在 URL 中也将在存储库名称之前显示您的用户名。

因此，在上面的示例中，页面顶部将显示 your-username / cloud_haiku，新的 URL 将类似于以下内容：

https://github.com/your-username/cloud_haiku

存储库分叉完成后，您就可以克隆它，以便您有代码库的本地工作副本。

克隆存储库

为了创建您自己的存储库的本地副本，让我们首先打开一个终端窗口。

我们将使用 git clone 命令以及指向您存储库分叉的 URL。

这个 URL 将类似于上面的 URL，只是现在它将以 .git 结尾。在上面的 cloud_haiku 示例中，URL 将类似于以下内容，您的实际用户名将替换 your-username：

https://github.com/your-username/cloud_haiku.git

您还可以通过使用您从原始存储库页面分叉的存储库页面上的绿色**“⤓ Code”**按钮来复制 URL。一旦单击该按钮，您将能够通过单击 URL 旁边的剪贴板按钮来复制 URL：

!GitHub 克隆或下载

一旦我们有了 URL，我们就可以克隆存储库。为此，我们将在终端窗口中的命令行中将 git clone 命令与存储库 URL 结合使用：

git clone https://github.com/your-username/repository.git

现在我们有了代码的本地副本，我们可以继续创建一个新的分支，在该分支上进行代码工作。

创建一个新分支

每当你参与协作项目时，你和其他程序员对于新功能或修复可能会有不同的想法。其中一些新功能不会花费太多时间来实现，但有些可能会是持续进行的。因此，重要的是要为代码库创建分支，以便能够管理工作流程，隔离你的代码，并控制哪些功能会回到项目代码库的主分支。

项目代码库的主要分支通常被称为 main 分支。建议的做法是将主分支上的任何内容都视为随时可供他人使用的可部署内容。

在基于现有项目创建分支时，非常重要的一点是要从主分支创建你的新分支。你还应该确保你的分支名称具有描述性。与其称其为 my-branch，你应该选择类似 frontend-hook-migration 或 fix-documentation-typos 的名称。

要在我们的终端窗口中创建分支，让我们切换到代码库的目录中，确保使用实际的代码库名称（如 cloud_haiku）切换到该目录。

cd repository

现在，我们将使用 git branch 命令创建新分支。确保给它一个描述性的名称，以便其他项目成员了解你正在做什么。

git branch new-branch

现在我们已经创建了新分支，我们可以使用 git checkout 命令切换到该分支以确保我们正在该分支上工作：

git checkout new-branch

一旦输入 git checkout 命令，你将收到以下输出：

Switched to branch 'new-branch'

或者，你可以使用以下命令和 -b 标志来简化上述两个命令，创建并切换到新分支：

git checkout -b new-branch

如果你想切换回 main，你将使用带有主分支名称的 checkout 命令：

git checkout main

checkout 命令将允许你在多个分支之间切换，因此你可以同时处理多个功能。

此时，你现在可以在自己的分支上修改现有文件或向项目中添加新文件。

本地进行更改

为了演示如何发起拉取请求，让我们使用示例 cloud_haiku 代码库，在本地副本中创建一个新文件。使用你喜欢的文本编辑器创建一个新文件，以便我们可以按照贡献指南添加一首新的俳句诗。例如，我们可以使用 nano，并将我们的示例文件命名为 filename.md。你需要使用一个带有 .md 扩展名的原始名称来命名你的文件，以便进行 Markdown 格式化。

nano filename.md

接下来，我们将向新文件添加一些文本，按照贡献指南的要求。我们需要使用 Jekyll 格式，并添加一个带有换行的俳句。以下文件是一个示例文件，你需要贡献一首原创的俳句。

---
layout: haiku
title: Octopus Cloud
author: Sammy
---Distributed cloud <br>
Like the octopuses' minds <br>
Across the network <br>

一旦你包含了你的文本，保存并关闭文件。如果你使用的是 nano，按 CTRL + X，然后 Y，最后 ENTER 来完成。

一旦你修改了现有文件或向你选择的项目中添加了新文件，你可以使用 git add 命令将其添加到你的本地代码库中。在我们的示例中，filename.md，我们将输入以下命令。

git add filename.md

我们将文件名传递给这个命令，以将其添加到我们的本地代码库中。这确保了你的文件已准备好被添加。

如果你想要添加你在特定目录中修改的所有文件，你可以使用以下命令将它们全部添加：

git add .

在这里，句号将添加所有相关文件。

如果你想要递归地添加所有更改，包括子目录中的更改，你可以输入：

git add -A

或者，你可以输入 git add -all 来添加所有新文件。

当我们的文件被添加到暂存区后，我们将使用 git commit 命令记录我们对代码库所做的更改。

提交更改

提交消息 是你代码贡献的重要方面；它帮助维护者和其他贡献者充分理解你所做的更改，为什么做出这些更改以及其重要性。此外，提交消息为项目的更改提供了历史记录，帮助未来的贡献者。

如果我们有一个非常简短的消息，我们可以使用 -m 标志和带引号的消息来记录。在我们添加俳句的示例中，我们的 git commit 可能类似于以下内容。

git commit -m "在 filename.md 文件中添加了一首新的俳句"

除非是一个较小或预期的更改，我们可能希望包含一个更长的提交消息，以便我们的合作者完全了解我们的贡献。要记录这条较长的消息，我们将运行 git commit 命令，它将打开默认的文本编辑器：

git commit

运行此命令时，你可能会注意到你正在使用 vim 编辑器，你可以通过输入 :q 来退出。如果你想配置你的默认文本编辑器，你可以使用 git config 命令，并将 nano 设置为默认编辑器，例如：

git config --global core.editor "nano"

或者 vim：

git config --global core.editor "vim"

运行 git commit 命令后，根据你正在使用的默认文本编辑器，你的终端窗口应该显示一个准备供你编辑的文档，类似于下面的内容：


```markdown
# 请输入您的更改的提交消息。以“＃”开头的行将被忽略，空消息将中止提交。
# 在新分支上
# 您的分支是最新的'origin/new-branch'。
#
# 要提交的更改：
#       修改：new-feature.py
#

在介绍性注释下面，您应该将提交消息添加到文本文件中。

要编写有用的提交消息，您应该在第一行包括一个大约50个字符长的摘要。在此之下，并分成易于理解的部分，您应该包括一个描述，说明您进行此更改的原因，代码的工作原理以及其他信息，以便在合并时为其他人提供上下文和澄清。尽量尽可能地提供帮助和积极性，以确保维护项目的人员能够充分理解您的贡献。

推送更改

保存并退出提交消息文本文件后，您可以使用以下命令验证Git将提交的内容：

git status

根据您所做的更改，您将收到类似于以下内容的输出：

在分支new-branch
没有要提交的内容，工作树干净

此时，您可以使用git push命令将更改推送到您分叉的存储库的当前分支：

git push --set-upstream origin new-branch

该命令将向您提供输出，让您了解进度，并且类似于以下内容：

计数对象：3，完成。
使用多达4个线程进行增量压缩。
压缩对象：100%（2/2），完成。
写入对象：100%（3/3），336字节| 0字节/秒，完成。
总共3（增量0），重用0（增量0）
到https://github.com/your-username/repository.gita1f29a6..79c0e80  new-branch  -> new-branch
分支new-branch设置为跟踪来自origin的远程分支new-branch。

现在，您可以转到GitHub网页上的分叉存储库，并切换到您推送的分支，以在浏览器中查看您所做的更改。

此时，可以向原始存储库发出拉取请求，但如果您尚未这样做，您需要确保本地存储库与上游存储库保持最新。

更新本地存储库

当您与其他贡献者一起开发项目时，重要的是要保持本地存储库与项目同步，这样您就不会为自动引起冲突的代码发出拉取请求（尽管在协作代码项目中，冲突是不可避免的）。为了保持代码库的本地副本更新，您需要同步更改。

首先，我们将首先配置分叉的远程存储库，然后同步分叉。

为分叉配置远程存储库

远程存储库使您能够与他人协作进行Git项目。每个远程存储库都是托管在互联网或您可以访问的网络上的项目的一个版本。每个远程存储库应该对您来说是只读或读写的，具体取决于您的用户权限。

为了能够将您在分叉中进行的更改与您正在使用的原始存储库同步，您需要配置一个引用上游存储库的远程。您应该仅在设置远程指向上游存储库时进行一次设置。

让我们首先检查您已配置了哪些远程服务器。git remote命令将列出您已经指定的任何远程存储库，因此，如果您像上面那样克隆了存储库，您至少会收到有关origin存储库的输出，这是Git为克隆目录给出的默认名称。

从我们的终端窗口中的存储库目录，让我们使用git remote命令以及-v标志来显示Git存储的URL以及相关的远程短名称（如“origin”）：

git remote -v

由于我们克隆了一个存储库，我们的输出应该类似于这样：

origin    https://github.com/your-username/forked-repository.git (fetch)
origin    https://github.com/your-username/forked-repository.git (push)

如果您之前设置了多个远程存储库，git remote -v命令将提供所有这些的列表。

接下来，我们将为我们指定一个新的上游远程存储库，以便与分叉同步。这将是我们从中分叉的原始存储库。我们将使用git remote add命令来执行此操作。

git remote add upstream https://github.com/original-owner-username/original-repository.git

对于我们的cloud_haiku示例，此命令将如下所示：

git remote add upstream https://github.com/do-community/cloud_haiku.git

在此示例中，upstream是我们为远程存储库提供的短名称，因为在Git方面，“upstream”指的是我们从中克隆的存储库。如果我们想要添加到协作者的存储库的远程指针，我们可能需要提供该协作者的用户名或短名称作为短名称。

我们可以再次使用git remote -v命令从存储库目录验证我们对上游存储库的远程指针是否已正确添加：

git remote -v

origin    https://github.com/your-username/forked-repository.git (fetch)
origin    https://github.com/your-username/forked-repository.git (push)
upstream    https://github.com/original-owner-username/original-repository.git (fetch)
upstream    https://github.com/original-owner-username/original-repository.git (push)

现在，您可以在命令行中引用upstream而不是写整个URL，并且您已准备好将您的分叉与原始存储库同步。


### 同步分支一旦我们配置了一个远程引用上游和 GitHub 上的原始仓库，我们就可以准备同步我们的分支以保持最新状态。要同步我们的分支，在终端窗口中，从本地仓库的目录中，我们将使用 `git fetch` 命令从上游仓库获取分支以及它们各自的提交。由于我们使用了短名称“upstream”来引用上游仓库，我们将把它传递给该命令。```bash
git fetch upstream

取决于自从我们分叉仓库以来进行了多少更改，你的输出可能会有所不同，并且可能包括一些关于计数、压缩和解压对象的内容。你的输出将以类似以下行结束，但根据项目中有多少分支可能会有所不同：

From https://github.com/original-owner-username/original-repository* [new branch]      main     -> upstream/main

现在，主分支的提交将存储在一个名为 upstream/main 的本地分支中。

让我们切换到我们仓库的本地主分支：

git checkout main

Switched to branch 'main'

现在，我们将合并在原始仓库的主分支中进行的任何更改（通过我们的本地 upstream/main 分支访问），与我们的本地主分支：

git merge upstream/main

这里的输出会有所不同，但如果有更改，它将以 Updating 开头，如果自从你分叉仓库以来没有进行更改，则以 Already up-to-date 开头。

你的分支现在与上游仓库同步，你所做的任何本地更改都不会丢失。

根据你自己的工作流程和你花在进行更改上的时间，你可以根据自己的需要多次将你的分支与原始仓库的上游代码同步。但是，在发起拉取请求之前，你应该确保同步你的分支，以确保你不会自动贡献冲突的代码。

创建拉取请求

此时，你已经准备好向原始仓库发起拉取请求。

你应该导航到你的分叉仓库，并在页面的左侧点击 New pull request 按钮。

!GitHub Pull Request Button

你可以在下一个屏幕上修改分支。在任一侧，你可以从下拉菜单中选择适当的仓库和适当的分支。

一旦你选择了，例如，在左侧选择了原始仓库的主分支，在右侧选择了你的分叉仓库的 new-branch，你应该会收到一个屏幕，上面显示如果没有竞争代码，你的分支可以合并：

!GitHub Pull Request

你应该在适当的字段中添加标题和评论，然后点击 Create pull request 按钮。

此时，原始仓库的维护者将决定是否接受你的拉取请求。他们可能会要求你在接受拉取请求之前编辑或修改你的代码，通过提交代码审查。

结论

此时，你已成功向开源软件仓库发送了一个拉取请求。在等待进行审查时，你应该确保更新和重新基于你的代码。项目维护者可能会要求你重新编写你的代码，所以你应该做好准备。

为开源项目做出贡献，并成为一名活跃的开源开发者，可能是一种有益的经验。定期为你经常使用的软件做出贡献，可以确保该软件对其他最终用户来说是尽可能有价值的。

如果你有兴趣了解更多关于 Git 和在开源软件上进行协作的知识，你可以阅读我们的教程系列，名为 An Introduction to Open Source。如果你已经熟悉 Git，并且需要一份速查表，你可以参考“How To Use Git: A Reference Guide”。