译自 Git Handbook

了解版本控制——特别是 Git，以及它是如何与 GitHub 一起工作的。

最后更新：2017 年 9 月 25 日

译自 Hello World

Hello World 项目是计算机编程中历史悠久的传统。这个简单的练习可以让你在学习新东西时快速入门。让我们开始使用 GitHub！

你将会学习如何：

• 创建与使用一个仓库

• 创建于管理一个分支

• 对文件做一些修改，将它们提交并推送到 GitHub

• 发起并合并一个拉取请求

最后更新：2016 年 4 月 7 日

译自 Understanding the GitHub flow

GitHub 工作流是一个基于分支的轻量级工作流，它支持定期进行部署的团队和项目。本指南将介绍 GitHub 工作流如何以及为何起作用。

最后更新：2017 年 11 月 30 日

部署

有了 GitHub，你可以在合并到 master 之前使用某分支部署，进行生产环境的最终测试。

一旦你的请求被评审并且分支通过了测试，你就可以部署更改以在生产环境中验证它们。如果你的分支导致某些问题，你可以通过部署现有的 master 分支到生产环境中来回滚它。

仅仅因为你对项目做了改变并不意味着你应该停下来！查看其他指南，了解如何为其他项目做出贡献或完善你自己的项目工作方式：

• GitHub 工作流

• 为开源做贡献

你可能会做的第一件事是删除首页的默认标题，并向其添加更友好的信息。由于这是一个非常简单的更改——而且是第一次修改——在默认分支 master 上进行更改就可以了。

通过在 Code 选项卡中导航到 _config.yml 文件。你可以单击铅笔图标来编辑文件。

目前你的网站没有设置标题，所以我们回到之前的仓库中。我将把“title: Welcome to the Octocat’s homepage!”这一行添加到该文件中。除了要注意自己的用户名，可以随意执行相同的操作。

在这个标题下，你可以添加有关页面用途的信息，并描述你希望用户在这里做些什么。我要将我自己的设置为“将此网站加入书签以关注我的项目更新”。

默认情况下，每次有新的 时，Zenodo 都会存档你的 GitHub 仓库。要对此进行测试，请回到主仓库视图，然后单击 releases 标题项。

除非你之前已为此仓库发布了版本，否则系统会要求你创建新版本。继续单击此按钮并填写新的发布表单。

如果这是你的代码的第一个版本，那么你应该给它一个版本号 v1.0.0。填写发行说明，然后单击 Publish release 按钮。

发布新版本将触发 Zenodo 归档你的仓库。你可以通过单击 Zenodo 配置文件中的 Upload 选项卡来确认此过程已发生。你应该会在右侧面板中看到新的上传内容。

一旦一个拉取请求被发起，评审你所做的更改的人员或团队可能会有问题或意见。也许是编码风格与项目指南不符，更改缺少单元测试，或者一切看起来都很棒，符合要求。拉取请求旨在鼓励和记录此类对话。

你还可以根据相关提交的讨论和反馈继续推送到相应分支。如果有人指出你忘记执行某些操作或代码中存在错误，则可以在分支中修复它并推送更改。GitHub 将在统一的拉取请求视图中显示你的新提交以及可能收到的任何其他反馈。

拉取请求评论是以 Markdown 格式编写的，因此你可以嵌入图片和表情符号，使用预格式化的文本块和其他轻量级格式。

仓库是 GitHub 最基本的元素。它们最容易被想象为你项目的文件夹。创建 DOI 的第一步是选择要在 Zenodo 中存档的仓库。 为此，请转到你的个人主页，然后单击 Repositories 选项卡。

**重要信息！**确保通过在仓库中包含许可证来告诉人们如何重用你的工作成果。 如果你不知道哪种许可证适合你，请查看 。

GitHub 是用于版本控制和协作的代码托管平台。它可以让你和其他人在任何地方协同工作。

本教程讲解一些 GitHub 基本知识，如_仓库_，分支，提交_和_拉取请求。你将创建自己的 Hello World 仓库并学习 GitHub 的拉取请求工作流，这是一种流行的创建和审查代码的方法。

无需写代码

要完成本教程，你需要一个 和互联网。你不需要知道如何写代码，如何使用命令行或安装 Git（GitHub 正是基于这个版本控制软件开发）。

提示：在单独的浏览器窗口（或标签页）中打开本指南，以便可以一边看本教程一边实践。

译自

Markdown 是一种轻量级且易用的语法，用于在 GitHub 平台上设置所有形式的书写样式。

你将学习的：

• Markdown 格式如何使样式化协作编辑变得简单

译自

随着越来越多的人加入 GitHub，每天都有新的项目增加，跟上所有项目可能会很困难。不过，可以通过关注用户和查看仓库，通过给项目加星或使用探索板块查找新人和新项目等轻松有趣的方式来保持对它们的关注。

最后更新：2018 年 5 月 17 日

译自

GitHub Pages 是通过 GitHub 发布的公共网页托管服务。最方便的方式是使用 Jekyll Theme Chooser 来加载已有的主题。之后，你可以通过 Web 或本地计算机远程修改 GitHub Pages 的内容和样式。

最后更新：2013 年 12 月 1 日

