# GitHub 使用指南

[![stars](https://img.shields.io/github/stars/itechub/github-guides-zhcn.svg)](https://github.com/itechub/github-guides-zhcn) [![updated](https://img.shields.io/github/last-commit/itechub/github-guides-zhcn/master.svg?color=%23c16927\&label=updated)](https://github.com/itechub/github-guides-zhcn/commits/master)

[GitHub Guides](https://guides.github.com/) 的中文版 —— [GitHub 使用指南(GitBook)](https://itechub.gitbook.io/github-guides-zhcn/)

[GitHub 用户点此进入 GitBook 开始阅读](https://itechub.gitbook.io/github-guides-zhcn)

## 目录

* [GitHub 使用指南](/)

### Hello World

* [简介](/hello-world/intro)
* [什么是 GitHub？](/hello-world/about-github)
* [创建一个仓库](/hello-world/create-a-repository)
* [创建一个分支](/hello-world/create-a-branch)
* [修改并提交更改](/hello-world/make-a-commit)
* [发起拉取请求](/hello-world/open-a-pull-request)
* [合并拉取请求](/hello-world/merge-pull-request)

### 理解 GitHub 工作流

* [简介](/github-flow/intro)
* [创建分支](/github-flow/create-a-branch)
* [提交更改](/github-flow/add-commits)
* [发起拉取请求](/github-flow/open-a-pull-request)
* [讨论并评审代码](/github-flow/discuss-and-review)
* [部署](/github-flow/deploy)
* [合并](/github-flow/merge)

### GitHub Pages 入门

* [简介](/github-pages/intro)
* [创建你的网站](/github-pages/create-your-website)
* [做一些修改](/github-pages/making-changes)
* [下一步](/github-pages/next-steps)

### Git 手册

* [简介](/git-handbook/intro)
* [什么是版本控制系统？](/git-handbook/version-control-system)
* [什么是仓库？](/git-handbook/repositories)
* [Git 基础](/git-handbook/basic-git)
* [GitHub](/git-handbook/github)

### 复刻他人项目

* [简介](/forking-projects/intro)
* [为项目做贡献](/forking-projects/contributing-to-a-project)
* [复刻仓库](/forking-projects/fork-the-repository)
* [克隆你所复刻的项目](/forking-projects/clone-your-fork)
* [修改并推送](/forking-projects/making-and-pushing-changes)
* [发起拉取请求](/forking-projects/making-a-pull-request)

### 多多社交

* [简介](/be-social/intro)
* [关注一个朋友](/be-social/follow-a-friend)
* [查看一个项目仓库](/be-social/watch-a-project)
* [你可以做更多的事情](/be-social/more-things-you-can-do)

### 使代码可引用

* [简介](/making-your-code-citable/intro)
* [选择你的仓库](/making-your-code-citable/choose-your-repository)
* [登录 Zenodo](/making-your-code-citable/login-to-zenodo)
* [查看仓库设置](/making-your-code-citable/check-repo-settings)
* [发布新版本](/making-your-code-citable/create-a-new-release)
* [创建 DOI](/making-your-code-citable/minting-a-doi)
* [即将完成](/making-your-code-citable/finishing-up)

### 精通 Issues

* [简介](/mastering-issues/intro)
* [里程碑，标签和被指派人](/mastering-issues/milestones-labels-and-assignees)
* [通知，@提及 和引用](/mastering-issues/notifications-mentions-and-references)
* [搜索](/mastering-issues/search)
* [概述 & 报告](/mastering-issues/overviews-and-reports)
* [Issues 的其他用途](/mastering-issues/other-uses-for-issues)

### 精通 Markdown

* [简介](/mastering-markdown/intro)
* [什么是 Markdown?](/mastering-markdown/what-is-markdown)
* [例子](/mastering-markdown/examples)
* [语法指南](/mastering-markdown/syntax-guide)
* [GitHub 风味 Markdown](/mastering-markdown/gfm)

### 项目文档化

* [简介](/documenting-projects/intro)
* [创建你的 README](/documenting-projects/creating-your-readme)
* [格式化你的 README](/documenting-projects/formatting-your-readme)
* [创建你的 wiki](/documenting-projects/creating-your-wiki)
* [添加内容](/documenting-projects/adding-content)
* [添加页面](/documenting-projects/adding-pages)
* [语法高亮](/documenting-projects/syntax-highlighting)

## 参与翻译

本书发布在 [GitBook](https://itechub.gitbook.io/github-guides-zhcn)，你可以访问 [github-guides-zhcn (GitHub)](https://github.com/kvko/github-guides-zhcn) 参与翻译，帮助我们修正翻译错误。


# 简介

阅读时间：约 10 分钟

> *译自* [*Hello World*](https://guides.github.com/activities/hello-world/)

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

**你将会学习如何：**

* 创建与使用一个仓库
* 创建于管理一个分支
* 对文件做一些修改，将它们提交并推送到 GitHub
* 发起并合并一个拉取请求

> 最后更新：2016 年 4 月 7 日


# 什么是 GitHub？

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

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

**无需写代码**

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

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


# 创建一个仓库

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

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

#### 创建一个新仓库

1. 在右上角，你头像的旁边，点击 + 号图标然后选择 **New repository。**
2. 仓库命名为`hello-world`。
3. 为仓库写简介。
4. 选择 **Initialize this repository with a README（使用一个 README 文件初始化此仓库）**。

![创建一个新仓库](https://guides.github.com/activities/hello-world/create-new-repo.png)

点击 **Create repository**。


# 创建一个分支

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

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

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

该图显示了：

* `master` 分支
* 一个叫做 `feature`（因为我们在此分支上“开发功能”）的分支
* `feature` 在合并到 `master` 之前所经历的旅程

![分支创建与合并](https://guides.github.com/activities/hello-world/branching.png)

Have you ever saved different versions of a file? Something like:

你有没有保存过同一文件的不同版本？就像是：

* `story.txt`
* `story-joe-edit.txt`
* `story-joe-edit-reviewed.txt`

分支在 GitHub 仓库中实现了类似的目标。

在 GitHub，我们的开发者、作家和设计师使用分支来保持错误修复和功能开发与 `master`（生产）分支分开。当更改准备就绪时，他们才会将自己的分支合并到 `master`。

#### 创建一个新分支

1. 前往你的新仓库 `hello-world`。
2. 点击文件列表顶端显示了 **branch: master** 的下拉列表。
3. 往新建文本框里输入一个分支名，`readme-edits`。
4. 选择蓝色的 **Create branch** 块或按“Enter”键。

![从 master 创建一个新分支](https://guides.github.com/activities/hello-world/readme-edits.gif)

现在你有两个分支，`master`和`readme-edits`。它们看起来完全一样，但很快就是不是了！接下来，我们将更改添加到这个新分支。


# 修改并提交更改

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

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

**修改并提交更改**

1. 点击 `README.md` 文件。
2. 点击文件右上角的铅笔图标进行编辑。
3. 在编辑器中，写点关于你自己的东西。
4. 写一条提交消息来描述你的变更。
5. 点击 **Commit changes** 按钮。

![提交](https://guides.github.com/activities/hello-world/commit.png)

这些更改只会影响 `readme-edits` 分支上的 README 文件，因此现在这个分支包含的内容与 `master` 不同。


# 发起拉取请求

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

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

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

通过在拉取请求消息中使用 GitHub 的 [@提及 系统](https://help.github.com/articles/about-writing-and-formatting-on-github/#text-formatting-toolbar)，你可以询问特定人员或团队的反馈，无论他们是在大厅还是 10 个时区之外。

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

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

*点击图片可放大查看*

| 步骤                                                                        | 截图                                                                                                                                               |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| 单击 **Pull Request** 选项卡，然后从其页面中，单击 **New pull request** 按钮。               | [![pr-tab](https://guides.github.com/activities/hello-world/pr-tab.gif)](https://guides.github.com/activities/hello-world/pr-tab.gif)            |
| 在 **Example Comparisons** 块中，选择你创建的`readme-edits` 分支，与 `master`（即原始分支）比较。 | [![branch](https://guides.github.com/activities/hello-world/pick-branch.png)](https://guides.github.com/activities/hello-world/pick-branch.png)  |
| 在“比较”页面上查看差异中的更改，确保它们是你想要提交的内容。                                           | [![diff](https://guides.github.com/activities/hello-world/diff.png)](https://guides.github.com/activities/hello-world/diff.png)                  |
| 如果你对要提交的更改感到满意，则单击绿色的 **Create Pull Request** 按钮。                         | [![create-pull](https://guides.github.com/activities/hello-world/create-pr.png)](https://guides.github.com/activities/hello-world/create-pr.png) |
| 为你的拉取请求填写标题与更改的简要说明。                                                      | [![pr-form](https://guides.github.com/activities/hello-world/pr-form.png)](https://guides.github.com/activities/hello-world/pr-form.png)         |

完成消息填写后，单击 **Create pull request**！

> \*\*提示：\*\*你可以在评论和拉取请求消息中使用 [emoji](https://help.github.com/articles/basic-writing-and-formatting-syntax/#using-emoji) 和 [图片拖放](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/)。


# 合并拉取请求

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

1. 单击绿色按钮 **Merge pull request** 来将更改合并到 `master` 中。
2. 单击 **Confirm merge**。
3. 分支的更改合并后即可点击紫色块中的 **Delete branch** 按钮。

![合并](https://guides.github.com/activities/hello-world/merge-button.png)

![删除](/files/-Lhu1NRhLzC9KC9V2RWe)

#### 庆祝一下！

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

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

* 创建一个开源仓库
* 创建管理一个分支
* 修改一个文件并将变更提交到 GitHub
* 发起并合并一个拉取请求

看一下你的 GitHub 个人页，你会看到新的 [贡献方块](https://help.github.com/articles/viewing-contributions)！

想了解有关拉取请求功能的更多信息，我们建议你阅读 [GitHub 工作流](https://itechub.gitbook.io/github-guides-zhcn/github-flow/intro)。你也可以访问 [探索 GitHub](http://github.com/explore) 并参与开源项目。

> 提示：查看我们的其他 [指南](http://guides.github.com/)、[YouTube 频道](http://youtube.com/githubguides) 和 [按需培训](https://services.github.com/on-demand/)，了解如何开始使用 GitHub 的更多信息。


# 简介

阅读时间：约 5 分钟

> *译自* [*Understanding the GitHub flow*](https://guides.github.com/introduction/flow/)

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

> 最后更新：2017 年 11 月 30 日


# 创建分支

![](/files/-LezYaslXG3gWAr_gh8A)

## 创建分支

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

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

### 高级技巧

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

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


# 提交更改

![Add commits](/files/-LezYZFww-OCVW4hROK1)

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

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

## **高级技巧**

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


# 发起拉取请求

![](/files/-LezYZahA-KX38kiu0uR)

## 发起拉取请求

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

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

### **高级技巧**

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


# 讨论并评审代码

![](/files/-LezY_rdJjw8Wc8pjqkz)

## 讨论并评审代码

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

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

### **高级技巧**

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


# 部署

![](/files/-LezY_-4HTKRI8b2KDMr)

## 部署

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

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


# 合并

![](/files/-LezYa5sKRPCguorY6Zr)

## 合并

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

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

### **高级技巧**

通过将某些关键字组织到拉取请求的文本中，你可以将 issues 与代码关联起来。合并拉取请求后，相关问题也将关闭。例如，输入短语 `Closes #32` 将关闭仓库中的第 32 个 issue。更多信息，请查看我们的[帮助文档](https://help.github.com/articles/closing-issues-using-keywords/)。


# 简介

阅读时间：约 10 分钟

> *译自* [*Getting Started with GitHub Pages*](https://guides.github.com/features/pages/)

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

![GitHub Pages 首页](https://guides.github.com/features/pages/pages-home-page.png)

> 最后更新：2013 年 12 月 1 日


# 创建你的网站

[登录](https://github.com/login) 后，创建一个新的仓库开始使用。

![新建仓库按钮](https://guides.github.com/features/pages/create-new-repo-button.png)

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

![新仓库页面](https://guides.github.com/features/pages/create-new-repo-screen.png)

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

![设置选项卡](https://guides.github.com/features/pages/repo-settings.png)

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

![打开主题选择页面](https://guides.github.com/features/pages/launch-theme-chooser.png)

单击该按钮后，你将打开主题选择页面。在页面顶部的轮播图中可看到几个主题选项。单击图像可预览主题。选择其中一个后，单击右侧的 **Select theme**。以后想改变主题也很方便，所以如果现在不确定，随便选择一个就好了。

![选择主题](https://guides.github.com/features/pages/theme-chooser.png)

你可以在这里编写自己的内容（如果你愿意也可以暂时保留默认内容）。

![代码编辑器](https://guides.github.com/features/pages/code-editor.png)

完成编辑后，向下滚动到页面底部，然后单击 **Commit changes**。

![提交编辑](https://guides.github.com/features/pages/commit-edits.png)

GitHub 将负责所有工作，将访问者引导至 `username.github.io` 查看你的新网站。这个过程可能需要 10 分钟。过一段时间后，你可以在浏览器中进入你的网站看看！


# 做一些修改

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

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

![编辑页](https://guides.github.com/features/pages/edit-file.png)

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

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

![修改标题与描述](https://guides.github.com/features/pages/change-title-description.png)

完成这一小改动后，滚动到页面底部进行第二次提交。你有两个地方可以写关于此次更改的信息：主题和详细描述。详细描述是可选的，让我们在主题中留下描述性信息。

完成后，单击“**Commit changes**”，你的更新将在几秒钟后生效！

![尽量描述清楚](https://guides.github.com/features/pages/commit-messages-matter.png)


# 下一步

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

* [GitHub 工作流](https://itechub.gitbook.io/github-guides-zhcn/github-flow/intro)
* [为开源做贡献](https://opensource.guide/how-to-contribute/)
* [精通 Markdown](https://itechub.gitbook.io/github-guides-zhcn/mastering-markdown/intro)


# 简介

阅读时间：约 10 分钟

> *译自* [*Git Handbook*](https://guides.github.com/introduction/git-handbook/)

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

> 最后更新：2017 年 9 月 25 日


# 什么是版本控制系统？

#### 什么是版本控制系统？

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

* 什么被修改了？
* 谁做了修改？
* 什么时候做的修改？
* 为什么需要修改？

#### 什么是分布式版本控制系统？

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

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

#### 为什么选择 Git？

根据最新的 [Stack Overflow 开发者调查](https://insights.stackoverflow.com/survey/2017#technology)，超过 70％ 的开发者使用 Git，使其成为世界上使用最多的 VCS。Git 普遍用于开源和商业软件开发，为个人、团队和企业带来**显着的好处**。

* Git 允许开发者在一个仓库查看他们的变更、决策和任何项目进展的整个时间表。从他们访问项目历史的那一刻起，开发人员就拥有了解它并开始贡献所需的所有上下文。
* 开发者在各个时区工作。使用像 Git 这样的 DVCS，可以在保持源代码完整性的同时进行协作。使用分支，开发人员可以安全地更改生产代码。
* 使用 Git 的企业可以打破团队之间的沟通障碍，让他们专注于做最好的工作。此外，Git 使整个企业的专家能够在重大项目上进行协作。


# 什么是仓库？

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

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

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


# Git 基础

#### Git 基础命令

要使用 Git，开发者用特定命令来复制、创建、更改和组合代码。这些命令可以直接从命令行执行，也可以使用 [GitHub 桌面版](https://desktop.github.com/) 或 Git Kraken 等应用程序执行。以下是一些使用 Git 的常用命令：

* `git init` 初始化一个全新的 Git 仓库并开始跟踪相应目录。它在现有目录中添加了一个隐藏的子目录，其中包含版本控制所需的内部数据结构。
* `git clone` 创建已存在远端的项目的本地副本。克隆将会包括所有的项目文件、历史记录和分支。
* `git add` 暂存修改。Git 跟踪开发者对代码库的更改，但是有必要先暂存并拍摄更改的快照以将其包含在项目的历史记录中。此命令执行暂存功能，这是两步过程的第一部分。任何已暂存的更改都将成为下一个快照的一部分，并成为项目历史的一部分。分别执行暂存和提交可使开发者完全控制其项目的历史记录，而无需更改其编码和工作习惯。
* `git commit` 将快照保存到项目历史记录中并完成更改跟踪过程。简而言之，提交功能就像拍照一样。任何使用 `git add` 暂存的内容都将成为 `git commit` 快照的一部分。
* `git status` 显示更改的跟踪状态，有未跟踪、已修改和已暂存三种。
* `git branch` 显示在本地工作的分支。
* `git merge` 将各个开发分支合并在一起。此命令通常用于将两个不同分支上的更改合并起来。例如，当开发者想要把来自功能分支的更改合并到主分支以进行部署时，他们就可以使用 `git merge`。
* `git pull` 使用远程对应的内容更新本地仓库。如果队友已经对远程分支提交了更新，开发者便可以使用此命令，并且他们希望在本地环境中反映这些更改。
* `git push` 使用本地提交到分支的更改来更新远程仓库。

从 [Git 命令完整参考指南](https://git-scm.com/docs) 中了解更多信息。

**探索更多 Git 命令**

有关 Git 实践的详细介绍，下面的视频展示了如何充分利用 Git 命令。

* [在本地设备工作](https://www.youtube.com/watch?v=rBbbOouhI-s\&index=2\&list=PLg7s6cbtAD17Gw5u8644bgKhgRLiJXdX4)
* [`git status`](https://www.youtube.com/watch?v=SxmveNrZb5k\&list=PLg7s6cbtAD17Gw5u8644bgKhgRLiJXdX4\&index=3)
* [两步提交](https://www.youtube.com/watch?v=Vb0Ghkkc2hk\&index=4\&list=PLg7s6cbtAD17Gw5u8644bgKhgRLiJXdX4)
* [`git pull` 与 `git push`](https://www.youtube.com/watch?v=-uQHV9GOA0w\&index=5\&list=PLg7s6cbtAD17Gw5u8644bgKhgRLiJXdX4)


# GitHub

#### 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 工作流的更多信息。

* [指南](https://itechub.gitbook.io/github-guides-zhcn/github-flow/intro)
* [GitHub 工作流演示视频](https://www.youtube.com/watch?v=47E-jcuQz5c\&index=1\&list=PLg7s6cbtAD17Gw5u8644bgKhgRLiJXdX4)

#### GitHub 与命令行

对于刚接触命令行的开发者，GitHub 培训团队已经整理了一系列 Git 命令的 [教程](https://help.github.com/articles/git-and-github-learning-resources/) 来指导方向。有时候，一系列命令可以描绘出如何使用 Git 的景象：

**示例：为现有仓库做贡献**

```
# 从 GitHub.com 把仓库下载到我们的设备上
git clone https://github.com/me/repo.git

# 切换到 `repo` 目录
cd repo

# 创建一个新分支以存储修改
git branch my-branch

# 切换到该分支（开发主题）
git checkout my-branch

# 做一些修改，例如使用文本编辑器编辑 `file1.md` 和 `file2.md`

# 暂存已修改的文件
git add file1.md file2.md

# 为暂存的文件（任何被添加入暂存区的文件）做一个快照
git commit -m "my snapshot"

# 将更改推送至 github
git push --set-upstream origin my-branch
```

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

首先，你需要在 GitHub 上创建一个新的仓库。你可以在我们的 [Hello World 指南](http://itechub.gitbook.io/github-guides-zhcn/hello-world/create-a-repository) 中学习如何创建新的仓库。**不要**使用 README、.gitignore 或 License 文件来初始化仓库。这个空的仓库就只等着你的代码。

```
# 创建一个新目录，并使用 git 特定函数来初始化它
git init my-repo

# 切换到 `my-repo` 目录
cd my-repo

# 创建项目的第一个文件
touch README.md

# git 还没开始跟踪此文件，先暂存它
git add README.md

# 为暂存区拍一个快照
git commit -m "add README to initial commit"

# 为仓库设置 github 远程仓库地址
git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git

# 将更改推送至 github
git push --set-upstream origin master
```

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

```
# 假设：机器上已经存在一个名为 `repo` 的项目，并且自上次在本地进行更改后，有新的分支已被推送到 GitHub.com

# 切换到 `repo` 目录
cd repo

# 更新所有远程跟踪分支和当前所在的分支
git pull

# 切换到已有的 `feature-a` 分支
git checkout feature-a

# 做一些修改，例如：使用编辑器编辑 `file1.md` 文件

# 暂存修改的文件
git add file1.md

# 为暂存区做一次快照
git commit -m "edit file1"

# 将更改推送至 github
git push
```

#### 协作开发的模型

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

1. 共享仓库
2. [复刻](https://help.github.com/en/articles/about-forks) 与 [拉取](https://help.github.com/en/articles/about-pull-requests)

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

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

#### 按自己的节奏学习

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

* [探索入门项目](https://github.com/showcases/great-for-new-contributors)
* [GitHub 指引视频](https://youtube.com/githubguides)
* [GitHub 按需学习](https://services.github.com/on-demand/)
* [GitHub 学习指南](https://guides.github.com/)
* [GitHub 学习资源](https://services.github.com/resources/)


# 简介

阅读时间：约 4 分钟

> *译自* [*Forking Projects*](https://guides.github.com/activities/forking/)

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

> 最后更新：2017 年 11 月 30 日


# 为项目做贡献

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

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

在本教程中，我们将使用 [Spoon-Knife](https://github.com/octocat/Spoon-Knife) 项目（一个托管在 GitHub.com 上的测试仓库），可以让你测试拉取请求的工作流。


# 复刻仓库

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

![一个仓库的分叉按钮](https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png)

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


# 克隆你所复刻的项目

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

如果你正在使用 [GitHub 桌面版](https://desktop.github.com/)，这个过程轻而易举。在 Spoon-Knife 的复刻仓库上，在右侧栏单击 **Clone or Download**。如何克隆取决于你自己。可选的方式是 [使用命令行克隆](https://services.github.com/on-demand/github-cli/clone-repo-cli)，或 [使用 GitHub Desktop 克隆](https://services.github.com/on-demand/github-desktop/clone-repository-github-desktop)。


# 修改并推送

继续使用你喜欢的文本编辑器（如 [Atom](https://atom.io/)）对项目进行一些更改。例如，你可以更改 *index.html* 中的文本来添加你的 GitHub 用户名。

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

> 现在在本地暂存和提交更改是否难度太高了？[查看这个按需培训](https://services.github.com/on-demand/) 的互动教程，以帮助你了解更多信息。

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


# 发起拉取请求

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

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

![最近推送分支的横幅](https://github-images.s3.amazonaws.com/help/pull_requests/recently_pushed_branch.png)

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

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

![发起拉取请求按钮](https://github-images.s3.amazonaws.com/help/pull_requests/pullrequest-send.png)

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

### 欢呼！

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


# 简介

阅读时间：约 5 分钟

> *译自* [*Be Social*](https://guides.github.com/activities/socialize/)

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

> 最后更新：2018 年 5 月 17 日


# 关注一个朋友

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

#### 第一步：选一个用户

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

[![cheshire137](https://avatars3.githubusercontent.com/cheshire137?v=3\&s=86)**cheshire137**](https://github.com/cheshire137)\*\*\*\*

[![charliesome](https://avatars3.githubusercontent.com/charliesome?v=3\&s=86)**charliesome**](https://github.com/charliesome)

[![benbalter](https://avatars2.githubusercontent.com/benbalter?v=3\&s=86)**benbalter**](https://github.com/benbalter)

[![jeffrafter](https://avatars2.githubusercontent.com/jeffrafter?v=3\&s=86)**jeffrafter**](https://github.com/jeffrafter)

[![muan](https://avatars3.githubusercontent.com/muan?v=3\&s=86)**muan**](https://github.com/muan)

[![pifafu](https://avatars3.githubusercontent.com/pifafu?v=3\&s=86)**pifafu**](https://github.com/pifafu)

#### 第二步：关注该用户

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

![关注用户按钮](https://github-images.s3.amazonaws.com/help/profile/follow-user-button.png)

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


# 查看一个项目仓库

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

我们的朋友八爪猫有一个名为 [Hello World](https://github.com/octocat/Hello-World) 的仓库，我们来看看。

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

![查看仓库按钮](https://github-images.s3.amazonaws.com/help/repository/repo-actions-watch.png)

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


# 你可以做更多的事情

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

**观星**

如果你对朋友过去曾加星的某些仓库感兴趣，但你不再在仪表板上看到它，请转到你的 [星标页面](https://github.com/stars) 并跳转到其他用户！

![转到其他用户主页](https://guides.github.com/activities/socialize/jump-to-another-user.png)

**发现仓库**

在你查看、关注并在 GitHub 上为你喜欢的人和仓库加星后，请转到你的 [发现仓库](https://github.com/dashboard/discover) 页面，根据这些内容查看个性化仓库建议！

**探索 / 时事通讯**

“探索”页面包含由你关注的用户、GitHub 员工的加星项目以及常规趋势第一页上的仓库。

如果你希望每天、每周或每月收到这些简报，请查看“探索”页面底部的简报声明。

![时事通讯](https://guides.github.com/activities/socialize/subscribe-explore.png)

你稍后还可以在 [订阅页面](https://github.com/explore/subscribe) 配置这项设置。

如果你只想查看趋势仓库和用户，请 [转到趋势](https://github.com/trending)。

![趋势](https://guides.github.com/activities/socialize/trending.png)

### 庆祝

恭喜！你现在社交小王子了。看看接下来做些什么：

* [从 GitHub 获取你的项目](https://help.github.com/categories/importing-your-projects-to-github/)
* [复刻他人项目](https://itechub.gitbook.io/github-guides-zhcn/forking-projects)


# 简介

阅读时间：约 10 分钟

> *译自* [*Making Your Code Citable*](https://guides.github.com/activities/citable-code/)

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

> 高级提示：本教程面向希望在学术文献中引用 GitHub 仓库的研究人员。如果你已经设置了 GitHub 仓库，则可以在不安装任何特殊软件的情况下完成本教程。如果你尚未在 GitHub 上创建过项目，请先 [上传你的工作成果](https://help.github.com/categories/importing-your-projects-to-github/) 到仓库。

> 最后更新：2016 年 10 月


# 选择你的仓库

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

![登录](https://guides.github.com/activities/citable-code/repos.png)

> \*\*重要信息！\*\*确保通过在仓库中包含许可证来告诉人们如何重用你的工作成果。 如果你不知道哪种许可证适合你，请查看 [choosealicense.com](http://choosealicense.com/)。


# 登录 Zenodo

接下来，转到 [Zenodo](http://zenodo.org/) 并单击页面右上角的 **Log in** 按钮，这样你可以选择使用 GitHub 帐户登录。

![登录](https://guides.github.com/activities/citable-code/zenodo-login.png)

Zenodo 会将你重定向回 GitHub，询求你同意共享你的邮件地址以及在你的仓库中配置 [web 钩子](https://developer.github.com/webhooks/) 的权限。接着，单击 **Authorize application**，为 Zenodo 提供所需的权限。

> **重要信息**！如果要归档属于 GitHub 上的组织的仓库，则需要确保组织管理员已启用对 Zenodo 应用程序的 [第三方访问](https://help.github.com/articles/approving-third-party-applications-for-your-organization/)。

![认证](https://guides.github.com/activities/citable-code/zenodo-authorize.png)

#### 选择你想要归档的仓库

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

> \*\*重要信息！\*\*Zenodo 只能访问你的公共仓库，因此请确保你要存档的仓库是 [公共的](https://help.github.com/articles/making-a-private-repository-public/)。

![切换按钮](https://guides.github.com/activities/citable-code/zenodo-toggle-on.png)


# 查看仓库设置

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

![web 钩子](https://guides.github.com/activities/citable-code/webhook-view.png)


# 发布新版本

默认情况下，每次有新的 [发布](https://help.github.com/articles/about-releases) 时，Zenodo 都会存档你的 GitHub 仓库。要对此进行测试，请回到主仓库视图，然后单击 **releases** 标题项。

![仓库](https://guides.github.com/activities/citable-code/repo-view.png)

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

![发布版本](https://guides.github.com/activities/citable-code/create-release.png)

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

![第一个发布](https://guides.github.com/activities/citable-code/first-release.png)

### 检查一切是否生效

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

![上传](https://guides.github.com/activities/citable-code/upload-tab.png)


# 创建 DOI

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

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

![表单](https://guides.github.com/activities/citable-code/zenodo-form.png)


# 即将完成

回到你的 [Zenodo GitHub 页面](https://zenodo.org/account/settings/github)，你现在应该看到你的仓库中列有一个闪亮的新徽章，显示你的新 DOI！

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

![当前发布](https://guides.github.com/activities/citable-code/releases-present.png)


# 简介

阅读时间：约 10 分钟

> *译自* [*Mastering Issues*](https://guides.github.com/features/issues/)

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

![高亮导航显示](https://guides.github.com/features/issues/navigation-highlight.png)

例如，让我们看一下 [Bootstrap 的 Issues](https://github.com/twbs/bootstrap/issues)：

![issues 列表](https://guides.github.com/features/issues/listing-screen.png)

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

![issue 例子](https://guides.github.com/features/issues/example-issue.png)

* **标题**和**描述**表达了 issue 的全部内容。
* 彩色**标签**可帮助你对问题进行分类和过滤（就像邮件中的标签一样）。
* **里程碑**就像 issues 的容器一样。这对将 issues 与特定功能或项目阶段关联起来非常有用（例如，*Weekly Sprint 9/5-9/16* 或 *Shipping 1.0*）。
* 一名**被指派人**负责在任意时间处理该 issue。
* **评论**允许任何有权访问存储库的人提供反馈。

> 最后更新：2014 年 4 月 7 日


# 里程碑，标签和被指派人

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

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

![查看标签](https://guides.github.com/features/issues/labels.png)

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

## 里程碑

![查看里程碑](https://guides.github.com/features/issues/milestones.png)

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

* **Beta 发布** —— 归档启动项目测试版之前需要修复的错误。这是一个确保你没有遗漏任何东西的好方法。
* **十月冲刺** —— 归档你希望在 10 月份处理的 issues。当有很多事情要做时，这是一个集中精力的好方法。
* **重新设计** —— 归档与重新设计项目相关的 issues。这是收集有关工作内容想法的好方法。

## 标签

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

![查看标签列表](https://guides.github.com/features/issues/labels-listing.png)

## 被指派人

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


# 通知，@提及 和引用

通过在问题中使用@提及 和引用，你可以通知其他 GitHub 用户和团队，并相互交叉关联问题。这些方法提供了一种灵活的方式，可以让合适的人员高效地解决问题，并且易于学习和使用。它们适用于 GitHub 上的所有文本字段 —— 它们是我们的文本格式化语法的一部分，称为 [GitHub 版 Markdown](https://help.github.com/articles/writing-on-github#name-and-team-mentions-autocomplete)。

![Markdown 例子](https://guides.github.com/features/issues/markdown-example.png)

如果你想了解更多信息，请查看 [**Mastering Markdown**](http://guides.github.com/features/mastering-markdown/)。

## 通知

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

有两种方法可以接收通知：通过邮件和 web。你可以[在设置中](https://github.com/settings/notifications)配置接收通知的方式。如果你预计收到大量通知，我们建议你接收**所参与**项目的 web + 邮件通知，以及**所看过**项目的 web 通知。

![通知截屏](https://guides.github.com/features/issues/notifications.png)

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

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

![个人通知截屏](https://guides.github.com/features/issues/notification.png)

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

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 中创建一个如下所示的事件：

![创建引用截屏](https://guides.github.com/features/issues/reference.png)

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

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

![提交中引用的截屏](https://guides.github.com/features/issues/commit.png)

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

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


# 搜索

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

![搜索截屏](https://guides.github.com/features/issues/search.png)

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

* 关键字，例如，[提及“侧边栏”的所有 issues](https://github.com/twbs/bootstrap/issues?q=sidebar)
* 状态，例如，[提及“侧边栏”的所有已关闭的 issues](https://github.com/twbs/bootstrap/issues?q=sidebar+is%3Aclosed)
* 被指派人，例如，[提及“侧边栏”的所有被指派给 @mdo 的 issues](https://github.com/twbs/bootstrap/issues?q=sidebar+is%3Aclosed+assignee%3Amdo)

[我们关于搜索 Issues 的帮助文章](https://help.github.com/articles/using-search-to-filter-issues-and-pull-requests)可以向你展示其他搜索方式：使用创建/更新日期，标签，作者，评论计数，仓库所有者等。


# 概述 & 报告

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

## Issues 仪表板

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

* 你拥有和协作的仓库中的所有 issues
* 指派给你的 issues
* 你创建的 issues

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

## Pulse

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

![Pulse 截屏](https://guides.github.com/features/issues/pulse.png)

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


# Issues 的其他用途

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

* [用于开源项目的 bug 跟踪器](https://github.com/joyent/node/issues)
* [请求食谱](https://github.com/newmerator/recipes/issues)（也许你有一个很好的[无麸质披萨面团配方](https://github.com/newmerator/recipes/issues/3)？）

## 最后

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


# 简介

阅读时间：约 3 分钟

> *译自* [*Mastering Markdown*](https://guides.github.com/features/mastering-markdown/)

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

**你将学习的：**

* Markdown 格式如何使样式化协作编辑变得简单
* Markdown 与传统格式化方法的区别
* 如何使用 Markdown 格式化文本
* 如何利用 GitHub 的自动 Markdown 渲染
* 如何应用 GitHub 独特的 Markdown 扩展

> 最后更新：2014 年 1 月 15 日


# 什么是 Markdown?

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

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

* [Gists](https://gist.github.com/)
* Issues 和拉取请求中的评论
* 在扩展名为 `.md` 或 `.markdown` 的文件中

更多相关信息请看 *GitHub 帮助* 中的“[在 GitHub 上书写](https://help.github.com/categories/writing-on-github/)”。


# 例子

#### 文本

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

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

#### 列表

```
有时你想要有序列表：

1. 一
2. 二
3. 三

有时你想要突出要点：

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

或者，

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

有时你想要有序列表：

1. 一
2. 二
3. 三

有时你想要突出要点：

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

或者，

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

#### 图片

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

![Yaktocat](https://octodex.github.com/images/yaktocat.png)
```

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

![Yakotocat](https://octodex.github.com/images/yaktocat.png)

#### 标题 & 引用

```
# 结构化文档

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

### 这是一个三级标题

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

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

> 咖啡。有史以来最好的有机悬浮液……我用它击败了 Borg。
> ——Janeway 船长
```

## 结构化文档

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

#### 这是一个三级标题

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

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

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

#### 代码

```
使用 GitHub 的 markdown 来装饰代码的方式有很多种。如果你有行内代码，请用反引号包住它们：`var example = true`。如果你有一个更长的代码块，你可以缩进四个空格：

    if (isAwesome){
      return true
    }

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

```

if (isAwesome){ return true }

````

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

```javascript
if (isAwesome){
  return true
}
````

````

使用 GitHub 的 markdown 来装饰代码的方式有很多种。如果你有行内代码，请用反引号包住它们：`var example = true`。如果你有一个更长的代码块，你可以缩进四个空格：

```text
if (isAwesome){
  return true
}
````

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

```
if (isAwesome){
  return true
}
```

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

```
if (isAwesome){
  return true
}
```

#### 其他

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

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

- [x] 这是已完成的事项
- [ ] 这是未完成的事项

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

当然，emoji 也是支持的！
```

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

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

* [x] 这是已完成的事项
* [ ] 这是未完成的事项

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

当然，emoji 也是支持的！


# 语法指南

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

#### 标题

```
# 这是一个 <h1> 标签
## 这是一个 <h2> 标签
###### 这是一个 <h6> 标签
```

#### 强调

```
*这行字将会是斜体*
_这行字将会是斜体_

**这行字将会是粗体**
__这行字将会是粗体__

_你**可以**组合它们_
```

#### 列表

**无序**

```
* 项目 1
* 项目 2
  * 项目 2a
  * 项目 2b
```

**有序**

```
1. 项目 1
1. 项目 2
1. 项目 3
   1. 项目 3a
   1. 项目 3b
```

#### 图片

```
![GitHub Logo](/images/logo.png)
格式：![Alt Text](url)
```

#### 链接

```
http://github.com - automatic!
[GitHub](http://github.com)
```

#### 引用

```
如 Kanye West 所说：

> 我们活在未来
> 那么当下即是过去
```

#### 行内代码

```
我认为你这里应该使用 `<addr>` 元素代替。
```


# GitHub 风味 Markdown

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

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

#### 语法高亮

以下是如何使用 [GitHub 风味 Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/) 进行语法高亮的示例：

````
```javascript
function fancyAlert(arg) {
  if(arg) {
    $.facebox({div:'#foo'})
  }
}
````

````

你还可以简单地将代码缩进四个空格：

```text
    function fancyAlert(arg) {
      if(arg) {
        $.facebox({div:'#foo'})
      }
    }
````

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

```
def foo():
    if not bar:
        return True
```

#### 任务列表

```
- [x] 支持@提及、#引用、[链接]()、**格式化**、和 <del>标签</del>
- [x] 需要列表语法（支持任何无序或有序列表）
- [x] 这是一个已完成事项
- [ ] 这是一个未完成事项
```

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

#### 表格

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

```
标题一 | 标题二
----- | -----
第一格内容 | 第二格内容
第一列内容 | 第二列内容
```

会变成：

| 标题一   | 标题二   |
| ----- | ----- |
| 第一格内容 | 第二格内容 |
| 第一列内容 | 第二列内容 |

#### SHA 引用

对提交的 [SHA-1 哈希](http://en.wikipedia.org/wiki/SHA-1) 的任何引用都将自动转换为 GitHub 上对应提交的链接。

```
16c999e8c71134401a78d4d46435517b2271d6ac
mojombo@16c999e8c71134401a78d4d46435517b2271d6ac
mojombo/github-flavored-markdown@16c999e8c71134401a78d4d46435517b2271d6ac
```

#### 仓库内引用 Issue

任何引用 Issue 或拉取请求的编号都将自动转换为链接。

```
#1
mojombo#1
mojombo/github-flavored-markdown#1
```

#### 用户名 @提及

输入 `@` 符，后跟用户名，将通知该用户来查看评论。这被称为“@提及”，因为你\_提及\_了某个人。你还可以在组织内@提及团队。

#### 自动链接 URLs

任何 URL（如 `http://www.github.com/`）都将自动转换为可点击的链接。

#### 删除线

用两个波浪号包裹的任何单词（比如 `~~这个~~`）都会显示出删除线。

#### Emoji

GitHub 支持 [emoji](https://help.github.com/articles/basic-writing-and-formatting-syntax/#using-emoji)！

要查看我们支持的所有图片的列表，请查看 [Emoji 速查表](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md)。


# 简介

阅读时间：约 10 分钟

> *译自* [*Documenting your projects on GitHub*](https://guides.github.com/features/wikis/)

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

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

* README 文件是其他用户更快速，更简单地了解你的工作的方法。
* GitHub 上的 wikis 可帮助你以有用的方式提供项目的详细信息。

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

> 最后更新：2016 年 7 月 15 日


# 创建你的 README

通过 GitHub [创建新仓库](https://help.github.com/articles/creating-a-new-repository/) 时，请选择“使用 README 文件初始化此仓库”，除非你计划导入已有仓库。

![使用 README 初始化](/files/-LhyOaYlwFPZmdDKeQzk)

你的 README.md 文件现在可以在全新的仓库中进行编辑。你的项目名称位于其顶部，接着是你在创建仓库时选择包含的任何描述。README 文件很容易 [在 GitHub](https://help.github.com/articles/editing-files-in-your-repository/) 或本地修改。查看 [精通 Markdown 指南](https://itechub.gitbook.io/github-guides-zhcn/mastering-markdown/intro)，以了解有关如何在创建文件后修改文本的详细信息。


# 格式化你的 README

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

* **项目名称**：你项目的名称是人们在向下滚动到 README 时会看到的第一件事，它是在创建 README 文件时被包含在内的。
* **描述**：接着就是你项目的描述。一个好的描述具备清楚、简短以及有重点等特点。它描述项目的重要性及其作用。
* **目录**：可选地，包括目录以允许他人快速导航特别长或特别详细的 README 文件。
* **安装**：安装是高效的 README 文件的下一部分。它告诉其他用户如何在本地安装项目。可选地，包含一个 gif 图片，以使其他人更清楚。
* **用法**：下一部分是用法，你可以在其中指导其他人在安装项目后如何使用你的项目。这也是一个包含项目截图的好地方。
* **贡献**：较大的项目通常有关于为其项目做贡献的部分，其中概述了贡献说明。有时，这是一个单独的文件。如果你有特定的贡献偏好，请解释它们，以便其他开发人员知道如何最好地为你的工作做出贡献。要了解更多有关如何帮助其他人贡献的信息，请查看为 [仓库贡献者设置指南](https://help.github.com/articles/setting-guidelines-for-repository-contributors/) 的指南。
* **信用**：包括一个信用部分，以突出显示并链接到该项目的作者。
* **许可证**：最后，包含项目许可证的部分。有关选择许可证的更多信息，请查看 GitHub 的 [许可证指南](http://choosealicense.com/)！

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


# 创建你的 wiki

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

![首页截图](https://guides.github.com/features/wikis/wiki-blank-slate.png)


# 添加内容

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

![wiki 编辑器截图](https://guides.github.com/features/wikis/wiki-editor.png)

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

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


# 添加页面

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

![Wiki 侧边栏截图](https://guides.github.com/features/wikis/wiki-sidebar-closeup.png)

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

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

> 如果你已熟悉命令行操作，则还可以在本地修改 wiki。查看 [我们的帮助文章](https://help.github.com/articles/adding-and-editing-wiki-pages-locally) 了解更多信息。


# 语法高亮

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

````
```ruby
  def foo
    puts 'bar'
  end
````

```

该块必须以三个反引号开始，可选地后跟着该块包含的语言的名称。有关可以语法高亮的语言列表，请参阅 [Pygments 支持的语言列表](http://pygments.org/docs/lexers/)。

块内容应缩进到与起始反引号相同的程度。该块必须以与起始反引号相同缩进程度的三个反引号结束。

### 完成了！

你已经了解了一些有关如何最好地与 GitHub 社区的其他人分享关于你的工作的重要信息，无论你的项目是否足够庞大，还是你只是刚刚开始并设置一个清晰简洁的 README 文件。

要阅读有关本文所涵盖主题的更多信息，我们的 [创建新仓库](https://help.github.com/articles/creating-a-new-repository/)、[编辑仓库中的文件](https://help.github.com/articles/editing-files-in-your-repository/)、[为仓库贡献者设置指南](https://help.github.com/articles/setting-guidelines-for-repository-contributors/) 以及 [选择许可证](http://choosealicense.com/) 是很好的起点。或者，请查看其他的 [GitHub 指南](https://itechub.gitbook.io/github-guides-zhcn) 以继续学习。

最后，如果你对为项目构建文档网站感兴趣，我们建议你使用 [GitHub Pages](https://pages.github.com/)。  


```