要复刻 Spoon-Knife 仓库，单击仓库标题中的 Fork 按钮。

坐下来感受复刻的魔法。完成后，你将被带到 Spoon-Knife 仓库的副本。

继续使用你喜欢的文本编辑器（如 ）对项目进行一些更改。例如，你可以更改 index.html 中的文本来添加你的 GitHub 用户名。

当你准备好提交更改时，先暂存再提交更改。

现在在本地暂存和提交更改是否难度太高了？ 的互动教程，以帮助你了解更多信息。

现在，你基本上相当于告诉 Git，“好的，我已经做了我的更改快照！”你可以继续做更多更改，并做更多提交快照。当你准备好将更改推送到 GitHub.com 时，就将更改推送到远程仓库。

GitHub 上的每个仓库都附带一个 wiki。创建仓库后，你可以通过侧栏导航设置包含的 wiki。启用 wiki 只需单击 wiki 按钮并创建第一页即可。

在使用 GitHub 一段时间后，你可能会希望自己能为他人的项目做点什么。或者，你可能希望将某人的项目作为你自己项目的起点。这个过程称为_复刻_。

创建“复刻”是创建他人项目的个人副本的过程。复刻充当原始仓库和你个人副本之间的桥梁。你可以提交_拉取请求_，通过向原始项目提交更改来帮助改善他人的项目。复刻是 GitHub 社交编码的核心。

在本教程中，我们将使用 项目（一个托管在 GitHub.com 上的测试仓库），可以让你测试拉取请求的工作流。

在 Zenodo 为你的仓库发布 DOI 之前，你需要提供刚刚存档的 GitHub 仓库的信息。

一旦你对软件的描述感到满意，请单击 Zenodo 表单底部的 Publish 按钮，于是，你刚刚为你的 GitHub 仓库创建了一个新的 DOI！

_仓库_或 Git 项目 包含与项目关联的整个文件与文件夹集合，以及每个文件的修改历史记录。文件历史记录呈现为被称作_提交_的快照，并且提交是以链接列表关系的方式存在的，并且可以组织成被称为_分支_的多个开发版本。由于 Git 是 DVCS，因此仓库是自包含单元，拥有仓库副本的任何人都可以访问整个代码库及其历史记录。使用命令行或其他易用的接口，git 仓库还允许：与历史记录、克隆、创建分支、提交、合并和比较不同代码版本之间的变更等进行交互。

在仓库中工作可以保持开发项目的组织和保护情况。这可以鼓励开发人员修复错误或创建新功能，而不必担心会破坏主线开发工作。Git 通过使用主题分支来实现这一点：历史记录中提交的轻量级指针可以轻松创建并在不再需要时弃用。

通过像 GitHub 这样的平台，Git 还为项目透明度和协作提供了更多机会。公共仓库可帮助团队协同工作，以构建最佳的产品。

译自 Making Your Code Citable

数字对象标识符（DOI）是学术引用和度量系统的支柱。如果你是一名编写软件的研究人员，本指南将向你展示如何通过归档 GitHub 仓库并使用数据存档工具Zenodo 分配 DOI，来使你在 GitHub 上分享的工作成果可引用化成为可能。

高级提示：本教程面向希望在学术文献中引用 GitHub 仓库的研究人员。如果你已经设置了 GitHub 仓库，则可以在不安装任何特殊软件的情况下完成本教程。如果你尚未在 GitHub 上创建过项目，请先 上传你的工作成果 到仓库。

最后更新：2016 年 10 月

译自 Documenting your projects on GitHub

良好的文档是任何项目成功的关键。使文档可访问让人们能够了解项目；使更新变得容易以确保文档贴近项目。

项目文档的两种常用组织方法是 _README 文件_和 wikis：

• README 文件是其他用户更快速，更简单地了解你的工作的方法。

• GitHub 上的 wikis 可帮助你以有用的方式提供项目的详细信息。

在你的项目中至少有一个 README 是个好主意，因为这是许多人第一次找到你的工作成果时会读到的东西。

最后更新：2016 年 7 月 15 日

你已经成功复刻了 Spoon-Knife 仓库，但到目前为止，它只存在于 GitHub 上。为了能够处理项目，你需要将其克隆到自己的计算机上。

如果你正在使用 GitHub 桌面版，这个过程轻而易举。在 Spoon-Knife 的复刻仓库上，在右侧栏单击 Clone or Download。如何克隆取决于你自己。可选的方式是 使用命令行克隆，或 使用 GitHub Desktop 克隆。

译自 Forking Projects

有没有在 GitHub 上找到一个你想要参与的项目？了解如何使用复刻来做贡献。

最后更新：2017 年 11 月 30 日

在“Issues”部分之外，还有另外两个页面可帮助汇总整个仓库以及跨所有仓库中的问题。

Issues 仪表板

如果你正在寻找跨多个项目的更广泛的所有 issue 列表，Issues 仪表板是一个很好的工具。仪表板与 issues 部分的工作方式非常相似，但收集问题的方式不同：

• 你拥有和协作的仓库中的所有 issues

• 指派给你的 issues

• 你创建的 issues

如果你使用了组织，则每个组织都有自己的“Issues”仪表板，用于分隔组织内的问题。

每个仓库下面都有一个名为 Pulse 的部分 —— Pulse 是过去一周（或一天，或过去 3 个月，诸如此类）在仓库中发生的所有事件的快照。

在你离开项目并且在观看仓库时不希望提供通知，这是一个很好的跟进仓库的方式。

分支创建后，是时候做一些改变了。无论何时添加，编辑或删除文件，都要进行提交（Commit），将它们添加到分支中。添加提交的操作使得你可以在处理功能分支时跟踪进度。

提交还会创建一份透明的工作历史记录，其他人可以遵循这些记录来了解你的工作内容及变更原因。每个提交都有一个关联的提交消息，用于解释为什么做了特定的更改。此外，每个提交都被视为一个独立的变更单位。这样，一旦发现错误，或者你决定朝另一个方向进行，就可以回滚更改。

高级技巧

提交消息很重要，特别是当 Git 已跟踪你的更改，并在它们被推送到服务器后展示出来。通过编写明确的提交消息，你可以让其他人更轻松地跟进并提供反馈意见。

仓库通常用于组织单个项目。仓库可以包含文件夹和文件，图像，视频，电子表格和数据集——你的项目需要的任何内容。我们建议包括一个 README，或者一个包含项目信息的文件。GitHub 可以在创建新仓库的同时方便地添加一个信息文件。它还提供其他常见选项，例如许可证文件。

你的 hello-world 仓库可以成为一个你想存放点子，资源，甚至与其他人分享和讨论事物的地方。

创建一个新仓库

1. 在右上角，你头像的旁边，点击 + 号图标然后选择 New repository。

2. 仓库命名为hello-world。

3. 为仓库写简介。

4. 选择 Initialize this repository with a README（使用一个 README 文件初始化此仓库）。

点击 Create repository。

在某些时候，你可能希望了解特定项目的最新信息。这类似于关注一个人，除了重点仅限于项目仓库中的事件。你可以选择通过邮件发送此仓库的通知，也可以通过 配置你的设置 在 Web 上查看。典型的通知是对拉取请求或 issue 的评论，甚至只是仓库中任何位置的评论。

我们的朋友八爪猫有一个名为 Hello World 的仓库，我们来看看。

进入仓库页面后，你会注意到页面顶部有一个“watch”按钮。点击它。

恭喜！ 现在你查看了 Hello World 仓库。如果八爪猫对其进行更新，你将看到仪表板中发生的情况或收到通知。

README 文件通常遵循一种格式，以便尽快将开发人员定位到项目最重要的地方。

• 项目名称：你项目的名称是人们在向下滚动到 README 时会看到的第一件事，它是在创建 README 文件时被包含在内的。

• 描述：接着就是你项目的描述。一个好的描述具备清楚、简短以及有重点等特点。它描述项目的重要性及其作用。

• 目录：可选地，包括目录以允许他人快速导航特别长或特别详细的 README 文件。

• 安装：安装是高效的 README 文件的下一部分。它告诉其他用户如何在本地安装项目。可选地，包含一个 gif 图片，以使其他人更清楚。

• 用法：下一部分是用法，你可以在其中指导其他人在安装项目后如何使用你的项目。这也是一个包含项目截图的好地方。

• 贡献：较大的项目通常有关于为其项目做贡献的部分，其中概述了贡献说明。有时，这是一个单独的文件。如果你有特定的贡献偏好，请解释它们，以便其他开发人员知道如何最好地为你的工作做出贡献。要了解更多有关如何帮助其他人贡献的信息，请查看为 的指南。

• 信用：包括一个信用部分，以突出显示并链接到该项目的作者。

• 许可证：最后，包含项目许可证的部分。有关选择许可证的更多信息，请查看 GitHub 的 ！

你的 README 文件应仅包含开发者开始使用和为你的项目做出贡献的必要信息。更长的文档适合使用 wiki，如下节所述。

译自 Mastering Issues

Issues 是跟踪项目任务、增强功能和错误的好方法。它们有点像电子邮件——除了可以与团队其他成员共享和讨论。大多数软件项目都有某种 bug 跟踪器。GitHub 的跟踪器称为 Issues，并且每个仓库都有相应的部分。

例如，让我们看一下 Bootstrap 的 Issues：

GitHub 的 issue 跟踪很特别，因为我们专注于协作，引用和良好的文本格式。GitHub 上典型的 issue 看起来有点像这样：

• 标题和描述表达了 issue 的全部内容。

• 彩色标签可帮助你对问题进行分类和过滤（就像邮件中的标签一样）。

• 里程碑就像 issues 的容器一样。这对将 issues 与特定功能或项目阶段关联起来非常有用（例如，Weekly Sprint 9/5-9/16 或 Shipping 1.0）。

• 一名被指派人负责在任意时间处理该 issue。

• 评论允许任何有权访问存储库的人提供反馈。

最后更新：2014 年 4 月 7 日

创建分支

当你在做一个项目时，你可能会在任何时间里有一堆不同的功能或想法——其中一些已经准备就绪，另一些则没有。分支的存在可以帮助你管理这些工作流。

在项目中创建分支时，你可以创建一个用于尝试新想法的环境。在新分支上所做的更改不会影响 master 分支，因此可以自由地进行实验和提交更改，完全可以放心，这个新分支直到被协作人评审后才会合并。

高级技巧

分支是 Git 的一个核心概念，整个 GitHub 工作流也是基于分支运作的。只有一条规则：master 分支中的内容始终都是可部署的。

因此，在处理功能或修复时，创建一个新的分支是十分重要的。分支名应该是描述性的（例如，refactor-authentication，user-content-cache-key，make-retina-avatars），以便其他人可以看出相应分支是在处理什么内容。

接下来，转到 Zenodo 并单击页面右上角的 Log in 按钮，这样你可以选择使用 GitHub 帐户登录。

Zenodo 会将你重定向回 GitHub，询求你同意共享你的邮件地址以及在你的仓库中配置 web 钩子 的权限。接着，单击 Authorize application，为 Zenodo 提供所需的权限。

重要信息！如果要归档属于 GitHub 上的组织的仓库，则需要确保组织管理员已启用对 Zenodo 应用程序的 第三方访问。

选择你想要归档的仓库

此时，你已授权 Zenodo 配置允许存档和 DOI 发布所需的仓库 web 钩子。要启用此功能，只需单击仓库（在本例中为 My-Awesome-Science-Software）旁边的 On 切换按钮。

**重要信息！**Zenodo 只能访问你的公共仓库，因此请确保你要存档的仓库是 。

一旦你收集了很多 issues，你可能会发现很难找到你关心的问题。里程碑，标签和被指派人是过滤和分类 issues 的强大功能。

你可以通过单击右侧边栏中的相应齿轮来更改或添加里程碑，被指派人和标签。

如果你没有看到编辑按钮，那是因为你没有编辑 issue 的权限。你可以要求仓库所有者将你添加为协作者以获取访问权限。

里程碑

里程碑是与项目，功能或时间段相对应的 issues 组。人们在软件开发中以多种不同的方式使用它们。 GitHub 上的一些里程碑示例包括：

• Beta 发布 —— 归档启动项目测试版之前需要修复的错误。这是一个确保你没有遗漏任何东西的好方法。

• 十月冲刺 —— 归档你希望在 10 月份处理的 issues。当有很多事情要做时，这是一个集中精力的好方法。

• 重新设计 —— 归档与重新设计项目相关的 issues。这是收集有关工作内容想法的好方法。

标签是组织不同类型 issues 的好方法。issues 可以包含任意数量的标签，你可以一次过滤一个或多个标签。

每个 issue 都可以有一个被指派人 —— 一个负责推动 issue 进展的人。通过 issue 顶部的灰色栏，以与里程碑相同的方式选择被指派人。

Markdown 是一种在网站上设置文字样式的方法。你可以控制文档的显示；将文字格式化为粗体或斜体、添加图像和创建列表是我们可以使用 Markdown 执行的一小部分操作。大多数情况下，Markdown 只是常规文本，其中包含一些非字母字符，如 # 或 *。

在 GitHub 上的大多数地方你都可以使用 Markdown：

• Gists

• Issues 和拉取请求中的评论

• 在扩展名为 .md 或 .markdown 的文件中

更多相关信息请看 GitHub 帮助 中的“”。

通过 GitHub 创建新仓库 时，请选择“使用 README 文件初始化此仓库”，除非你计划导入已有仓库。

你的 README.md 文件现在可以在全新的仓库中进行编辑。你的项目名称位于其顶部，接着是你在创建仓库时选择包含的任何描述。README 文件很容易 在 GitHub 或本地修改。查看 精通 Markdown 指南，以了解有关如何在创建文件后修改文本的详细信息。

在每个页面的最顶部是一个搜索框，可搜索 issues。

你可以通过以下方式限定搜索范围：

• 关键字，例如，提及“侧边栏”的所有 issues

• 状态，例如，提及“侧边栏”的所有已关闭的 issues

• 被指派人，例如，

可以向你展示其他搜索方式：使用创建/更新日期，标签，作者，评论计数，仓库所有者等。

发起拉取请求

拉取请求会启动你所提交内容的讨论。因为它们与 Git 紧密结合，所以任何人都可以确切地知道如果他们接受你的请求，将会合并哪些更改。

你可以在开发过程中随时发起拉取请求：在很少或根本没有代码但希望分享一些截图或想法时，在你遇到困难并需要帮助或建议时，或者在你准备好让别人评审你的工作时。通过在拉取请求消息中使用 GitHub 的 @提醒 系统，你可以征询特定人员或团队的反馈，不管他们身处何处。

高级技巧

拉取请求对于贡献开源项目和管理对共享仓库的更改很有用。如果你使用的是 Fork & Pull 模式，拉取请求提供了一种方式来通知项目维护者什么是你所希望他们考虑的更改。如果你使用的是共享仓库模式，拉取请求则会在合并到 master 分支之前帮助启动代码评审和有关建议更改的对话。

最后，你已准备好对主项目进行更改！这是复刻别人项目的最后一步，可以说是最重要的一步。如果你做了一个你认为会对整个社区有益的改变，你一定要考虑回馈。

为此，请去你项目所在的 GitHub.com 仓库。对于这个例子是 https://www.github.com/<your_username>/Spoon-Knife。你将看到一个横幅，表明你最近推送了一个新分支，并且你可以将此分支“上游”提交到原始仓库：

单击 Compare and Pull Request 将转到讨论页面，你可以在其中输入标题和选填的说明。重要的是提供尽可能多的有用信息和理由，说明你_为什么_首先提出此拉取请求。项目所有者需要确定你的更改是否如你所想对所有人都有用。

当你准备好输入你的真诚论点时，请单击 Send pull request。完成了！

拉取请求是一个可供讨论的地方。在这个例子中，八爪猫非常繁忙，可能不会合并你的更改。对于其他项目，如果项目所有者拒绝你的拉取请求，或者要求提供其为何被发起的更多信息，请不要觉得被冒犯。甚至可能是项目所有者选择不合并你的拉取请求，这完全没问题。你的副本将是互联网上无足轻重的存在。但是谁知道呢——也许你从未见过的人会发现你的更改比原来的项目更有价值。分享一切！

你已成功复刻并向原仓库做出贡献。请继续做更多的贡献！

合并

现在你的更改已在生产中得到验证，现在是时候将代码合并到 master 分支中了。

一旦被合并后，拉取请求会保留代码更改的历史记录。因为它们是可搜索的，所以任何人都可以及时回头了解决策的原因和方式。

高级技巧

通过将某些关键字组织到拉取请求的文本中，你可以将 issues 与代码关联起来。合并拉取请求后，相关问题也将关闭。例如，输入短语 Closes #32 将关闭仓库中的第 32 个 issue。更多信息，请查看我们的帮助文档。

回到你的 Zenodo GitHub 页面，你现在应该看到你的仓库中列有一个闪亮的新徽章，显示你的新 DOI！

**高级提示：**如果你真的想炫耀，请右击有着灰色和蓝色的 DOI 图片，复制其 URL 并将其放在 GitHub 仓库的 README 中。

通过在 Zenodo 中启用存档，你可以在仓库中设置新的 web 钩子。单击仓库中的“设置”选项卡，然后单击左侧菜单中的“Webhooks”。你会看到如下图所示的内容，其中显示了一个配置为向 Zenodo 发送消息的新 web 钩子。

干得漂亮！你在非 master 分支中做了更改，现在可以发起一个_拉取请求_。

拉取请求是在 GitHub 上合作的核心。当你发起一个拉取请求，意味着你做出了更改而请求某人审核并提取你的贡献，并将其合并到他们的分支中。拉取请求会显示来自两个分支的_内容差异_。修改、新增和删减分别以绿色和红色显示。

即使是在代码完成之前提交，你也可以发起拉取请求并开始讨论。

通过在拉取请求消息中使用 GitHub 的 ，你可以询问特定人员或团队的反馈，无论他们是在大厅还是 10 个时区之外。

你甚至可以在自己的仓库中发起拉取请求并自行合并。在开展大型项目之前，这是学习 GitHub 工作流的好方法。

为 README 所做的修改发起一个拉取请求

后，创建一个新的仓库开始使用。

在新的仓库页面上，你需要为此仓库指定一个独特的名称来生成相应的网站。

网站的文件将存放在名为 username.github.io 的仓库中（其中“username”是你的实际 GitHub 用户名）。要开始设置你的网站，你需要打开“设置”选项卡。

在设置页面向下滚动，你将看到底部附近的 GitHub Pages 部分。单击 Choose a theme 按钮开始创建站点。

分支是同时在不同版本的仓库上工作的方式。

默认情况下，你的仓库有一个名为 master 的分支，它被认为是标准分支。在提交到 master 之前，我们使用其他分支进行试验和编辑。

当你从 master 创建分支时，相当于做了一个 master 的副本或快照，就像是位于和 master 同一个时间点一样。如果其他人更改了 master 分支，而此时你工作在自己的分支上，则可以拉取别人的更新。

要使用 Git，开发者用特定命令来复制、创建、更改和组合代码。这些命令可以直接从命令行执行，也可以使用 或 Git Kraken 等应用程序执行。以下是一些使用 Git 的常用命令：

• git init 初始化一个全新的 Git 仓库并开始跟踪相应目录。它在现有目录中添加了一个隐藏的子目录，其中包含版本控制所需的内部数据结构。

• git clone 创建已存在远端的项目的本地副本。克隆将会包括所有的项目文件、历史记录和分支。

以下是 Markdown 语法的概述，你可以在 GitHub.com 或你自己的文本文件中的任何位置使用它。

无序

有序

你已经完成了 GitHub 提供的一些最基本的社交互动，但不要就此止步！看看其他社交功能：

观星

如果你对朋友过去曾加星的某些仓库感兴趣，但你不再在仪表板上看到它，请转到你的 并跳转到其他用户！

发现仓库

在你查看、关注并在 GitHub 上为你喜欢的人和仓库加星后，请转到你的 页面，根据这些内容查看个性化仓库建议！

探索 / 时事通讯

干得漂亮！现在，你正在 readme-edits 分支的代码视图，该分支是 master 的副本。我们来做一些编辑。

在 GitHub，保存更改称为_提交_。每个提交都有一个关联的提交消息，该消息是解释为何进行特定更改的描述。提交消息可体现更改的历史记录，因此其他贡献者可以了解你已完成的工作和原因。

修改并提交更改

1. 点击 README.md 文件。

Wiki 页面支持使用以下自动语法高亮突出显示各种语言的代码：

Wiki 内容旨在轻松编辑。你可以在任何 wiki 页面通过单击右上角的 Edit 按钮来添加或更改内容。这可以打开 wiki 编辑器。

Wiki 页面可以用 支持的任何格式编写。使用编辑器中的下拉菜单，你可以选择 wiki 的格式，然后使用 wiki 工具栏在页面上创建和编写内容。Wikis 还为你提供了包含自定义页脚的选项，你可以在其中列出项目的联系人详细信息或许可证信息。

GitHub 会跟踪 wiki 中每个页面所做的更改。在页面标题下方，除了对页面进行提交的数量外，你还可以看到谁进行了最新的编辑。单击此信息将转到完整的页面历史记录，你可以在其中比较修订版本或查看详细的编辑列表。

GitHub Guides 的中文版 —— GitHub 使用指南(GitBook)

GitHub 用户点此进入 GitBook 开始阅读

目录

• GitHub 使用指南

Hello World

本书发布在 ，你可以访问 参与翻译，帮助我们修正翻译错误。

最后一步，是时候将你的更改结合在一起——将你 readme-edits 分支合并到 master 分支中。

1. 单击绿色按钮 Merge pull request 来将更改合并到 master 中。

2. 单击 Confirm merge。

3. 分支的更改合并后即可点击紫色块中的 Delete branch 按钮。

通过完成本教程，你已经学会了在 GitHub 创建项目并发出拉取请求！

你在本教程中完成的内容：

• 创建一个开源仓库

• 创建管理一个分支

• 修改一个文件并将变更提交到 GitHub

看一下你的 GitHub 个人页，你会看到新的 ！

想了解有关拉取请求功能的更多信息，我们建议你阅读 。你也可以访问 并参与开源项目。

提示：查看我们的其他 、 和 ，了解如何开始使用 GitHub 的更多信息。

什么是版本控制系统？

版本控制系统（或称 VCS）会跟踪人员和团队进行项目协作时的更改历史记录。随着项目的发展，团队可能会运行测试，修复错误并提交新代码，并确信任何版本都可以随时恢复。开发者可以查看项目历史记录以找出：

• 什么被修改了？

• 谁做了修改？

• 什么时候做的修改？

• 为什么需要修改？

Git 是普遍用于开源和商业软件开发的分布式版本控制系统（DVCS）的范例。DVCS 允许完全访问项目的每个文件、分支和迭代，并允许每个用户访问所有更改的完整且自包含的历史记录。与曾经流行的集中版本控制系统不同，像 Git 这样的DVCS 不需要与中央存储库的持续连接。开发者可以在任何地方工作，并可以从任何时区异步协作。

如果没有版本控制，团队成员将受到冗余任务、较慢的时间线和单个项目的多个副本的影响。为了消除不必要的工作，Git 和其他 VCS 为每个贡献者提供了一个统一且一致的项目视图，展示了正在进行的工作。查看透明的变更历史，由谁创建，以及他们如何为项目的开发做出贡献，有助于团队成员在独立工作时保持一致。

根据最新的 ，超过 70％ 的开发者使用 Git，使其成为世界上使用最多的 VCS。Git 普遍用于开源和商业软件开发，为个人、团队和企业带来显着的好处。

• Git 允许开发者在一个仓库查看他们的变更、决策和任何项目进展的整个时间表。从他们访问项目历史的那一刻起，开发人员就拥有了解它并开始贡献所需的所有上下文。

• 开发者在各个时区工作。使用像 Git 这样的 DVCS，可以在保持源代码完整性的同时进行协作。使用分支，开发人员可以安全地更改生产代码。

• 使用 Git 的企业可以打破团队之间的沟通障碍，让他们专注于做最好的工作。此外，Git 使整个企业的专家能够在重大项目上进行协作。

GitHub 的一个重要功能是能够查看其他人正在做什么以及他们正在与谁联系。当你关注某人时，你将收到有关其 GitHub 活动的通知。关注朋友可以帮助你找到可能感兴趣的新项目和新人。你可以通过查看 个人仪表板 来查看你朋友感兴趣的内容，或者你可以通过查看 探索页面 了解 GitHub 社区中正在发生的事情。

第一步：选一个用户

试试关注 GitHub 上一些很酷的人：

cheshire137****

charliesome

benbalter

jeffrafter

muan

一旦你进入某人的主页，就可以点击“follow”按钮。

恭喜！你现在关注了一个朋友。

通过在问题中使用@提及 和引用，你可以通知其他 GitHub 用户和团队，并相互交叉关联问题。这些方法提供了一种灵活的方式，可以让合适的人员高效地解决问题，并且易于学习和使用。它们适用于 GitHub 上的所有文本字段 —— 它们是我们的文本格式化语法的一部分，称为 GitHub 版 Markdown。

如果你想了解更多信息，请查看 Mastering Markdown。

通知

通知是 GitHub 与你的 Issues 保持同步的方式。你可以使用它们来查找有关仓库的新 issues，或者只是知道某人何时需要你的输入才能继续处理 issue。

有两种方法可以接收通知：通过邮件和 web。你可以在设置中配置接收通知的方式。如果你预计收到大量通知，我们建议你接收所参与项目的 web + 邮件通知，以及所看过项目的 web 通知。

通过这些设置，当人们特别提到你时，你会收到邮件，接着就可以访问基于 Web 的界面及时了解你感兴趣的仓库。

你可以通过界面访问你的所有通知。此界面非常适合一次浏览许多通知并将其标记为已读或静默该通知线程。尝试使用键盘快捷键来加速你的工作流 —— 在页面上按 ? 查看可用的快捷键。

被静默的通知线程在你再次特别提及之前，将不再显示为未读。这是一个静默你不感兴趣的（可能是你不熟悉的某个子系统）通知线程的一个很好的策略。如果你将问题标记为已读，则它将保持这种状态，直到有人再次对该通知线程发表评论为止。

GitHub 还同步邮件通知的已读/未读状态 —— 如果你在邮件客户端中读取通知，它将在基于 Web 的界面中（如果你喜欢此功能，请确保允许你的邮件客户端显示图片）标记为已读。

@提及 是我们在 GitHub Issues 中引用其他 GitHub 用户的方式。在描述或 issue 的任何评论内，提及另一个 GitHub 用户的@用户名 以向他们发送通知。这与 Twitter 使用@提及 的方式非常相似。

我们喜欢使用 /cc 语法（ 抄送的缩写）来提及 issues 中的人：

It looks like the new widget form is broken on Safari. When I try and create the widget, Safari crashes. This is reproducible on 10.8, but not 10.9. Maybe a browser bug?

/cc @kneath @jresig

如果你知道要提及的特定用户，这种方法很有用，但很多时候我们在团队中工作但不知道谁可以帮助我们。@提及 也适用于 GitHub 组织内的团队。如果你在@acmeinc 组织下创建一个名为 browser-bugs 的团队，你可以使用@提及 提醒该团队：

/cc @acmeinc/browser-bugs

这将向 browser-bugs 团队的每个成员发送通知。

通常情况下，issues 取决于其他 issues，或者至少与它们有关，并且你希望将这两个 issues 关联起来。你可以通过输入主题标签和问题编号来引用 issues。

Hey @kneath, I think the problem started in #42

当你这样做时，我们将在 issue #42 中创建一个如下所示的事件：

另一个仓库中的 issue 只需在名称之前包含仓库名即可：kneath/example-project#42 。

使用 GitHub Issues 的一个更有趣的方法是直接从提交中引用 issue。在提交消息中包含 issue 编号即可。

通过在提交合并到 master 分支时将提交信息前缀写为 “Fixes”，“Fixed”，“Fix”，“Closes”，“Closed”，或“Close”，它也会自动关闭该问题。

通过引用，可以将正在完成的工作与正在跟踪的错误进行深入关联，这是增加项目历史可读性的好方法。

GitHub.com 使用自己版本的 Markdown 语法，该语法提供了一组额外的有用功能，其中许多功能可以更轻松地使用 GitHub.com 上的内容。

注意，GitHub 风味 Markdown 的某些功能仅在 Issues 和拉取请求的说明和注释中提供。这些包括@提及以及对 SHA-1 哈希、Issues 和拉取请求的引用。任务列表也可以在 Gist 评论和 Gist Markdown 文件中使用。

以下是如何使用 进行语法高亮的示例：

以下是没有语法高亮的 Python 代码示例：

如果你在 Issue 的第一条评论中包含任务列表，你将在问题列表中获得一个方便的进度指示器。 它也适用于拉取请求！

你可以通过组合单词列表并用连字符 - 分隔（第一行），然后用管道符 | 分隔每个列创建表格：

文本

使用 Markdown 可以很容易地给一些文字设置**粗体**，其他文字设置*斜体*。你甚至可以 [链接到谷歌](http://google.com)！

使用 Markdown 可以很容易地给一些文字设置粗体，其他文字设置_斜体_。你甚至可以 链接到谷歌！

列表

有时你想要有序列表：

1. 一
2. 二
3. 三

有时你想要突出要点：

* 使用星号开始一行
* 利润！

或者，

- 横杠也是可以的
- 如果还有下一级，在横杠或星号前输入两个空格：
  - 像这样
  - 还有这样

有时你想要有序列表：

1. 一

2. 二

3. 三

有时你想要突出要点：

• 使用星号开始一行

• 利润！

或者，

• 横杠也是可以的

• 如果还有下一级，在横杠或星号前输入两个空格：

  • 像这样

如果你想嵌入图片，可以这样做：

有时，使用不同级别的标题来组织文档是很有用的。用 # 开始作为标题。连续多个 ## 表示较小的标题。

你可以使用 # 到 ###### 六种不同大小的标题。

如果你想要引用他人的文字，使用 > 开头：

咖啡。有史以来最好的有机悬浮液……我用它击败了 Borg。

——Janeway 船长

if (isAwesome){ return true }

GitHub 还支持称为代码防护的东西，它允许多行而不缩进：

如果你想使用语法高亮，则写上语言类型：

GitHub 支持 Markdown 中的许多额外功能，可以帮助你引用链接别人。如果你想对某人发表评论，你可以在他们的名字前加上@符号：嘿 ——你的毛衣不错！

我必须承认，待办事项是我最喜欢的：

• 这是已完成的事项

• 这是未完成的事项

当你在 Issue 的第一条评论中包含任务列表时，你会在任务列表中看到一个有用的进度条。它也适用于拉取请求！

当然，emoji 也是支持的！

Issues 非常适合跟踪各种事情 —— GitHub 是一个轻松分享和协作解决问题的好地方。这是我们最爱的一些：

• 用于开源项目的 bug 跟踪器

• 请求食谱（也许你有一个很好的无麸质披萨面团配方？）

最后

现在祝贺你自己 —— 读起来还真不少！issue 管理是任何开发人员可以使用的最强大的工具之一。我想现在剩下的就是去修复错误。

GitHub 是如何融入 Git 的

GitHub 是一个 Git 托管仓库，它为开发人员提供工具，通过命令行功能、issues（线程化的讨论流程）、拉取请求、代码审查或在 GitHub 集市中使用一系列免费和收费应用程序来造就更好的代码。通过 GitHub 工作流等协作方式，拥有 1500 万开发者的社区以及拥有数百个集成功能的生态系统，GitHub 改变了软件的构建方式。

GitHub 是如何工作的

GitHub 直接将协作构建到开发过程中。工作流程被组织到仓库中，开发者可以在其中概述需求或发展方向并为团队成员预设期望。然后，使用 GitHub 工作流，开发者只需创建一个分支来处理更新，提交更改并保存它们，发起拉取请求以提出并讨论更改，并在所有人达成共识时合并拉取请求。

GitHub 工作流

GitHub 工作流是一个基于分支的轻量级工作流，围绕世界各地团队（包括我们的团队）使用的核心 Git 命令构建。

GitHub 工作流有六个步骤，每个步骤在实施时都有显著的好处：

1. **创建分支：**从规范部署分支（通常是 master 分支）创建的主题分支允许团队为许多并行工作做出贡献。特别是短时间存在的主题分支，可以使团队专注工作并快速发展。

2. **添加提交：**分支上的开发快照在项目历史中创建了安全，可恢复的时间点。

3. **发起拉取请求：**拉取请求公开项目的持续进展，并为透明的开发过程定下基基调。

4. **讨论并审查代码：**团队通过评论，测试和审查开放的拉取请求来参与代码审查。代码审查是开放与参与文化的核心。

5. **合并：**单击合并后，GitHub 会自动执行与本地“git merge”等效的操作。GitHub 还在合并的拉取请求中保留整个分支开发历史记录。

6. **部署：**团队可以选择最佳的发布周期或加入持续集成工具，并确保部署分支上的代码通过了稳健的工作流程的考验。

了解有关 GitHub 工作流更多信息

开发者可以在下面提供的资源中找到有关 GitHub 工作流的更多信息。

对于刚接触命令行的开发者，GitHub 培训团队已经整理了一系列 Git 命令的 来指导方向。有时候，一系列命令可以描绘出如何使用 Git 的景象：

示例：为现有仓库做贡献

例子：新建一个仓库并发布到 GitHub

首先，你需要在 GitHub 上创建一个新的仓库。你可以在我们的 中学习如何创建新的仓库。不要使用 README、.gitignore 或 License 文件来初始化仓库。这个空的仓库就只等着你的代码。

例子：向 GitHub 上的现有分支贡献

人们在 GitHub 上合作主要有两种方式：

1. 共享仓库

2. 与

使用_共享仓库_，个人和团队被明确指定为具有读取、写入或管理员访问权限的贡献者。这种简单的权限结构与受保护的分支和 Marketplace 等功能相结合，可以帮助团队在采用 GitHub 时快速进展。

对于开源项目或任何人都可以贡献的项目，管理个人权限可能具有挑战性，但是_复刻_与_拉取_模型允许任何可以查看项目的人做出贡献。复刻是开发者个人帐户下项目的副本。每个开发者都可以完全控制他们的分支，并可以自由地实现修复或新功能。在复刻中完成的工作要么保持独立，要么通过拉取请求合并回原始项目。在那里，维护人员可以在合并之前查看建议的更改。有关更多信息，请参阅 。

GitHub 团队创建了一个教育视频和指南库，以帮助用户继续充实他们的技能并构建更好的软件。

你可以通过选择右上角的 New Page 向 wiki 添加其他页面。默认情况下，你创建的每个页面都会自动包含在你的 wiki 侧边栏中，并按字母顺序列出。

你还可以通过单击 Add custom sidebar 链接来添加自定义侧边栏。自定义侧边栏的内容可以包括文本、图像和链接。

注意：名为“Home”的页面用作 wiki 的入口页面。如果缺少它，则会显示自动生成的目录。

如果你已熟悉命令行操作，则还可以在本地修改 wiki。查看 了解更多信息。