因为我此前并未接触过相关的规范，此前参与过的项目也没有明确的提交守则与版本号命名规范，对于相关的规范我只在一些开源项目中看到过，以及偶然听人提起过，并没有一个较为完整的认识，所以我决定查询一些资料去学习一下如何规范一个项目的版本号。

所幸我在让 AI 帮我规范提交信息时，它提到了“约定式提交”这个概念，而“约定式提交”与“语义化版本”有着密切的关系，所以我先分别了解了两者的概念，然后了解了它们之间是如何相互对应的。

语义化版本

软件的版本号是一个软件的重要标识，而许多软件的版本号命名都遵循着一套规范，“语义化版本”就是其中的一种。

什么是语义化版本

首先来看语义化版本的概念：

语义化版本是一种用于描述软件版本的方式，它使用一组规则来描述版本的变化。语义化版本的规则如下：

• 版本号由三个部分组成：主版本号、次版本号、修订号，格式为：主版本号.次版本号.修订号
• 版本号的递增规则如下：
  • 主版本号：当软件发生了不兼容的 API 更改时，主版本号递增，次版本号和修订号重置为 0
  • 次版本号：当软件添加了新功能，但向后兼容时，次版本号递增，修订号重置为 0
  • 修订号：当软件进行了 bug 修复，向后兼容时，修订号递增
• 先行版本号及版本编译信息可以加到“主版本号.次版本号.修订号”的后面，作为延伸。

（PS：向后兼容指的是，用户 import 你的软件包，用了里面的函数，这个软件包更新时，用户无需做任何修改，预期结果也不受影响）

举个例子

让我们以一个例子来理解这种规则：

假设我们有一个版本号为 1.0.0 的软件包供外部软件调用，这个软件包中有一个函数example(a: string, b: number): string {}，以下三种情况分别对应了修订号、次版本号、主版本号的修改：

• example 函数体存在bug，我们在确保修复了这个 bug 的情况下未在软件包中引入新的 API，该函数依旧能够实现预期的功能，返回预期的结果。这时仅进行了 bug 修复，未添加新功能，未发生不兼容的API修改，版本号变为 1.0.1
• 软件包中新增了一种 example 函数的函数重载，它的实现函数变成example(a: string, b: number, c?: boolean): string {}，用户原有的函数调用依旧返回预期结果，但是当用户调用 example 函数传入 c参数时，返回值会发生变化，这时我们新增了一个函数重载，未发生不兼容的API修改，版本号变为 1.1.0
• example 函数新增了一个参数，变成example(a: string, b: number, c: string): string {}，用户原有的函数调用会报错提示缺少参数。这时我们在 example 函数中新增了一个参数，发生了不兼容的API修改，版本号变为 2.0.0

可以看到，语义化版本的规则是非常清晰的，它规定了版本号的递增规则，以及当软件发生不兼容的 API 修改时，版本号的变化。这也是语义化版本的最主要的作用，它可以确保用户在使用某一主版本的软件包时，已编写的代码在该软件包仅发生次版本号会修订版本号更新时，不会出现错误。

开发初始阶段的版本控制

软件的主版本号为零（0.y.z）是一种特殊状态，这意味着该软件处于开发初始阶段，一切都可能随时被改变。因此在初始开发阶段，进行版本控制最简单的做法是以 0.1.0 作为初始化开发版本，并在后续的每次发行时递增次版本号。

如何判断发布 1.0.0 版本的时机

当软件被部署到生产环境中开始被正式使用，它应该已经达到了 1.0.0 版。此时的软件已经有了一系列稳定的API在被使用者依赖，并开始需要考虑向后兼容的问题。

版本的优先级

对于不同版本号的软件，如何排序决定它们的优先级呢？在判断优先级时，我们必须把版本依序拆分为主版本号、次版本号、修订号及先行版本号后进行比较（版本编译信息不在这份比较的列表中）。随后，按照这三条规则进行判断：

• 对于两个正式版本，需要依据它们的主版本号、次版本号、修订号依次进行比较，直到找到第一个不同的数字，该数字较大的版本号优先级较高（例如1.0.0 < 1.0.1 < 1.1.0 < 1.1.1 < 2.0.0）
• 对于具有相同主版本号、次版本号、修订号的正式版本和先行版本，正式版本的优先级总是高于先行版本（例如1.0.0-alpha < 1.0.0）
• 对于两个先行版本，如果它们的主版本号、次版本号、修订号完全相同，其优先级必须通过由左到右的每个被句点分隔的标识符来比较，直到找到一个差异值后，按照如下规则决定：
  • 只有数字的标识符以数值高低比较。（例如1.0.0-alpha.1<1.0.0-alpha.5）
  • 有字母或连接号时则逐字以 ASCII 的排序来比较。（例如1.0.0-alpha.beta<1.0.0-alpha.rc）
  • 数字的标识符比非数字的标识符优先级低。（例如1.0.0-0<1.0.0-alpha）
  • 若开头的标识符都相同时，栏位比较多的先行版本号优先级比较高。（例如1.0.0-alpha.1<1.0.0-alpha.1.0）

再举一个最直观的例子：
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0 < 1.0.1 < 1.1.0 < 1.1.1 < 2.0.0
你可以按照上述的三条规则，一一它们的优先级排列，相信你会对版本的优先级有更加深刻的认识。

约定式提交

最开始时我提到过，“约定式提交”与“语义化版本”有着密切的关系，这是因为在进行源代码管理时，我们通常会使用版本控制工具，如 Git，在使用git commit提交代码时，如果我们按照“约定式提交”的规范填写提交信息，我们可以方便地将一组特定的提交发布为一个新版本，而这个新版本可以按照对应的提交类型确定版本号如何更新。

在许多开源项目的 contribute 指南中，都有约定式提交的规范，比如在 arco-design的CONTRIBUTING.zh-CN.md 的 Commit 指南章节，就要求 Commit messages 需要遵循约定式提交的标准，并列出了 commit 的类型列表。

因此，让我们首先了解什么是约定式提交。

什么是约定式提交

首先来看约定式提交的概念：

约定式提交是一种用于描述提交信息的方式，它使用一组规则来描述提交的内容。约定式提交的规则如下：

• 提交信息必须以一个描述性的标题开头，标题的第一个单词必须是提交类型，提交类型必须是以下之一：
  • feat：新功能（feature），类型 为 feat 的提交表示在代码库中新增了一个功能（这和语义化版本中的 次版本号 相对应）。
  • fix：bug 修复，类型 为 fix 的提交表示在代码库中修复了一个 bug（这和语义化版本中的 修订号 相对应）。
  • BREAKING CHANGE：破坏性变更，在脚注中包含 BREAKING CHANGE: 或 <类型>(范围) 后面有一个 ! 的提交，表示引入了破坏性 API 变更（这和语义化版本中的 MAJOR 相对应）。
  • 其他提交类型：例如 docs、chore、style、refactor、perf、test、build、ci、revert 等
• 提交信息的结构如下所示：

  <类型>[可选 范围]: <描述>
  [可选 正文]
  [可选 脚注]
  

让我们通过一些例子了解如何完成一个约定式提交：

• 包含了描述、范围并且脚注中有破坏性变更的提交说明：

  feat(api): 新增了一个新功能
  这是一个新功能的详细描述。
  BREAKING CHANGE: 这个提交引入了一个破坏性变更。
  

• 包含了 ! 字符以提醒注意破坏性变更的提交说明：

  feat(api)!: 新增了一个新功能
  这是一个新功能的详细描述。
  

• 不包含正文的提交说明：

  docs: correct spelling of CHANGELOG
  

约定式提交与语义化版本的对应关系

举个例子

让我们以一个例子来理解这种规则：

对于一个当前版本为 1.0.0 的项目，我们有以下几个提交：

• feat(api): 新增了一个新功能
• fix(api): 修复了一个 bug
• docs: 修正了文档中的错误

我们现在想要发布一个新版本，由于新的提交包括了新功能的增加，但是没有引入破坏性的变更，所以我们可以按照语义化版本的规则，将次版本号递增，版本号变为 1.1.0。

但是如果我们有以下几个提交：

• feat(api)!: 新增了一个新功能, 引入了破坏性变更
• fix(api): 修复了一个 bug
• docs: 修正了文档中的错误

由于引入了破坏性变更，如果我们此时想要发布新版本，我们需要将主版本号递增，版本号变为 2.0.0。

使用约定式提交的好处

使用约定式提交有以下几个好处：

• 便于建立流水线自动化生成 CHANGELOG 、自动化触发对应的构建与部署流程，从而方便地进行版本发布。
• 便于基于提交的类型，自动决定语义化的版本变更，从而方便地进行版本管理。
• 便于形成结构化的提交历史，向同事、公众与其他利益关系者传达变化的性质，降低贡献者了解项目发展历程的难度。

后记

语义化版本和约定式提交是两个相互关联的概念，它们都可以帮助我们更好地管理软件版本。语义化版本规定了版本号的递增规则，以及当软件发生不兼容的 API 修改时版本号的变化。约定式提交规定了提交信息的结构，以及如何根据提交信息自动决定版本号的变化。

在实际的项目开发与项目管理过程中，建立和遵守这些规范可以提高软件的质量和可维护性，同时也可以方便地进行版本管理和发布，提高开发效率与协作效率。

参考文章

• 语义化版本 2.0.0 | Semantic Versioning
• 约定式提交

GitHub 拥有许多特殊的存储库。比如，你可以创建一个与你用户名相匹配的存储库，添加 README 文件，其包含的所有信息都将在你的 GitHub 个人资料中可见。

你可能已经对许多仓库中的 .github 目录很熟悉了，而 .github 目录中包含了工作流（Workflow）、议题模板（Issue Template）、拉取请求模板（Pull Request Template）、资助信息（Funding Information）及那个项目所特有的文件。

但另一个你能创建的特殊仓库却是 .github 仓库。它的作用是为你那些实质上没有 .github 目录的库提供默认的议题模板及其他社区健康文件[^1]。

举个例子，假如说我有一个名为 .github 的存储库，其中包含通用的故障报告（Bug Report）和功能请求的议题模板（Feature Request Issue Template）。然后再建另一个名为 new-project 的库，但我没有在其中添加包含议题模板的 .github 目录。

那么当有人看到这个 new-project 库并打开一个议题时，他将看到一个选项用来选择 .github 仓库的同名目录中[^2]已有的通用模板。

同样的，当我为我的 .github 库中添加行为准则（Code of Conduct）后，它将在我所有未明确规定过的库中展示出来。

请注意，相对于 .github 仓库中的文件，当前仓库会优先选择自己 .github 目录中的那份文件。比如说，当我 new-project 库的 .github 目录中有功能请求的议题模板时， .github 库中的那份就不会被展示出来。

让我们看看这些特殊的仓库是如何运作的吧。

如何在私人 GitHub 账号中使用 .github

在 GitHub 上，创建特殊的仓库同创建其他库一样简单。所以打开浏览器，登上 GitHub，像这样创建一个仓库：

完成后，你可以开始往里添加文件。我要加的第一个文件是故障报告表单（Bug Report Issue Form）。我并不准备详细地讲表格的详情，不过你可以浏览我先前有关 GitHub 议题表单的文章。

.github/ISSUE_TEMPLATE/bug_report.yml

name: 🐛Bug Report
description: File a bug report here
title: "[BUG]: "
labels: ["bug"]
assignees: ["AnishDe12020"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report 🤗
        Make sure there aren't any open/closed issues for this topic 😃
        
  - type: textarea
    id: bug-description
    attributes:
      label: Description of the bug
      description: Give us a brief description of what happened and what should have happened
    validations:
      required: true
      
  - type: textarea
    id: steps-to-reproduce
    attributes:
      label: Steps To Reproduce
      description: Steps to reproduce the behavior.
      placeholder: |
        1. Go to '...'
        2. Click on '...'
        3. Scroll down to '...'
        4. See error
    validations:
      required: true
  - type: textarea
    id: additional-information
    attributes:
      label: Additional Information
      description: |
        Provide any additional information such as logs, screenshots, likes, scenarios in which the bug occurs so that it facilitates resolving the issue.

故障报告表单代码

我还打算创建一份功能请求表单。

.github/ISSUE_TEMPLATE/feature_request.yml

name: ✨Feature Request
description: Request a new feature or enhancement
labels: ["enhancement"]
title: "[FEAT]: "
body:
  - type: markdown
    attributes:
      value: |
        Please make sure this feature request hasn't been already submitted by someone by looking through other open/closed issues
  
  - type: textarea
    id: description
    attributes:
      label: Description
      description: Give us a brief description of the feature or enhancement you would like
    validations:
      required: true
      
  - type: textarea
    id: additional-information
    attributes:
      label: Additional Information
      description: Give us some additional information on the feature request like proposed solutions, links, screenshots, etc.

功能请求表单代码

我要再加一份拉取请求模板。

.github/pull_request_template.md

<!-- 
感谢你的拉取请求 🤗

请确保拉取请求被限定在一个类中（文档或功能之类的），而且让它尽可能地小。你可以开多个 pr(Pull Request, 拉取请求) 而不是单开一个很大的。
-->

<!-- 如果这个拉取请求关闭了议题，请在下面提及 -->
Closes # <!-- 对应议题的序号 -->

## 📑 描述
<!-- 为 pr 添加一个简短的描述-->

<!-- 你也可以选择用 markdown 的 to-do list 格式列出一系列变更来标记是否完成- [ ] 未完成
- [x] 已完成
-->

## ✅ 检查
<!-- 确保你的 pr 通过了 CI(Continuous Integration, 持续集成) 检查,并且根据需要选择以下选项 - -->
- [ ] 我的拉取请求符合本项目的代码风格
- [ ] 我的代码需要修改文档
- [ ] 我已按要求更新了文件
- [ ] 所有测试均已通过

## ℹ 补充信息
<!-- 任何补充信息，像破坏性更新（Breaking Change）、依赖添加（Dependency Added）、截图（Screenshot）和新旧行为的对比等等 -->

拉取请求模板代码

我要加的最后一个文件是行为准则————不过它要放在库的根目录下。尽管如此，它也能正常工作（行为准则通常都被保存在根目录下）。注意，我在使用的是 Contributor Convent 公约。

CODE_OF_CONDUCT.md

# Contributor Covenant Code of Conduct

## Our Pledge

We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, caste, color, religion, or sexual
identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.

## Our Standards

Examples of behavior that contributes to a positive environment for our
community include:

* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
  and learning from the experience
* Focusing on what is best not just for us as individuals, but for the overall
  community

Examples of unacceptable behavior include:

* The use of sexualized language or imagery, and sexual attention or advances of
  any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email address,
  without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
  professional setting

## Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.

Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.

## Scope

This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
[INSERT CONTACT METHOD].
All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the
reporter of any incident.

## Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:

### 1. Correction

**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.

**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.

### 2. Warning

**Community Impact**: A violation through a single incident or series of
actions.

**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or permanent
ban.

### 3. Temporary Ban

**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.

**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.

### 4. Permanent Ban

**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.

**Consequence**: A permanent ban from any sort of public interaction within the
community.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.1, available at
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].

Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].

For answers to common questions about this code of conduct, see the FAQ at
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
[https://www.contributor-covenant.org/translations][translations].

[homepage]: https://www.contributor-covenant.org
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations

Markdown 格式的 Contributor Convent 行为准则 v2.1

我们还可以添加更多文件，像资助信息、贡献指南(Contributing Guide)等。你可以在 GitHub 文档 中获取更多信息。

.github 存储库实践

我的 blog 库并没有任何议题模板、行为准则或其他文件，除了记录了我博客的 markdown 文件和一篇 README。所以这是用来测试这些功能(feature)是否起作用的绝佳仓库。

我已经可以看到行为准则在这里出现了：

如果我尝试去创建议题，也会收到模板：

在拉取请求时也起作用了。

如何将 .github 存储库用于组织或公共账号

组织账号中的 .github 存储库和个人账号上的 .github 存储库工作原理相同——只有一处区别。

组织也可以在 GitHub 上拥有 README 资料，它将展示在组织页面上。这个 README 位于组织 .github 仓库的 profile 目录下。为了展示，我将快速地建一个演示组织。

当为组织创建 .github 仓库时，你应该会得到如下消息：

同样的，当你给 profile/README.md 添加内容时，你也应该会受到这样的消息：

现在，我准备向 README 里加一些内容并提交。当我访问组织首页时，我们应当看到下面内容：

总结

我希望你现在知道了 .github 仓库到底是什么。你也应该明白如何为你的库创建默认社区健康文件还有如何为你的组织添加 README 资料。

请随意通过 Twitter 联系我。祝你有美好的一天😃

资源

• GitHub 文档中关于社区健康文件的内容
• 我的 .github 仓库
• 我测试组织的 .github 仓库
• Contributor Convent
• 有关如何使用 GitHub 议题表单的文章

我最近在开发一个叫 DevKit 的项目，这是一个渐进式 Web 应用，它将开发者工具整合在一个应用中，且让你的工作更快地完成。一定要来看看 https://www.devkit.one/ 。

译者注

^1 翻译来源于这篇文章。
^2 原文为 already in the .github directory ，我认为直接放在文中不合理，故修改，请注意，后文同样预设你已知要将文件放在同名库的 .github 目录下。

如今，开发人员经常使用自动化工具来有效地管理任务，并简化他们的日常活动。GitHub Actions 就是这些流行的工具之一。

你可能会同意我的观点：软件（包括开源软件）对效率的要求很高。在这种自动化工具的帮助下，维护者可以将重复性的工作自动化，并专注于更重要的任务，如编写高质量的代码、审核贡献，以及围绕项目创建一个活跃的社区。

我曾经不得不手动完成一些本可以自动化的任务，所以我觉得我有资格分享如何使用 GitHub Actions 来节省时间。

我花了大半天的时间去研究我的一个已经吸引了贡献者的迷你 Python 项目。我给新的贡献者写热情洋溢的欢迎词，检查最近 pull requests，以确保他们遵守项目的规则比如 README 文件和说明、如果需要的话提供截图，等等。

但我不知道的是，我可以自动执行其中一些任务以及更多任务，以减少自己的工作量。我可以在 GitHub Actions 的帮助下做到这一点。

在本指南中，我将分享更多关于 GitHub Actions 的信息，以及我如何使用它。我将向你展示如何利用它来自动化项目的各个方面，从欢迎新贡献者到分配任务、检查代码质量等等。我们一起来让你的项目更加高效、更具有交互性。

GitHub Actions 是什么

GitHub Actions 是一种工具，可让你在 GitHub 仓库中执行不同的自动化操作。它允许你创建自定义工作流，你可以使用这些工作流来自动化开发过程，例如构建、测试和部署代码。

将此工具与其他 GitHub 功能集成后，你可以转变你的项目管理程序，让每个参与其中的人都更加愉快，更加有参与感。

如何在你的仓库中设置 GitHub Actions

一切都从根文件夹开始。默认情况下，GitHub Actions 通常集成在你的 GitHub 仓库中，因此你无需在安装时注册单独的账户。但是你需要执行几个步骤才能访问它的功能。

• 在你的 GitHub 仓库中，在顶部导航选项卡上，你将看到 Actions 选项卡。单击它，你可以访问推荐的工作流列表以及创建自己的工作流的选项。
• 现在，根据项目的性质，你可以选择从可用列表中选择一个已经创建的工作流，也可以选择自己创建一个。由于你了解项目的全部内容以及可能需要自动化的内容，因此我建议你自己设置一个新的工作流程。这将使你更好地了解正在发生的事情。
• 要设置新的工作流程，请单击 Set up a workflow yourself（自行设置工作流程）。这将带你进入一个工作流创建界面，其中包含一个名为 main.yml 的新 YAML 文件。既然你选择编写自己的工作流程，在这里，我应该提到了解 YAML 非常重要。

在幕后发生的事情是，一旦你单击此选项，就会在 main.yml 文件旁边创建两个文件夹。如果你之后访问你的仓库或查看文件名之前的路径，你将看到：.github/workflows/<filename>。

• 在 main.yml 文件中是你定义工作流程的地方，在编写完所有内容后，你可以提交更改（commit the changes），就像对仓库进行更改时所做的那样。这样，你就设置了工作流，它将根据 YAML 文件中定义的触发器运行。

或者，你仍然可以在你最喜欢的代码编辑器中完成这一切。你需要做的就是将仓库克隆到你的计算机上，在项目的根文件夹中创建一个 .github 文件夹，在其中创建另一个名为 workflows 的文件夹，最后添加一个扩展名为 .yml 的文件并将你的脚本写入这个文件。

在下面的示例中，我将引用我在项目中实现的代码来帮助你理解。

GitHub Actions 组件

GitHub Actions 主要由三个主要组件组成，包括：

• 工作流（Workflows） - 这些是定义自动化过程的规则集。它们在 YAML 文件中定义，该文件存储在 .github/workflows 目录中。
• 事件（Events） - 它们启动工作流。例如，你可以将事件设置为在创建 PR 或新开 issue 时运行工作流。要在工作流中定义事件，请使用关键字 on 后跟事件名称。

例如：

on:
    issues:
        types: [opened]
    pull_request_target:
        types: [opened]

• 任务（Jobs） - 这些构成了工作流程。默认情况下，任务是同时运行的。要在给定的工作流中定义你的任务，请使用关键字 jobs，后跟每个任务及其配置的唯一标识符。

例如：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.10
      - name: Install dependencies
        run: |
          pip install -r requirements.txt

所有这些组件确保一组特定的规则被成功执行。现在看看我们的项目。

如何自动化管理 issue 和 pull request

管理 issue 和 pull request 可能是一项非常耗时的工作，尤其是对于大型开源项目。但有了 GitHub Actions，维护者就可以把这些流程自动化，把更多的时间花在编码和与社区互动上。

如何创建 issue 和 pull request 模板

如果你是一个活跃的开源贡献者，你有可能遇到过一个指南，告诉你在创建 issue 或提交 PR 时应该包括什么。这种模板的主要目的是提供指导，确保贡献者提供所有必要的信息。

现在，让我们看看你如何在你的项目中创建这个模板：

• 第一步是确保在仓库的 root 中有一个 .github 目录，如果你还没有的话。
• 在 .github 文件夹内，创建两个文件夹 ISSUE_TEMPLATE 和 PULL_REQUEST_TEMPLATE。
• 在这两个文件夹中，添加代表你想自动化内容的 markdown 文件：例如，你可以将 feature_request.md 和 issue_report.md 作为 issue 模板，将 pull_request_template.md 作为 PR 模板。

下面是我在 pull_request_template.md 文件中写的内容，作为参考。这是一个简单的指南，告诉贡献者在提交 pull request 之前应该包括什么。

**Related Issue(s):**
Please provide a title for this pull request.

**Description:**
Please provide a brief description of the changes you are proposing.

**Checklist:**

-   [ ] I have read and followed the [contributing guidelines](/CONTRIBUTING.md).
-   [ ] I have included a README file for my project.
-   [ ] I have updated the main README file where necessary.
-   [ ] I have included a requirements.txt file.
-   [ ] I have added tests that prove my changes are effective or that my feature works.
-   [ ] All new and existing tests pass.

**Screenshots**
If applicable, add screenshots to help explain behavior of your code.

**Additional Notes:**
Please provide any additional information about the changes you are proposing.

如需更详细的解释，请在这里查看 GitHub Action 关于 issue 和 pull request 模板的文档。

欢迎新的贡献者并表彰社区的努力

作为一个维护者，与社区打交道是很重要的，因为你有机会与你的朋辈直接互动并获得反馈。但如果你正在运行一个吸引众多贡献者的大型项目，你可能不会经常有机会直接与社区互动。

在 GitHub Actions 的帮助下，你可以完成其中的一些任务，比如欢迎新的贡献者，认可他们的努力，并为现有的社区成员创造一个积极的氛围。

如果你正在管理一个小项目，你可能可以直接与社区互动，但仍然利用自动化来完成一些工作。

例如，这里有一些示例代码，当新的贡献者创建 pull request 或在仓库上创建一个新的 issue 时，我通过这些代码来欢迎他们。在其中，你可以看到我有一条信息，感谢他们的努力，也向他们保证我将尽快审核他们提交的修改。尽管如此，如果需要额外的东西或提出新的想法，我还是会通过对话去跟进。

name: Welcome New Contributors

on:
    issues:
        types: [opened]
    pull_request_target:
        types: [opened]

jobs:
    welcome:
        runs-on: ubuntu-latest
        steps:
            - name: Welcome Issue
              if: github.event_name == 'issues'
              uses: actions/github-script@v5
              with:
                  script: |
                      const issue = context.issue;
                      const repo = context.repo;
                      const issueAuthor = context.payload.sender.login;
                      const welcomeMessage = `
                        Hi @${issueAuthor}! :wave:
                        Thank you for creating an issue in our repository! We appreciate your contribution and will get back to you as soon as possible.
                      `;
                      github.rest.issues.createComment({
                        ...repo,
                        issue_number: issue.number,
                        body: welcomeMessage
                      });
            - name: Welcome Pull Request
              if: github.event_name == 'pull_request_target'
              uses: actions/github-script@v5
              with:
                  script: |
                      const pr = context.issue;
                      const repo = context.repo;
                      const prAuthor = context.payload.sender.login;
                      const welcomeMessage = `
                        Hi @${prAuthor}! :wave:
                        Thank you for submitting a pull request! We appreciate your contribution and will review your changes as soon as possible.
                      `;
                      github.rest.issues.createComment({
                        ...repo,
                        issue_number: pr.number,
                        body: welcomeMessage
                      });

除了这个简单的工作流程外，如果你正在领导一个更复杂的项目，你可以考虑编写一个更详细的工作流程，能够自动为贡献者分配徽章、标签或自定义标题。

同样，你也可以选择添加一个工作流，在贡献者的 pull request 被合并或 issue 被关闭时对其表示感谢。你可以查看 GitHub Action 文档，了解详细的指南。

如何实现代码 QA 的自动化

对于大多数开发人员来说，编写高质量的代码是非常重要的，特别是如果他们正在创建与消费者有关的应用。虽然一个项目的成功取决于精心编写和测试的代码，但有时审核修改可能会花些时间，甚至会使用户正需要的功能延迟上线。

在代码自动化工具的帮助下，你可以保持一致的编码风格，并快速和容易地识别潜在的错误，保持你的项目整洁。

那么，如何用 GitHub Actions 设置持续集成（CI），整合代码 formatting 和 linting 工具，并在项目中使用自动化代码审核服务？

持续集成（CI）帮助你实现流程自动化，如构建、测试和验证代码更改。就像其他自动化代码一样，CI 代码写在一个 .yml 文件中，存储在 .github/workflows 文件夹中。

下面是一个 Python 项目 CI 工作流程的例子，它在向仓库的 main 分支 pull request 时运行。它测试 Python 多个版本的代码，安装必要的依赖，并使用 unittest 模块运行测试。

name: Python CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.7, 3.8, 3.9, 3.10]

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v2
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
    - name: Run tests
      run: |
        python -m unittest discover

除了上面的代码，如果你想保持代码风格的一致性，你可以整合代码 formatting 和 linting 工具，如 black、isort 或 flake8。为此，你只需要在 requirements.txt 文件中加入这些工具，该文件已经包含在上述代码中。下面的代码块运行这些工具。

#...
    # ...
    - name: Run black for code formatting
      run: |
        black --check .
    - name: Run isort for import sorting
      run: |
        isort --check --diff .
    - name: Run flake8 for linting
      run: |
        flake8 .

如果它发现任何代码格式问题，CI 构建将失败。要解决这个问题，你必须手动检查日志。请查看这个关于构建和测试 Python 的指南，了解更多的例子。

上面的想法只是你可以在项目中使用的一些自动程序。对于一个更复杂的应用，你可以考虑增加工作流程，用 Sphinx 或 MkDocs 等工具生成文档，自动化依赖性更新，自动化发布管理和项目跟踪，等等。

关于构建自定义 GitHub Actions 的提示

在 GitHub Actions 市场上已经有很多预制的 action。但有时你可能想要或需要定制工作流程以满足你的需求。

为此，你可以选择 JavaScript 或 Docker 容器，并与社区分享。

这里有一些可以遵循的最佳做法：

• 了解问题 - 就像其他项目一样，在开始构建之前，确保你了解要解决的问题以及你将如何解决它。
• 选择正确的技术栈 - 如上所述，可以使用 JavaScript 或 Docker 编写 GitHub Actions。请确保选择最适合你的需求和理解的方式。
• 确保你遵守最佳的编码实践，以便别人能够轻松地理解和阅读你的代码。
• 利用已有的软件包，如 @actions/core 和 @actions/github，它们提供了与 GitHub Actions 环境和 GitHub API 的简单互动。
• 在成功创建自己的工作流程后，你有可能想要发布它。无论你是否发布，请确保测试你的 action 是否有潜在的问题或错误。

通过这些简单的技巧，你可以创建一个自定义的 GitHub Action 来自动完成项目中的一些主要/基本任务。除了上面的提示，你可以在官方文档中找到更多关于创建自定义 action 的详细信息。

总结

在本指南中，我们看到了 GitHub Actions 能给我们的项目带来的好处。它不仅简化了生产流程，而且还允许我们自定义 action 以适应项目需要。

这仅仅是我们能实现的东西的一小部分。我鼓励你更好地理解和探索不同的方法，以进一步用 GitHub Actions 改进你的开源项目。让我们拥抱自动化，利用它来完成更多工作。

对大多数开发者来说，有时候需要在同一台机器上管理多个 GitHub 账户。当我碰巧换了 Mac，或者需要用新的工作账户进行 Git 推送时，我经常都需要停下来去搜索如何实现。

我的懒惰使我没有把过程记录下来，也没有能力记住步骤，这使我花了相当多的时间从网上找零碎的东西，然后以某种方式使它发挥作用。

我相信你们当中有很多人都有过这样的经历，也有很多人只是在等待下一次发生同样的事情（包括我自己！）。本文介绍的方法是为了帮助我们所有人。

1. 生成 SSH 密钥

在生成 SSH 密钥之前，我们可以检查一下我们是否有任何现有的 SSH 密钥：ls -al ~/.ssh 这将列出所有现有的公钥和私钥对，如果存在的话。

如果 ~/.ssh/id_rsa 是可用的，我们可以重新使用它，否则我们可以先通过运行以下代码来生成一个默认 ~/.ssh/id_rsa 的密钥：

ssh-keygen -t rsa

对于保存密钥的位置，按回车键接受默认位置。一个私钥和公钥 ~/.ssh/id_rsa.pub 将在默认的 SSH 位置 ~/.ssh/ 创建。

让我们为我们的个人账户使用这个默认的密钥对。

对于工作账户，我们将创建不同的 SSH 密钥。下面的代码将生成 SSH 密钥，并将标签为 “email@work_mail.com” 的公钥保存到 ~/.ssh/id_rsa_work_user1.pub 中。

$ ssh-keygen -t rsa -C "email@work_mail.com" -f "id_rsa_work_user1"

我们创建了两个不同的密钥：

~/.ssh/id_rsa
~/.ssh/id_rsa_work_user1

2. 将新的 SSH 密钥添加到相应的 GitHub 账户中

我们已经准备好了 SSH 公钥，我们将要求 GitHub 账户信任我们创建的密钥。这是为了避免每次进行 Git 推送时都要输入用户名和密码的麻烦。

复制公钥 pbcopy < ~/.ssh/id_rsa.pub，然后登录你的个人 GitHub 账户：

• 转到 Settings
• 在左边的菜单中选择 SSH and GPG keys
• 点击 New SSH key，提供一个合适的标题，并将密钥粘贴在下面的方框中
• 点击 Add key - 就完成了！

对于工作账户，使用相应的公钥（pbcopy < ~/.ssh/id_rsa_work_user1.pub），在 GitHub 工作账户中重复上述步骤。

3 . 在 ssh-agent 上注册新的 SSH 密钥

为了使用这些密钥，我们必须在我们机器上的 ssh-agent 上注册它们。使用 eval "$(ssh-agent -s)" 命令确保 ssh-agent 运行。像这样把密钥添加到 ssh-agent 中：

ssh-add ~/.ssh/id_rsa
ssh-add ~/.ssh/id_rsa_work_user1

让 ssh-agent 为不同的 SSH 主机使用各自的 SSH 密钥。

这是最关键的部分，我们有两种不同的方法：

使用 SSH 配置文件（第 4 步），以及在 ssh-agent 中每次只有一个有效的 SSH 密钥（第 5 步）。

4. 创建 SSH 配置文件

在这里，我们实际上是为不同的主机添加 SSH 配置规则，说明在哪个域名使用哪个身份文件。

SSH 配置文件将在 ~/.ssh/config 中。如果有的话，请编辑它，否则我们可以直接创建它。

$ cd ~/.ssh/
$ touch config           // Creates the file if not exists
$ code config            // Opens the file in VS code, use any editor

在 ~/.ssh/config 文件中为相关的 GitHub 账号做类似于下面的配置项：

# Personal account, - the default config
Host github.com
   HostName github.com
   User git
   IdentityFile ~/.ssh/id_rsa
   
# Work account-1
Host github.com-work_user1    
   HostName github.com
   User git
   IdentityFile ~/.ssh/id_rsa_work_user1

“work_user1” 是工作账户的 GitHub 用户 ID。

“github.com-work_user1” 是用来区分多个 Git 账户的记号。你也可以使用 “work_user1.github.com” 记号。确保与你使用的主机名记号一致。当你克隆一个仓库或为本地仓库设置 remote origin 时，这一点很重要。

上面的配置要求 ssh-agent：

• 使用 id_rsa 作为任何使用 @github.com 的 Git URL 的密钥
• 对任何使用 @github.com-work_user1 的 Git URL 使用 id_rsa_work_user1 密钥

5. 在 ssh-agent 中每次有一个活跃的 SSH 密钥

这种方法不需要 SSH 配置规则。相反，我们手动确保在进行任何 Git 操作时，ssh-agent 中只有相关的密钥。

ssh-add -l 会列出所有连接到 ssh-agent 的 SSH 密钥。把它们全部删除，然后添加你要用的那个密钥。

如果是要推送到个人的 Git 账号：

$ ssh-add -D            //removes all ssh entries from the ssh-agent
$ ssh-add ~/.ssh/id_rsa                 // Adds the relevant ssh key

现在 ssh-agent 已经有了映射到个人 GitHub 账户的密钥，我们可以向个人仓库进行 Git 推送。

要推送到工作的 GitHub account-1，需要改变 SSH 密钥与 ssh-agent 的映射关系，删除现有的密钥，并添加与 GitHub 工作账号映射的 SSH 密钥。

$ ssh-add -D
$ ssh-add ~/.ssh/id_rsa_work_user1

目前，ssh-agent 已经将密钥映射到了工作的 GitHub 账户，你可以将 Git 推送到工作仓库。不过这需要一点手动操作。

为本地仓库设置 git remote url

一旦我们克隆/创建了本地的 Git 仓库，确保 Git 配置的用户名和电子邮件正是你想要的。GitHub 会根据提交（commit）描述所附的电子邮件 ID 来识别任何提交的作者。

要列出本地 Git 目录中的配置名称和电子邮件，请执行 git config user.name 和 git config user.email。如果没有找到，可以进行更新。

git config user.name "User 1"   // Updates git config user name
git config user.email "user1@workMail.com"

6. 克隆仓库

注意：如果我们在本地已经有了仓库，那么请查看第 7 步。

现在配置已经好了，我们可以继续克隆相应的仓库了。在克隆时，注意我们要使用在 SSH 配置中使用的主机名。

仓库可以使用 Git 提供的 clone 命令来克隆：

git clone git@github.com:personal_account_name/repo_name.git

工作仓库将需要用这个命令来进行修改：

git clone git@github.com-work_user1:work_user1/repo_name.git

这个变化取决于 SSH 配置中定义的主机名。@ 和 : 之间的字符串应该与我们在 SSH 配置文件中给出的内容相匹配。

7. 对于本地存在的版本库

如果我们有已经克隆的仓库：

列出该仓库的 Git remote，git remote -v

检查该 URL 是否与我们要使用的 GitHub 主机相匹配，否则就更新 remote origin URL。

git remote set-url origin git@github.com-worker_user1:worker_user1/repo_name.git

确保 @ 和 : 之间的字符串与我们在 SSH 配置中给出的主机一致。

如果你要在本地创建一个新的仓库：

在项目文件夹中初始化 Git git init。

在 GitHub 账户中创建新的仓库，然后将其作为 Git remote 添加给本地仓库。

git remote add origin git@github.com-work_user1:work_user1/repo_name.git 

确保 @ 和 : 之间的字符串与我们在 SSH 配置中给出的主机相匹配。

推送初始提交到 GitHub 仓库：

git add .
git commit -m "Initial commit"
git push -u origin master

我们完成了！

依据正确的主机，添加或更新的本地 Git 目录的 Git remote，选择正确的 SSH 密钥来验证我们的身份。有了以上这些，我们的 git 操作应该可以无缝运行了。

当我还是一个开源贡献的初学者时，我最大的挑战之一是找到正确的项目/issue 来为其做贡献。

在很长一段时间里，我依靠互联网上不同作者创作的资源（顺便说一下，这些资源很好）。但我一直想找到一种解决这个问题的方法——一种我可以搜索和跟踪适合我的技能组合的项目的方法。

让我们承认一件事：与谷歌不同，在 GitHub 上搜索并不容易。但作为一个开发者，你有可能每天都会与 GitHub 或 GitLab 打交道。

现在的问题不是你用这些版本控制系统做什么，而是你如何使用它们。就像掌握谷歌搜索技巧对任何普通互联网用户来说都是必不可少的，我相信对于开发者来说，学会如何有效地在 GitHub 搜索也是至关重要的。

在这篇文章中，我们将看看可以用来正确地在 GitHub 搜索的不同技巧。你将学习如何通过搜索：

• 问题（issues）和拉取请求（pull requests）
• 仓库（repositories）
• 用户（users）
• 主题（topics）

以及更多。让我们开始吧。

GitHub 搜索查询

为了在互联网上找到关于某件事情的详细信息，你需要有正确的搜索技巧。这在 GitHub 上没有任何不同——要找到详细的信息，你可以利用常见的过滤、排序和搜索技术，轻松找到特定项目的 issues 和 pull requests。

即使你能在互联网上找到许多不同项目的资源，但当你想自己进行搜索时，主要问题就来了：你该如何开始？你应该使用哪些关键词来找到正确的结果？

大多数维护者倾向于用 issues 来标记他们的项目，这使得贡献者更容易找到合适的项目。下面列出了一些在使用 GitHub 时可能会对你有所帮助的小技巧。

如何在 GitHub 上搜索 issues 和 pull requests

搜索 issues 和相关的 pull requests，是寻找要贡献的项目的最常见的方法之一。这里有一些技巧，你可以用来轻松找到可靠的答案：

1、is:issue is:open label:beginner——这个特别的查询会列出所有具有开放的、并标有 beginner 的 issues 的项目。

2、is:issue is:open label:easy——这将列出所有被标记为 easy 的开放 issues。

3、is:issue is:open label:first-timers-only——这将列出所有欢迎第一次做贡献的人们的开放 issues。

4、is:issue is:open label:good-first-bug——这将列出带有 good-first-bug 标签的开放 issues 的项目，以吸引贡献者为其工作。

5、is:issue is:open label:"good first issue"——这将列出所有带有 good first issue 标签的开放 issues，意味着它是初学者入门的好地方。

6、is:issue is:open label:starter——这将列出整个 GitHub 中所有标有 starter 的开放 issues。

7、is:issue is:open label:up-for-grabs——这将列出开放的 issues，如果你有必要的技能，就可以进行工作。

8、no:project type:issue is:open——这将列出所有没有分配给特定项目的开放 issues。

9、no:milestone type:issue is:open——很多时候，项目是用里程碑来追踪的。但如果你想找到没有被跟踪的 issues，这个搜索查询将为你列出这些项目。

10、no:label type:issue is:open——这将列出所有没有标签的开放 issues。

11、is:issue is:open no:assignee——这显示所有尚未分配给某人的开放 issues。

如何搜索仓库

默认情况下，要进行搜索，你需要在搜索栏中输入仓库的名称，然后就可以得到一些搜索结果。

但你找到你想要的仓库的机会非常低。

让我们看看有什么方法可以缩小搜索范围：

如何通过名称、描述/README 查找

当你通过 README 文件的名称和描述进行搜索时，需要注意的是，你的搜索短语应该以 in 限定词开始。这样就可以在你要找的东西的“内部”进行搜索。

示例

• 使用 in:name。比方说，你正在寻找资源，以了解更多关于数据科学的信息。在这种情况下，你可以使用 Data Science in:name 命令，它将列出仓库名称中含有 Data Science 的仓库。
• 使用 in:description。如果你想找到具有特定描述的仓库，例如，仓库的描述中包含 “freeCodeCamp” 一词，我们的搜索将是：freecodecamp in:description。
• 使用 in:readme。你用它来搜索一个文件的 README 中的某一短语。如果我们想找到 README 中包含 freecodecamp 这个词的仓库，我们的搜索将是：freecodecamp in:readme。
• 使用 in:topic。你用它来查找某个短语或单词是否被标注在主题中。例如，要找到所有在主题中列出 freecodecamp 的仓库，我们的搜索将是：freecodecamp in:topic。

你也可以结合多个搜索查询，进一步缩小搜索范围。

如何按 Stars、Forks 查找

你也可以根据项目的 star 和 fork 的数量来搜索仓库。这使你更容易知道该项目有多受欢迎。

示例

• 使用 stars:n。如果你搜索一个有 1000 star 的仓库，那么你的搜索查询将是 stars:1000。这将列出正好有 1000 star 的仓库。
• 使用 forks:n。这指定了一个仓库应该有的 fork 数。如果你想找到少于 100 个 fork 的仓库，你的搜索将是：forks:<100。

你可以随时使用关系运算符，如 <、>、<=、>= 和 .. 来帮助你进一步缩小搜索范围。

如何按语言查找

在 GitHub 上搜索的另一个很酷的方法是按语言搜索。这可以帮助你过滤出特定语言的仓库。

示例

• 使用 language:LANGUAGE。例如，如果你想找到用 PHP 编写的仓库，你的搜索将是：language:PHP。

如何按组织名称查找

你也可以搜索由一个特定组织维护或创建的仓库/项目。为此，你需要用关键词 org:... 来开始你的搜索，然后是组织名称。

例如，如果你搜索 org:freecodecamp，它将列出与 freeCodeCamp 相匹配的仓库。

如何按日期查找

如果你希望你的结果基于一个特定的日期，你可以使用这些关键词之一进行搜索：created、updated、merged 和 closed。这些关键词应该伴随着格式为 YYYY-MM-DD 的日期一起使用。

示例

• 使用 keyword:YYYY-MM-DD。举个例子，我们想搜索所有在 2022-10-01 之后创建的带有 freeCodeCamp 这个词的仓库。那么我们的搜索将是：freecodecamp created:>2022-10-01。

你也可以使用 <、>、>= 和 <= 来搜索指定日期之后、之前和指定日期的日期。要在一个范围内搜索，你可以使用 ...。

如何通过许可证查找

当你在寻找一个可以贡献的项目时，许可证是非常重要的。不同的许可证对贡献者可以做什么或不可以做什么给予不同的权利。

为了使你更容易找到有正确许可证的项目，你需要对许可证有一个很好的了解。你可以在这里阅读更多关于它们的信息。

示例

• 使用 license:LICENSE_KEYWORD。这是一个搜索具有特定许可证的项目的好方法。例如，要搜索具有 MIT 许可证的项目，你可以使用 license:MIT。

如何按可见度搜索

你也可以根据仓库的可见性来进行搜索。在这种情况下，你可以使用 public 或者 private。这将分别匹配公共或私人仓库中的 issues 和 pull requests。

示例

• 使用 is:public。这将显示一个公共仓库的列表。让我们举个例子，我们想搜索所有由 freeCodCamp 拥有的仓库。那么我们的搜索将是：is:public org:freecodecamp。
• 使用 is:private。这个查询是为了列出所有在给定的搜索查询下的私有仓库。

总结

尽管我们在这里已经涵盖了许多搜索查询，但你总是可以发挥创意，将多个参数组合在一起，进一步缩小搜索范围。

对于更多的资源和更多的搜索参数，你可以随时参考 GitHub Docs 或利用高级 GitHub 搜索方法。这些方法总是能派上用场，因为它们提供了更多的归档选项。

你可以使用大量的搜索参数，使你在 GitHub 上的日常活动更容易。希望这能帮助你更容易、更有效地使用这个平台。

当你开始一个新的项目时，你可能需要添加多个 linting 工具来美化你的代码并防止简单的错误。

你经常会使用多个 linters，其中一个可能支持 npm 安装，另一个可能有 PyPI 安装，等等。你也会想在你的 CI 中设置一些自动化来运行这些 linters，但这个过程是相当乏味的😫。

在这篇文章中，我将向你展示如何使用 GitHub Super Linter，一个可以解决所有这些问题的单一 linter。我的大部分个人项目也都使用 GitHub Super Linter，我个人发现它是一个大救星。

为什么需要 Linting

Linting 本质上是一种静态代码分析的形式。它根据一些规则来分析你写的代码，以找出风格上或程序上的错误。可以把它看作是一种在软件中标记出可疑用法的工具。

linter 可以通过以下方式帮助你节省大量的时间：

• 防止有破坏性（broken）的代码被推送
• 帮助建立编码的最佳实践
• 建立代码布局和格式的准则
• 帮助代码审查变得更加顺畅
• 标记出你的代码中的语法错误的 bug

鉴于提示工具的作用，你最好在任何代码审查发生之前对推送到你的仓库的每一段代码运行一个 linter。这无疑有助于你写出更好、更可读、更稳定的代码。

下面是一个使用 Black 的例子，这是一个专注于代码格式化的 Python 的提示工具。

GitHub Super Linter 在为你的项目带来这些功能方面可以提供相当大的帮助，轻松而有效。GitHub Super Linter 是一个由多个常用 linters 组成的组合，你可以非常容易地使用。它可以让你为这些 linters 设置自动运行，也可以在一个项目中管理多个 linters！它还有大量的自定义功能。

它还有大量的环境变量的定制功能，可以帮助你根据你的个人仓库定制 Super Linter。

如何在 GitHub Actions 中使用 GitHub Super Linter

Super Linter 主要是为在 GitHub Action 中运行而设计的，这也是我在相当长一段时间内使用它的方式。我们将首先讨论这个问题。为了跟上进度，你应该在你的仓库里创建一个新的 GitHub Action。让我们在.github/workflows/linter.yml 创建一个新文件。

要继续操作，我将假设你知道 GitHub Action 的基本语法。但如果你不知道或需要快速复习，我建议你看一下这个快速入门指南。

怎样创建一个 Action

我们已经有了一个空白文件.github/workflows/linter.yml，现在我们要用补充 Action 相关内容，你可以用它来测试项目。

我们将首先给我们的 action 一个名字（name）。这就是出现在 GitHub Action 状态检查下的内容：

name: Lint Code Base

接下来，让我们为我们的 action 指定触发器。这将控制什么时候应该对你的代码库进行检查的问题。在这里，我们告诉它在每次推送（push）和每次拉取请求时（pull_request）都要运行 lint。

name: Lint Code Base

on: [push, pull_request]

这是另一个非常常用的触发器配置。它只在你向主分支（main 或者 master）发出拉取请求时（pull_request）运行，而不是在向这些分支（master 或者 main 分支）推送时（push）运行。

on:
  push:
    branches-ignore: [master, main]
  pull_request:
    branches: [master, main]

接下来，我们要设置一个 job（作业）。你放在一个作业中的所有组件将按顺序运行。在这里，我们把它看作是步骤，以及每当触发器得到满足时，我们希望它们按照哪个顺序运行。

我们将把这个 job 命名为 Lint Code Base，并要求 GitHub 用最新版本的 Ubuntu 运行我们的 job。

name: Lint Code Base

on: [push, pull_request]

jobs:
  build:
    name: Lint Code Base
    runs-on: ubuntu-latest

你不一定要像我们这里一样使用单一的 runner（ubuntu-latest）。可以选择多个 runner，但在这种情况下，它将以同样的方式在所有种类的 runner 上运行。你使用多个 runner 来测试你的代码，是否可以在多个平台上都能很好地运行。

GitHub Super Linter 在其他机器类型上的工作方式没有任何不同，所以我们只用一个机器类型。

接下来，我们将开始定义我们希望这个工作流程所具有的步骤。我们基本上有两个步骤：

1. 获取对应代码
2. 运行 super linter

获取代码。我们会使用 GitHub 官方的 checkout action。

我们设置 fetch-depth: 0 来获取所有分支和标签的所有历史记录，这对 Super linter 来说是必要的，可以获得修改过的文件列表。如果你没有这样做，就只能获取单个提交。

我们还要给我们的步骤起个名字，并告诉它我们要使用 GitHub 官方仓库中的 action，即 actions/checkout@v3。

name: Lint Code Base

on: [push, pull_request]

jobs:
  build:
    name: Lint Code Base
    runs-on: ubuntu-latest

    steps:

      - name: Checkout Code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

这段代码在 $GITHUB_WORKSPACE 下检出你的仓库，允许工作流（workflow）的其他部分访问这个仓库。我们要检查的版本库是你的代码所在的版本库，最好是同一个版本库。

如何运行 Linter

现在我们要添加运行 linter 的步骤，因为我们的代码已经获取。你可以在运行 Action 时使用环境变量（environment variables）来定制 GitHub Super Linter。

name: Lint Code Base

on: [push, pull_request]

jobs:
  build:
    name: Lint Code Base
    runs-on: ubuntu-latest

    steps:

      - name: Checkout Code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          
   - name: Lint Code Base
        uses: github/super-linter@v4

现在我们将谈谈在经常使用 GitHub 环境变量的例子。

• VALIDATE_ALL_CODEBASE：这控制 Super Linter 对整个代码库进行检查，还是只对该提交的修改进行检查。这些变化是通过git diff发现的，但你也可以改变搜索算法（但我们不会在这篇文章中研究这个问题）。常用配置: VALIDATE_ALL_CODEBASE: true。
• GITHUB_TOKEN：顾名思义，这就是 GitHub 令牌。如果你使用它，GitHub 将显示你使用的每个 linter（我们将很快看到如何做到这一点）作为 UI 上的单独检查。例如，你可以这样写 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}.
• DEFAULT_BRANCH：存储库默认分支的名称。例子: DEFAULT_BRANCH: main。
• IGNORE_GENERATED_FILES：如果你有任何由工具生成的文件，你可以将它们标记为 @generated。如果此环境变量设置为 true，Super Linter 将忽略这些文件。例如， IGNORE_GENERATED_FILES: true。
• IGNORE_GITIGNORED_FILES：从 linting 中排除 .gitignore 中的文件。示例： IGNORE_GITIGNORED_FILES: true。
• LINTER_RULES_PATH：任何 linter 自定义文件应该位于的自定义路径。默认情况下，你的文件应位于 .github/linters/。示例：LINTER_RULES_PATH: /。

这些是你最常使用的一些环境变量，但我们讨论过的还没有一个讨论特定于语言的 linting。

如果你不使用我们讨论的任何环境变量，Super Linter 会自动为你的代码库查找并使用所有适用的 linter。

如何增加特定的 Linters 到 Super Linter

你通常只会对为你的项目使用特定的 linter 感兴趣。你可以使用以下环境变量模式来添加你想要的任何 linter：

VALIDATE_{LANGUAGE}_{LINTER}

你可以在列表中找到这些 Supported Linters 的命名约定。

这里有几个例子，我们指定要使用 Black 对所有 Python 文件进行 lint，对 JavaScript 文件使用 ESLint，对 HTML 文件使用 HTMLHint。

name: Lint Code Base

on: [push, pull_request]

jobs:
  build:
    name: Lint Code Base
    runs-on: ubuntu-latest

    steps:

      - name: Checkout Code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          
   - name: Lint Code Base
        uses: github/super-linter@v4

      - name: Lint Code Base
        uses: github/super-linter@v4
        env:
          VALIDATE_ALL_CODEBASE: true
          VALIDATE_JAVASCRIPT_ES: true
          VALIDATE_PYTHON_BLACK: true
          VALIDATE_HTML: true
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

一旦将其中一个 linter 设置为 true，所有其他 linter 将不会运行。在上面的代码片段中，除了 ESLint、Black 或 HTMLHint 之外的所有 linter 都不会运行。

然而，在这个例子中，我们将单个 linter 设置为 false，所以除了 ESLint 之外的每个 linter 都将在这里运行：

name: Lint Code Base

on: [push, pull_request]

jobs:
  build:
    name: Lint Code Base
    runs-on: ubuntu-latest

    steps:

      - name: Checkout Code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          
   - name: Lint Code Base
        uses: github/super-linter@v4

      - name: Lint Code Base
        uses: github/super-linter@v4
        env:
          VALIDATE_ALL_CODEBASE: true
          VALIDATE_JAVASCRIPT_ES: false
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

如何定制化 Lint Checks

Linter 通常使用配置文件，因此你可以修改 linter 使用的规则。在上面我展示的两个完整示例中，Super Linter 将尝试在 .github/linters/ 下查找任何配置文件。

这些可能是用于配置 ESLint 的 .eslintrc.yml 文件，用于配置 HTMLHint 的 .htmlhintrc 等等。

如果你使用 Python 的 Flake8 linter，以下是配置文件的示例：

[flake8]
max-line-length = 120

你把它保存在.github/linters/.flake8。然后，你将在运行 Flake8 linter 时使用它。你可以在此处找到可以使用的模板配置文件示例。

但是，这里有两个示例说明如何修改此路径：

1. 你所有的 linter 配置文件都在其他目录中

将目录路径添加为环境变量，如下所示：

LINTER_RULES_PATH: configs/

2. 添加配置文件的路径

你还可以将特定 linter 的路径硬编码为环境变量。这是一个例子：

JAVASCRIPT_ES_CONFIG_FILE: configs/linters/.eslintrc.yml

如何在 GitHub Actions 之外运行 Super Linter

GitHub Super Linter 是为在 GitHub Actions 中运行而构建的。但是在本地或其他 CI 平台上运行它可能特别有用。你可以本地任何其他 CI 平台上一样运行 Super Linter。

如何在本地运行 Super Linter

你首先要使用此命令从 DockerHub 中获取最新的 Docker 容器：

docker pull github/super-linter:latest

为了运行这个容器，你可以运行以下命令：

docker run -e RUN_LOCAL=true -e USE_FIND_ALGORITHM=true VALIDATE_PYTHON_BLACK=true -v /project/directory:/tmp/lint github/super-linter

请注意这里的几件事：

• 我们用RUN_LOCAL标志运行它，以绕过一些 GitHub action 检查。这将自动设置 VALIDATE_ALL_CODEBASE 为 true。
• 我们将本地代码库映射到/tmp/lint，这样 linter 就能接收到代码。
• 当然，我们设置环境变量的方式是不同的，但运行 GitHub Super Linter 的整体过程是相同的。

如何在其他 CI 平台上运行 Super Linter

在其他 CI 平台上运行 GitHub Super Linter 与在本地运行 GitHub Super Linter 非常相似。下面是 Tao Yang 在 Azure Pipelines 中运行它的一个例子。

- job: lint_tests
  displayName: Lint Tests
  pool:
    vmImage: ubuntu-latest
  steps:
  - script: |
      docker pull github/super-linter:latest
      docker run -e RUN_LOCAL=true -v $(System.DefaultWorkingDirectory):/tmp/lint github/super-linter
    displayName: 'Code Scan using GitHub Super-Linter'

这只是把我们在本地运行 Super Linter 的命令作为一个脚本来运行。你可以在其他 CI 平台上以完全相同的方式运行它。

总结

谢谢你坚持到最后。我希望你能从 GitHub Super Linter 的使用中得到一两点启发。它无疑是我最喜欢的开源项目之一。

如果你学到了新的东西，或者喜欢读这篇文章，请分享出去，让别人看到。我们在下一篇文章中再见吧！

你也可以在 Twitter 上找到我，@rishit/_dagli，我在那里发布关于开源和机器学习的推文。

版本控制系统是一种用于跟踪、执行和管理软件代码更改的工具。它也称为源代码控制。

版本控制系统可帮助开发人员存储他们在不同阶段对文件所做的每项更改，以便他们和团队成员可以在以后检索这些更改。

有三种类型的版本控制系统，它们是：

• 本地版本控制系统
• 集中式版本控制系统
• 分布式版本控制系统

什么是本地版本控制系统（LVCS）？

这是一种非常常见且易于使用的版本控制系统。但是这种方法很容易出错和受到攻击，因为文件存储在你的本地系统中。

这意味着你可能会丢失系统文件或意外忘记你正在操作的文件的目录/文件夹（然后写入另一个目录）。

什么是集中式版本控制系统（CVCS）？

在这种类型的版本控制中，服务器充当存储每个版本代码的仓库。 CVCS 帮助不同的开发人员一起协作。

尽管开发人员之间进行了有益的协作和沟通，但如果服务器出现几秒钟的故障或损坏，你就有可能丢失资料。不幸的是，这是 CVCS 的一个非常大的问题。

在 CVCS 中，只有少数开发人员可以在一个项目上一起工作。

什么是分布式版本控制系统（DVCS）？

这是现在最新和最常用的版本控制系统类型。

在 DVCS 中，所有开发人员都拥有服务器中所有数据的完整备份（克隆）。这意味着无论何时服务器关闭或出现故障，你仍然可以处理你的项目，你可以将仓库复制或备份到服务器以恢复它们。

当你使用 DVCS 时，许多开发人员可以在一个项目上一起工作。一种流行的 DVCS 是 Git，我们现在将对其进行更多讨论。

什么是 Git？

Git 是一个免费的开源分布式版本控制系统，你可以使用它来跟踪文件中的更改。你可以在 Git 中处理所有类型的项目。

使用 Git，你可以将更改添加到代码中，然后在准备好时提交（或保存）它们。这意味着你还可以返回之前所做的更改。

开发者常将 Git 与 GitHub 一起使用——那么 GitHub 是什么？

什么是 GitHub？

GitHub 是一个 Web 界面，你可以在其中存储 Git 仓库并有效地跟踪和管理你的更改。它使操作同一项目的各种开发人员可以访问代码。你可以在其他开发人员进行更改的同时对项目进行自己的更改。

如果你在进行更改时不小心弄乱了项目中的某些代码，你可以轻松地回到尚未发生混乱的上一个阶段。

为什么使用 GitHub？

你应该学习和使用 GitHub 的原因有很多。现在让我们来看看其中的几个。

高效的项目管理

GitHub 是存储 Git 仓库的地方。GitHub 使从事同一项目但在不同位置的开发人员可以轻松地在同一页面上工作。

使用 GitHub，你可以轻松跟踪和管理你所做的更改，并检查你在项目中所做的进度。

轻松协作与合作

借助 GitHub，来自世界各地的开发人员可以在一个项目上协同工作，而不会遇到任何问题。

团队在共同处理项目时能够保持一致，并且可以轻松有效地组织和管理项目。

开源

GitHub 是一个免费的开源系统。这意味着开发人员可以轻松访问不同类型的代码/项目，他们可以使用这些代码/项目来学习和发展自己的技能。

多功能性

GitHub 的这个属性非常重要。 GitHub 不仅仅是开发人员的 Web 界面，设计师、写作者和任何想要跟踪其项目历史的人都可以使用它。

如何设置 Git？

要开始使用 Git，你需要先将它下载到你的计算机（如果你还没有的话）。你可以通过访问他们的官方网站来执行此操作。

当 Git 打开时，向下滚动一点，你应该会看到一个下载按钮，继续并单击它。

选择你的操作系统，无论是 Windows、MacOS、Linux/Unix。就我而言，我将选择 Windows 选项，因为我使用的是 Windows 计算机：

单击页面顶部的第一个链接以下载最新版本的 Git。

下载完成后，继续将 Git 安装到你的计算机上。你需要转到下载文件的位置并安装它。
安装后，你需要确保 Git 已成功安装在你的系统上。打开命令提示符或 Git bash（无论你选择使用哪个）并运行命令：

git --version

如果 Git 已成功安装在你的计算机上，它应该会在你刚刚运行的命令下方显示当前版本的 Git。如果显示了当前版本，恭喜你！

如何配置 Git？

现在我们已经在计算机上安装了 Git，我们必须对其进行配置。这样做是为了在任何时候我们在一个项目的团队中工作时，都可以轻松地识别我们在仓库中所做的提交。

要配置 Git，我们需要使用 git config --global 命令指定名称、电子邮件地址和分支，例如：

从上图中，我们使用 git config --global user.name 来配置用户名。就我而言，我使用了我的名字 “Derek Emmanuel”。这同样适用于 git config --global user.email。

Git 有一个默认的 master 分支，所以我使用 git config --global init.default branch main 命令将其更改为主分支。

现在你已准备好开始使用 Git。

如何设置 GitHub 账户？

要设置 GitHub 账户，请访问他们的官方网站，点击右上角的注册按钮：

当注册表单打开时，输入你的电子邮件，创建密码，输入你的用户名，然后在单击创建账户按钮之前验证你的账户。

常用的 Git 命令

每个开发人员都应该知道如何使用一些基本的 Git 命令：

• git config
• git init
• git add
• git commit
• git clone
• git push
• git rm
• git branch

让我们简要介绍一下这些，以便你知道如何使用它们。

如何使用 git config 命令

你可以使用此命令设置用户的用户名、电子邮件和分支，以便在处理项目时识别谁进行了提交。当你将 Git 下载到你的计算机中并且想要自定义它以供你使用时，将使用此命令。

例如：

git config --global user.name “ [username]”

git config --global user.email [email address]

如何使用 git init 命令

你可以使用 git init 命令在项目中启动 Git。当你正在处理项目并希望将 Git 初始化到项目以跟踪项目中所做的更改时，将使用此 Git 命令。

例如：

git init

当你运行此命令时，你应该会看到在你正在处理的当前文件夹中自动创建了一个名为 .git 的文件夹。

如何使用 git add 命令

此命令将你的文件添加到暂存区。暂存区域是添加我们对其进行更改的文件以及它们等待下一次提交的区域。

要将文件添加到暂存区域，请使用 git add 命令。它将文件夹中的所有文件添加到暂存区域。

git add (file name) 添加你想在暂存区提交的特定文件的名称。

当你对文件进行更改并希望将它们提交到你的项目时，请使用此命令。

如何使用 git commit 命令

这将提交你使用 git add 命令添加的任何文件以及暂存区域中的每个文件。

例如：

git commit –m “first commit”

此命令将文件永久保存到 Git 仓库。只要使用 git add 命令将文件添加到暂存区，就可以使用它。

如何使用 git clone 命令

你使用 git clone 命令将另一个位置的已有的仓库复制到你想要的当前位置。

例如：

git clone (repository name)

当你想要将 Git 仓库从 GitHub 复制到本地仓库时，你可以使用此命令。

如何使用 git push 命令

你可以使用此命令将文件从本地仓库上传/推送到另一个仓库，例如 GitHub 等远程仓库。

例如：

git push (remote storage name)

仅当你对项目所做的更改和提交感到满意并最终希望将其上传/推送到 GitHub 中的 Git 仓库时，才使用此命令。

如何使用 git rm 命令

你可以使用此 Git 命令从工作仓库中删除文件，例如：

git rm (filename)

仅当你希望从 Git 仓库中删除不需要的更改/文件时，才使用此命令。

如何使用 git branch 命令

你使用此命令来检查你正在处理的当前分支，例如：

git branch

此命令可帮助你了解你正在处理的当前分支。

总结

在本教程中，你了解了版本控制系统的全部内容。你还学习了如何在计算机上安装和设置 Git 以及设置 GitHub 账户。最后，我们浏览了一些常用的 Git 命令。

如果你想更深入地了解 Git 和 GitHub，可以在 freeCodeCamp YouTube 频道上查看本课程。

希望本教程对你有所帮助。

祝你编程愉快！

大家好！在本文中，我们将学习如何将 GitHub Copilot AI 工具与 Visual Studio Code 结合使用。

GitHub Copilot 是什么

GitHub Copilot 是一个可以帮助你更简单、更快速地编写代码的工具，由 GPT-3 提供支持。你只需编写所需代码的描述——例如，编写一个函数来生成一个随机数，或对一个数组进行排序——Copilot 就会为你创建它。

它不只是创建一种解决方案，而是创建多个，你可以选择你想要的一个。

在本教程中，我们将学习如何为 Visual Studio Code 设置 GitHub Copilot AI 工具，以及如何生成 JavaScript、React 和 HTML 代码。

如何安装 GitHub Copilot

要添加 GitHub Copilot，请打开你的 GitHub 并转到设置。

在左侧菜单中选择 GitHub Copilot 并勾选 Allow 以启用它，然后单击 Save 按钮以保存。

现在打开 Visual Studio Code 并转到 Extensions（扩展），在搜索栏中搜索 GitHub Copilot。

安装 Github Copilot，并重新启动你的 Visual Studio Code。

在底部，你会看到 GitHub Copilot 已被激活。

但请记住，我们目前只有试用版。而且它只有两个月的有效期——免费试用版将于 8 月 22 日结束。试用结束后，我们必须购买完整版。

每月花费 10 美元，或每年 100 美元。

现在我们已经安装了 Copilot，让我们开始使用它的更有趣的部分。

如何使用 GitHub Copilot 生成 JavaScript 代码

让我们从简单的事情开始。让我们创建一个函数来添加两个数字。

在 JavaScript 文件中，只需写一个注释，例如 “Generate a function to add two numbers（生成一个函数以将两个数字相加）”。

//Generate a function to add two numbers

然后按 Enter 键，它会向你抛出建议，你可以通过按 Tab 键接受这些建议。

//Generate a function to add two numbers
function add(a, b) {

然后按 Enter 键进入下一行，当出现下一行代码时，再次按 Tab。

//Generate a function to add two numbers
function add(a, b) {
  return a + b;
}

这是添加两个数字的函数。

现在让我们调用函数 add()。编写函数调用，它会自动接受一些随机参数。

我们还可以对数字进行减法、乘法和除法。

如何使用 GitHub Copilot 生成函数以在数组中显示彩虹的颜色

我们将从注释 “Generate an array of all the colors from the rainbow（从彩虹中生成所有颜色的数组）”开始。

//Generate an array of all the colors from the rainbow

然后就像之前一样，我们将按 Enter 键。

它将生成彩虹中所有颜色的数组。

//Generate an array of all the colors from the rainbow
var colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet'];

如何使用类型 Number、String 和 Boolean 创建三个数组并将它们合并到一个对象中

现在让我们尝试创建一个包含数字、字符串和布尔值的数组。

//Create an array of numbers
var numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

//Create an array of strings
var strings = ["hello", "world", "how", "are", "you"];

//Create an array of booleans
var booleans = [true, false, true, false, true];

现在，让我们将它们合并到一个对象中。我们将创建一个像这样的对象：

var objects = [
    {
        number: 1,
        string: "hello",
        boolean: true
    },
    {
        number: 2,
        string: "world",
        boolean: false
    },
    {
        number: 3,
        string: "how",
        boolean: true
    },
]

写一条注释 “Create an array of objects with the above array items as key value pairs（创建一个对象数组，将上述数组项作为键值对）”。

你可以按 Tab 键接受解决方案，或按 CTRL + Enter 键打开 Copilot 解决方案页面。

你可以接受任何你想要的解决方案。只需单击 Accept 以接受。

//Create an array of numbers
var numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

//Create an array of strings
var strings = ["hello", "world", "how", "are", "you"];

//Create an array of booleans
var booleans = [true, false, true, false, true];

//Create an array of objects with the above array items as key value pairs
var objects = [
  {
    number: 1,
    string: "hello",
    boolean: true,
  },
  {
    number: 2,
    string: "world",
    boolean: false,
  },
  {
    number: 3,
    string: "how",
    boolean: true,
  },
  {
    number: 4,
    string: "are",
    boolean: false,
  },
  {
    number: 5,
    string: "you",
    boolean: true,
  },
];

如何在 React 和 Express 中导入东西

现在让我们尝试看看 React 和 Express 是如何工作的。

我们将简单地导入一些模块。

让我们首先从 React 中导入 useState Hook。

//Import useState Hook from react

写下注释，然后按 Enter 键，Copilot 将生成代码。

//Import useState Hook from react
import React, { useState } from 'react';

让我们再试一试从 React 中导入 useEffect 和 useState Hooks。

//Import useState and useEffect hook from react
import React, { useState, useEffect } from 'react';

让我们在 Express 中做点什么。在 Express 中导入 CORS npm 包，它是为 Node 和 Express 制作的。它会在这里。

//Import cors from express
const cors = require('cors');

如何生成 HTML 代码

让我们尝试一些 HTML 代码。

首先，让我们生成一些代码来创建一个无序列表，其中包含 Nishant、25 和 Patna。

Create an ul tag with list items Nishant, 25, and Patna
    <ul>
      <li>Nishant</li>
      <li>25</li>
      <li>Patna</li>
    </ul>

让我们尝试相同的方法，但列表样式为 none。

Create an ul tag with the list having a class of lists and the items
    Nishant, 25, and Patna and the list style as none
    <ul class="lists" style="list-style: none">
      <li>Nishant</li>
      <li>25</li>
      <li>Patna</li>
    </ul>

就是这样，很神奇吧？

总结

在本文中，你了解了 GitHub Copilot 是什么以及如何使用它。

你还可以查看我关于同一主题的视频，即 Let's Test the GitHub Copilot - GitHub Copilot Tutorial with Visual Studio Code。

感谢你阅读本文。祝你学习愉快！

GitHub 是一个很棒的应用程序，可以帮助你管理你的 Git 仓库。你也可以用它来为开源生态系统做贡献，与其他贡献者合作。

GitHub 上的公共仓库经常会得到很多贡献者的关注，这有助于提高项目的水平。

那么如何才能轻松地在公共仓库中工作呢？仓库 forking 工具可以让贡献者在本地复制源代码仓库，并做任何他们想做的修改。

但如果你作为一个初学者要使用这个工具，你需要了解仓库复刻的工作流程，这样你就可以无缝地与其他公共仓库合作。

在这篇文章中，我们将通过实际的例子和故事来学习如何复刻一个仓库。如果你喜欢通过视频学习，也可以看这个 YouTube 视频：

什么是 GitHub 仓库复刻？

假设你喜欢在一个特定的框架或库上工作，比如 React.js。有一天，你想出了一个办法，可以自己增强 React 的功能。

React 的源代码在 GitHub 上以公共仓库的形式提供，所以你可以通过复刻来制作它的本地拷贝。

一旦你得到了代码的本地拷贝，你可以进行相关的修改，并要求 React 社区审查你的修改。

在审查了你的代码修改后，React 社区可能会批准它们，或者要求你做更多的修改。他们很有可能在批准（approval）后接受你的代码修改。

所以，让我们通过两个开发者 Tom 和 Hari 的故事来了解整个复刻工作流程。

完整的复刻工作流

Tom 和 Hari 是两个拥有各自 GitHub 账户的开发者。Tom 正在做一个优秀的项目，他在一个名为 /tom/repo 的公共仓库中管理其源代码。Hari 对这个想法感到惊奇，想为这个项目做出贡献。

现在，Hari 有两种方法。

• Hari 问 Tom：“嘿，Tom，我想为你的项目做贡献。你能不能把我加为贡献者？” Tom 可能同意也可能不同意。由于该项目已经作为仓库提供，他可能只是要求复刻并使用它。
• 第二种方式是 Hari 自己 fork 这个仓库并开始工作。他不需要等着和 Tom 谈，让 Tom 把他加为贡献者。

这第二种直接复刻仓库的方法对任何贡献者来说都更方便。那么它是如何工作的呢？让我们分步骤来了解一下工作流程。

1. Hari 复刻仓库 /tom/repo。我们称 /tom/repo 仓库为上游仓库。
2. 仓库现在可以在 Hari 的 GitHub 账户中以 /hari/repo 的形式使用。我们称 hari/repo 为复刻仓库（Forked Repository）。同时，它也是上游仓库的一个完全拷贝。这个仓库完全脱离了 Tom 的仓库，Hari 可以开始做任何他想做的修改。Hari 首先会克隆仓库，并开始进行修改。
3. Hari 做好所需的修改，并将修改推送（push）到上游仓库中。
4. 最后，Hari 创建一个从自己的仓库到上游仓库的拉取请求（Pull Request）。Tom 在他方便的时候审查该拉取请求，如果一切顺利，就批准（approve）并合并（merge）它。

这就是整个工作流程——通过简单而直接的方式来为公共仓库做贡献。一图胜千言，下面是我们讨论的工作流程的演示。

如何在 GitHub 中复刻一个仓库

复刻一个仓库只需点击一个按钮。

要跟着做，请浏览你想复刻的公共仓库。在页面的右上方，你会发现 Fork 按钮。点击该按钮并等待几秒钟，你会看到，新复刻的仓库会在你的 GitHub 账户下创建。

在复刻仓库后，按照我们上面学到的步骤开始贡献。

我们来练习复刻

作为一个新手，你想通过练习复刻来增强信心吗？让我们来做吧。你可以执行这些任务来练习复刻。

• 打开这个公共仓库：https://github.com/atapas/fork-me
• 创建一个与你的 GitHub 用户名相同的文件夹（对我来说是 atapas）
• 在该文件夹中添加一个 Readme.md 文件，内容可以是你选择的任何文字
• 在上游创建一个拉动请求 Pull Request。如果一切顺利，我将审查并合并它

如果你出错了，不要担心，继续尝试，你会成功的。这将是一个为开源仓库做贡献的练习场。

总结

• Git 是一个在开发者社区中被广泛使用的版本控制工具。如果你是 Git 的初学者，可以在这里了解它。
• GitHub 是一个流行的管理 Git 仓库的应用程序。任何人都可以为公共仓库做出贡献。
• 复刻是一个很好的工具，可以把别人仓库里的源代码复制到你的仓库里，并对其进行贡献。
• 学习并使用复刻的工作流程是很简单的。

结束之前......

我希望你觉得这篇文章有帮助。请练习复刻并为开源项目做出贡献。如果你想进一步讨论，可以在 Twitter 上联系我。

我也会在这些平台上分享我在 JavaScript、Web 开发、职业和博客方面的学习成果：

• 在 Twitter 上关注我
• 订阅我的 YouTube 频道
• GitHub 上的副业项目

Git 和 GitHub 是各个领域的开发者都应该学习的两项技术。

如果你是一个初级开发者，你可能会认为这两个术语意味着同样的事情--但它们是不同的。

本教程将帮助你了解什么是 Git 和版本控制，你需要知道的基本 Git 命令，如何使用其功能来提高工作效率，以及如何使用 GitHub 来扩展这些功能。

本指南对初学者友好，因为例子将非常容易理解。它也将是一个通用的教程，所以不管你最喜欢的编程语言是什么，你都可以跟着学。

对于我们的项目，我们将做一个写在文本（txt）文件中的待办事项清单。你将看到我们如何使用 Git 的功能来工作，并创建列表的最终版本。

你需要先准备好的

为了完成本教程，你将需要以下条件：

• 一个命令行界面（或者说是终端）
• 一个你喜欢的文本编辑器（我将使用 VS Code）
• 一个 GitHub 账户

什么是 Git

Git 是一个版本控制系统，可以让你跟踪你对文件所做的修改。使用 Git，你可以恢复到文件的各种状态（就像一台时间旅行机）。你也可以制作一个文件的副本，对该副本进行修改，然后将这些修改合并到原来的副本中。

例如，你可以在一个网站的登陆页面上工作，发现你不喜欢这个导航栏。但与此同时，你可能不想开始改变它的组件，因为它可能会变得更糟。

有了 Git，你可以为该文件创建一个相同的副本，然后对导航栏进行修改。然后，当你对你的改动感到满意时，你可以把副本合并到原文件中。

你并不局限于将 Git 仅仅用于源代码文件，你也可以用它来跟踪文本文件，甚至是图像。这意味着，Git 不仅仅是为开发者服务的，任何人都可以找到它的帮助。

如何安装 Git

为了使用 Git，你必须在你的电脑上安装它。要做到这一点，你可以在官方网站 下载最新版本。你可以从给出的选项中下载适合你的操作系统。

你也可以用命令行来安装 Git，但由于每个操作系统的命令都不一样，我们将专注于更通用的方法。

如何配置 Git

我将假设此时你已经安装了 Git。为了验证这一点，你可以在命令行上运行这个命令：git --version。这将显示当前安装在你电脑上的版本。

接下来，你需要做的是设置你的用户名和电子邮件地址。Git 会使用这些信息来识别谁对文件进行了修改。

要设置你的用户名，输入并执行这些命令：git config --global user.name "YOUR_USERNAME" 和 git config --global user.email "YOUR_EMAIL"。请确保用你选择的值替换 "YOUR_USERNAME" 和"YOUR_EMAIL"。

如何在 Git 中创建和初始化一个项目

我们终于完成了安装和设置 Git 的工作，现在是时候创建我们的项目了。

我在桌面上创建了一个名为 Git and GitHub tutorial的文件夹。使用命令行，进入到你新项目的文件夹位置。对我来说，我将运行以下命令：

cd desktop

cd Git and GitHub tutorial

如果你是命令行的新手，并且还在学习如何使用它来查看你的电脑文件夹，那么我建议使用微软的 Visual Studio Code。它是一个代码编辑器，有一个内置的终端来执行命令。你可以下载它 这里。

安装VS Code后，在编辑器中打开你的项目，为你的项目打开一个新的终端。这将自动把终端/命令行指向你的项目的路径。

现在要初始化你的项目，只需运行git init。这将告诉 Git 准备好开始监视你的文件的每一个变化。它看起来像这样：

git init

第一行是关于我的电脑的信息和文件夹存在的路径。第二行是命令git init，第三行是发回的响应，告诉我我的仓库（repo）已经被初始化了。它被认为是空的，因为我们还没有告诉 Git 要追踪哪些文件。

仓库只是定义一个被 Git 监视/跟踪的项目的另一种方式。

Git 项目文件

我只创建了一个名为 "todo.txt "的文件。这个文件看起来是这样的：

MY TO-DO LIST

1. Write an article.
2. Code.
3. Study books.
4. Attend classes on time.
5. Visit aunt.
6. Apply for remote jobs. 

在我们继续学习其他 Git 命令之前，让我们先谈谈 GitHub。

什么是 GitHub

GitHub 是一个为 Git 存储库提供的在线托管服务。想象一下，你在家里做一个项目，当你不在的时候，也许是在朋友那里，你突然想起了一个代码错误的解决方案，让你几天都坐立不安。

你不能进行这些修改，因为你的电脑不在你身边。但如果你的项目托管在 GitHub 上，你就可以在你能接触到的任何电脑上用命令访问和下载该项目。然后你就可以进行修改，并将最新版本推送回 GitHub。

总之，GitHub 可以让你在他们的平台上存储你的 repo。GitHub 的另一个了不起的功能是你可以在任何地方与其他开发者进行合作。

现在我们已经在本地创建并初始化了我们的项目，让我们把它推送到 GitHub。

如果你是初学者，你会遇到一些新的术语，比如推送（push）、提交（commit）、添加（add）等等——但不要被它们吓倒，只要多加练习，你就能记住这些术语和它们的作用。

如何推送一个仓库到 GitHub

我将把本节分为几个步骤，以帮助你更清楚地了解这个过程。

第一步 - 创建一个 GitHub 账户

为了能够使用 GitHub，你必须先创建一个账户。你可以在他们的[网站]（https://github.com/) 创建。

第二步 - 创建一个存储库

你可以点击页面右上角的+符号，然后选择 “New repository”。给你的版本库起个名字，然后向下滚动并点击 “Create repository”。

第三步 - 添加和提交文件

在我们添加（add）和提交（commit）我们的文件之前，你需要了解一个文件被 Git 跟踪的阶段。

已经提交的状态

当一个文件的所有修改都被保存在本地的 repo 中时，该文件就处于提交的（committed） 状态。处于提交阶段的文件是可以被推送到远程 repo（在 GitHub 上）的文件。

已修改状态

处于修改（modified） 状态的文件已经做了一些修改，但还没有保存。这意味着该文件的状态与之前在提交状态下的状态有了改变。

暂存状态

处于暂存（staged） 状态的文件意味着它可以被提交了。在这种状态下，所有必要的修改都已经完成，所以下一步就是把文件移到提交状态。

你可以把 Git 想象成一台摄像机，这样就能更好地理解。只有当文件到达提交状态时，相机才会进行快照。在这个状态之后，相机开始比较正在对同一文件进行的修改和最后一次快照（这就是修改状态）。而当所需的修改完成后，文件就会被分阶段移动到提交状态，以便进行新的快照。

目前，这可能是一个很大的信息量，但不要气馁——随着实践的进行，它变得更容易。

如何在 Git 中添加文件

当我们第一次初始化我们的项目时，该文件没有被 Git 追踪到。要做到这一点，我们使用这个命令git add .，将添加当前目录下所有文件。如果你想添加一个特定的文件，也许是一个名为about.txt的文件，你可以用git add about.txt。

现在，我们的文件已经处于暂存状态（staged state）。这条命令之后你不会得到回应，但要知道你的文件处于什么状态，你可以运行git status命令。

如何在 Git 中提交文件

文件下一个状态处于提交状态（committed state）。为了提交我们的文件，我们使用git commit -m "first commit"命令。

命令的第一部分 "git commit "告诉 Git，所有被暂存的文件都准备好提交了，所以是时候进行快照了。第二部分 -m "first commit" 是提交信息。-m是信息的缩写，而括号内的文字是提交信息。

执行这个命令后，你应该得到一个类似这样的响应：

git commit

现在我们的文件已经处于提交状态（committed state）。

第四步 - 推送仓库到 GitHub

创建完仓库后，你的浏览器应该跳到一个页面，告诉你如何在本地创建一个仓库或推送一个现有仓库。

在我们的例子中，项目已经存在于本地，所以我们将使用 “.…or push an existing repository from the command line” 部分的命令。这些是命令：

git remote add origin https://github.com/ihechikara/git-and-github-tutorial.git
git branch -M main
git push -u origin main

第一个命令 git remote add origin [https://github.com/ihechikara/git-and-github-tutorial.git](https://github.com/ihechikara/git-and-github-tutorial.git)，在你的本地 repo 和 Github 上的远程 repo 之间建立连接。

你的远程项目的 URL 应该与上面的完全不同。所以要根据你的实际 URL，确保你是按照步骤，用你自己的远程 repo 工作。执行这个命令后，你通常不会得到回应，但要确保你有互联网连接。

第二个命令 git branch -M main 将主分支的名字改为 "main"。默认的分支可能被创建为 "master"，但 "main "是现在这个 repo 的标准名称。这里通常没有回应。

最后一个命令 git push -u origin main 将你的 repo 从本地设备推送到 GitHub。你应该得到与此类似的回应：

git push

为了帮助你加深对文件阶段的理解，我将对文件进行修改，然后将新版本推送到 GitHub。

回顾一下，我们的文件现在处于提交状态。让我们对文件进行修改，并注意到这些状态。

我将在待办事项列表中添加一个新任务：

MY TO-DO LIST

1. Write an article.
2. Code.
3. Study books.
4. Attend classes on time.
5. Visit aunt.
6. Apply for remote jobs. 
7. Practice code

添加新任务后，运行git status命令。你应该看到这样的情况：

git status

在对文件进行修改后，它移到了修改状态--但它还没有被分期提交，所以你还不能把它推送到 GitHub。Git 并没有对这个当前状态进行最终的快照，因为它只是将我们现在所做的修改与最后的快照进行比较。

现在我们要添加（stage）这个文件，然后提交（commit ）并推送（push）它。这与上一节的做法相同。

我们首先使用git add .添加文件，它添加了当前目录下的所有文件（在我们的例子中是一个文件）。然后我们通过运行git commit -m "added new task"来提交该文件，接着是git push -u origin main。

这就是将修改过的文件推送到 GitHub 的三个步骤。添加（add），提交（commit），然后推送（push）。我希望你现在理解了文件阶段和与之相关的命令。

如何在 Git 中使用分支（branch）

有了分支，你可以在不破坏原始副本的情况下，创建一个你想要处理的文件副本。你可以把这些修改合并到原始副本上，或者让分支保持独立。

在我们开始使用分支之前，我想给大家看一下我们的 repo 的可视化表示，它看起来像这样：

main banch

上图显示了我们的主分支和最近的两次提交（第一次提交和添加的新任务提交）。

在这一点上，我想在列表中添加更多的任务，但我还不确定是否要把它们放在主列表中。因此，我将创建一个名为 test 的新分支，看看加入更多任务后我的列表会是什么样子。

要创建一个新的分支，运行这个命令。git checkout -b test。我将把它分开来。

checkout告诉 Git 它应该切换到一个新的分支。b告诉 Git 创建一个新的分支。test是要创建和切换到的分支的名字。以下是你应该得到的响应：

git checkout -b

现在我们已经创建了一个新的分支，这就是我们的 repo 的样子：

git branch

我们从上次提交的状态中创建了新的分支。现在让我们为这个新分支添加更多任务。

MY TO-DO LIST

1. Write an article.
2. Code.
3. Study books.
4. Attend classes on time.
5. Visit aunt.
6. Apply for remote jobs. 
7. Practice code
8. Complete internship task.
9. Practice chess openings.
10. Solve chess puzzles.
11. Check exam schedule. 

我增加了四个新任务。要把新的状态合并到主分支（main branch）。你必须先把这个分支分阶段并提交，由于我们在上一节中做了两次，我就不详细介绍如何提交。

你应该自己试着做一下，这样你就会明白它是如何工作的。作为提示，先添加文件，然后带着信息提交（参考上一节的细节，告诉你如何做）。

提交完测试分支后，通过运行以下命令切换回主分支，git checkout main。

你是否注意到，我们没有添加-b？这是因为我们不是在创建一个新的分支，而是切换到一个现有的分支。你可以通过运行git branch命令来检查你的 repo 中存在的所有分支。

现在，我们可以通过运行git merge test，将测试分支中的修改合并到主分支中。这时，你会看到测试分支中的所有改动都反映在主分支中。你还应该收到类似这样的回复：

git merge

下面是我们的 repo 的图示：

如果你继续将你的 repo 推送到 GitHub，你会发现测试分支不会被推送。它只会保留在你的本地 repo 中。如果你想推送你的测试分支，可以用git checkout test切换到该分支，然后运行git push -u origin test。

如何在 Git 中拉取一个仓库

在 Git 中拉取意味着将远程仓库的当前状态克隆到你的电脑/仓库中。当你想在不同的电脑上操作你的仓库时，或者当你在网上为一个开源项目做贡献时，这就很方便了。

要测试这一点，不用担心切换到新的电脑。只要运行cd .. 就可以离开当前目录并返回上一层目录。在我自己的例子中，我已经导航回到了我的桌面。

进入 GitHub，在你的仓库的主页上，你应该看到一个绿色的按钮，上面写着 "code"。当你点击这个按钮时，你应该在一个下拉菜单中看到一些选项。继续并复制 HTTPS URL。

之后，运行git clone YOUR_HTTPS_URL。这个命令会把远程版本库拉到你的本地电脑上，放在一个叫git-and-git-tutorial的文件夹里。就是说：

git clone

结语

本文介绍了有助于你开始使用 Git 的基本命令。我们还开始学习如何使用 GitHub。

如果你已经跟到了这一步，那么恭喜你，你已经可以开始了。现在无论你使用什么编程语言，都可以在你的项目中使用 Git。

你应该知道，这些并不是 Git 中存在的所有命令，所以你可以随时做更多的研究来了解更多的命令和它们的用途。 这篇文章 和 手册 是很好的开始。 这个gist 是查看更多 Git 命令的详细列表的好地方。

你可以在推特上找到我 @ihechikara2。祝你编程愉快！

程序员喜欢写博客，大都喜欢自己 Host 一个自己的 Blog。通常 Blog 会有一个全局的搜索功能，开源博客一般都会选择 lunrjs 或者 algolia 等。我的 Blog 是基于 Hugo 构建的，使用的主题是 LoveIt，集成的是 algolia 的搜索方式。

对于存储在 algolia 上的数据，我是通过 GitHub Action：Algolia Docsearch Indexer 来上传的，之前使用是没有问题的。

问题

突然有一天我要使用搜索功能，但是怎么也搜索不到我想搜索的内容，看了 GitHub 项目的构建状态，一切正常，然后登陆到 algolia 后台一看， 最后一次的数据更新是在 21 年 8 月； 然后打开最近的博客构建记录，看了执行如下 GitHub workflow 的 yaml 日志，大吃一惊：程序执行错误，但还是在最后给我们送了一个🚀，同样是写代码，你能忍？

    - uses: darrenjennings/algolia-docsearch-action@master
      with:
        algolia_application_id: ${{secrets.ALGOLIA_APPLICATION_ID}}
        algolia_api_key: ${{secrets.ALGOLIA_API_KEY}}
        file: './public/index.json'

运行日志

Run darrenjennings/algolia-docsearch-action@master
/usr/bin/docker run --name a682564a13d76444749d3b720346ba2365371_9474ad --label 6a6825 --workdir /github/workspace --rm -e INPUT_ALGOLIA_APPLICATION_ID -e INPUT_ALGOLIA_API_KEY -e INPUT_FILE -e HOME -e GITHUB_JOB -e GITHUB_REF -e GITHUB_SHA -e GITHUB_REPOSITORY -e GITHUB_REPOSITORY_OWNER -e GITHUB_RUN_ID -e GITHUB_RUN_NUMBER -e GITHUB_RETENTION_DAYS -e GITHUB_RUN_ATTEMPT -e GITHUB_ACTOR -e GITHUB_WORKFLOW -e GITHUB_HEAD_REF -e GITHUB_BASE_REF -e GITHUB_EVENT_NAME -e GITHUB_SERVER_URL -e GITHUB_API_URL -e GITHUB_GRAPHQL_URL -e GITHUB_REF_NAME -e GITHUB_REF_PROTECTED -e GITHUB_REF_TYPE -e GITHUB_WORKSPACE -e GITHUB_ACTION -e GITHUB_EVENT_PATH -e GITHUB_ACTION_REPOSITORY -e GITHUB_ACTION_REF -e GITHUB_PATH -e GITHUB_ENV -e RUNNER_OS -e RUNNER_ARCH -e RUNNER_NAME -e RUNNER_TOOL_CACHE -e RUNNER_TEMP -e RUNNER_WORKSPACE -e ACTIONS_RUNTIME_URL -e ACTIONS_RUNTIME_TOKEN -e ACTIONS_CACHE_URL -e GITHUB_ACTIONS=true -e CI=true -v "/var/run/docker.sock":"/var/run/docker.sock" -v "/home/runner/work/_temp/_github_home":"/github/home" -v "/home/runner/work/_temp/_github_workflow":"/github/workflow" -v "/home/runner/work/_temp/_runner_file_commands":"/github/file_commands" -v "/home/runner/work/blog/blog":"/github/workspace" 6a6825:64a13d76444749d3b720346ba2365371  "***" "***" "./public/index.json"
Cloning into 'docsearch-scraper'...
Collecting pipenv
  Downloading pipenv-2021.11.23-py2.py3-none-any.whl (3.6 MB)
Collecting virtualenv
  Downloading virtualenv-20.10.0-py2.py3-none-any.whl (5.6 MB)
Requirement already satisfied: pip>=18.0 in /usr/local/lib/python3.6/site-packages (from pipenv) (21.2.4)
Requirement already satisfied: setuptools>=36.2.1 in /usr/local/lib/python3.6/site-packages (from pipenv) (57.5.0)
Collecting virtualenv-clone>=0.2.5
  Downloading virtualenv_clone-0.5.7-py3-none-any.whl (6.6 kB)
Collecting certifi
  Downloading certifi-2021.10.8-py2.py3-none-any.whl (149 kB)
Collecting importlib-resources>=1.0
  Downloading importlib_resources-5.4.0-py3-none-any.whl (28 kB)
Collecting backports.entry-points-selectable>=1.0.4
  Downloading backports.entry_points_selectable-1.1.1-py2.py3-none-any.whl (6.2 kB)
Collecting six<2,>=1.9.0
  Downloading six-1.16.0-py2.py3-none-any.whl (11 kB)
Collecting importlib-metadata>=0.12
  Downloading importlib_metadata-4.8.3-py3-none-any.whl (17 kB)
Collecting filelock<4,>=3.2
  Downloading filelock-3.4.1-py3-none-any.whl (9.9 kB)
Collecting distlib<1,>=0.3.1
  Downloading distlib-0.3.4-py2.py3-none-any.whl (461 kB)
Collecting platformdirs<3,>=2
  Downloading platformdirs-2.4.0-py3-none-any.whl (14 kB)
Collecting zipp>=0.5
  Downloading zipp-3.6.0-py3-none-any.whl (5.3 kB)
Collecting typing-extensions>=3.6.4
  Downloading typing_extensions-4.0.1-py3-none-any.whl (22 kB)
Installing collected packages: zipp, typing-extensions, importlib-metadata, six, platformdirs, importlib-resources, filelock, distlib, backports.entry-points-selectable, virtualenv-clone, virtualenv, certifi, pipenv
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
Successfully installed backports.entry-points-selectable-1.1.1 certifi-2021.10.8 distlib-0.3.4 filelock-3.4.1 importlib-metadata-4.8.3 importlib-resources-5.4.0 pipenv-2021.11.23 platformdirs-2.4.0 six-1.16.0 typing-extensions-4.0.1 virtualenv-20.10.0 virtualenv-clone-0.5.7 zipp-3.6.0
WARNING: You are using pip version 21.2.4; however, version 21.3.1 is available.
You should consider upgrading via the '/usr/local/bin/python -m pip install --upgrade pip' command.
Installing dependencies from Pipfile.lock (aabb41)...
Traceback (most recent call last):
  File "docsearch", line 5, in <module>
    run()
  File "/github/workspace/docsearch-scraper/cli/src/index.py", line 161, in run
    exit(command.run(sys.argv[2:]))
  File "/github/workspace/docsearch-scraper/cli/src/commands/run_config.py", line 21, in run
    return run_config(args[0])
  File "/github/workspace/docsearch-scraper/cli/../scraper/src/index.py", line 33, in run_config
    config = ConfigLoader(config)
  File "/github/workspace/docsearch-scraper/cli/../scraper/src/config/config_loader.py", line 72, in __init__
    for key, value in list(data.items()):
AttributeError: 'list' object has no attribute 'items'
🚀 Successfully indexed and uploaded the results to Algolia

面对一个磨洋工的工具，作为程序员的我们肯定不能忍。

打开 GitHub 上这个 Action 的源码, 根据对 Action 构建的了解和现有代码，作者使用的是 Python 和 algolia 自己在 GitHub 上开源的工具, 然后执行一个 Python 脚本上传文件到 algolia 的；根据以往经验，由 Python 构建的项目镜像一般都比较大，在本地测试了一下，果不其然的大。

面临的问题

• 工具损坏
• 镜像体积大

方案Spike

综上分析，使用 Option2 SDK 的方案更佳。

执行方案

新建 GitHub Action 项目，我们使用 Dockerfile 的方式构建上传索引的方案；

• 新建 entrypoint.sh 并写入如下代码, 脚本执行需要传入如下几个变量：

#!/bin/sh
set -eu

npm install -g @algolia/cli

algolia import -s $FILE_PATH -a $APPLICATION_ID -k $ADMIN_API_KEY -n $INDEX_NAME 

if [ "$?" != "0" ] ; then
  echo "😢 Failed to upload your data to Algolia, PLZ report an issue, thx!"
  exit 1
fi

echo "🚀 Successfully uploaded!"

• 新建 Dockerfile 并写入如下代码，在此我们使用最小化的 Node 镜像 node:lts-alpine

FROM node:lts-alpine
COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

• 更新README, 完善使用文档。

详细代码请参考 algolia-docsearch-upload-action。

验证结果

Refs

• 博客: https://guzhongren.github.io/
• Algolia Docsearch Indexer: https://github.com/marketplace/actions/algolia-docsearch-indexer
• GitHub Action: https://docs.github.com/en/actions

欢迎阅读我的更多文章。

我们如何用Github Actions来自动持续部署我们的应用程序到S3?

• 什么是GitHub Actions
• 什么是持续部署
• 我们怎么去构建
• 第0步: 在GitHub上建立一个新的Next.js项目
• 第1步: 手工创建一个用于部署next.js项目的新S3桶
• 第2步: 创建一个新的GitHub Action工作流来自动化构建一个Next.js项目
• 第3步: 配置一个GitHub Action，部署静态网站到S3上

什么是GitHub Actions

GitHub Actions是GitHub的一项免费服务，它允许我们用代码实现任务自动化。

我在这篇文章 里介绍了如何用它来自动化任务，比如在运行代码中的测试，并向Slack发送通知。

它们提供一种灵活的方式，在我们现有的工作流基础上为自动化运行代码。这提供了很多的可能性，比如部署我们的网站。

什么是 AWS S3？

S3（简单存储服务）是AWS的一个对象存储服务。它允许你在云上轻松存储文件，使它们在世界各地都可以使用。

它还允许你将这些文件作为一个网站使用。因为我们可以把HTML文件作为一个对象上传，我们也可以配置S3，让一个HTTP请求访问该文件。 这意味着，我们可以在S3中直接托管整个网站.

什么使持续部署？

持续部署（Continuous Deployment），通常是指将代码处在可发布的状态，自动化部署代码，缩短部署部署时间。

在这个示例中，我们将配置项目，持续将更新推送或者合并到git主分支，部署到网站。

我们怎样去构建?

我们首先要使用默认的Next.js起始模板初始化一个简单的Next.js应用，并配置将其编译成静态文件。

如果你不向创建一个Next.js项目，你甚至用一个简单的HTML文件跟着做，并不运行任何构建命令。但Next.js是构建动态网站应用的一种现代化方式，所以我将从这里开始。

随着我们的网站文件准备就绪，我们将在AWS中创建和配置一个S3桶，在S3桶上托管我们的网站。

最后，我们将创建一个新的GitHub Action工作流，当我们的主分支（main）发生新的变化时，它将自动更新S3中网站文件。

第0步：在GitHub上创建一个新的Next.js项目

我们将从Next.js的默认模板开始。

在创建你像创建项目的目录后，运行:

yarn create next-app my-static-website
# 或者
npx create-next-app my-static-website

注意： 请注意将my-static-website替换为你想选择的名称。我们将在本教程的其余部分使用这个名字。

如果进入到该目录并运行开发命令，你应该能够成功启动你的开发服务器。

cd my-static-website
yarn dev
# or
npm run dev

New Next.js App

接下来，让我们把我们的项目配置为静态编译。

在 package.json文件, 把build 脚本改为 :

"build": "next build && next export",

这样做的目的时告诉Next将网站导出为静态文件，我们将它用于托管网站。

yarn build
# 或者
npm run build

一旦完成, 我们将查看 out目录，看到我们新网站的所有文件。

Next.js 的静态输出

最后，我们要把它推送到GitHub上。

在你的GitHub账号中 创建一个新的仓库。然后会提供如何 添加现有项目到该仓库的说明。

一旦把你的项目推送到GitHub上，我们就做好了建立我的新网站项目的准备。

GitHub中的新repo

有下面的提交内容

• 添加初始Next.js项目 通过 创建Next引用
• 配置Next.js导出

第1步: 手动创建新的S3桶，并将Next.js项目部署到上面。

要开始使用我们的新S3桶，首先登录你的AWS账号，并进入到S3服务。

发现没有桶

我们要创建一个新桶，使用我们选择的名字命名，用于我们网址托管的S3，我们还要配置我们的S3桶，使其能够托管一个网站。

_注意: 本教程步会指导你如何在S3上托管网站，但是你可以查看我的另一个教程，该教程将一步步地 指导你在S3上托管网站。

静态网站在AWS S3上托管

当我们把S3桶配置成一个网站，我们就可以回到Next.js项目文件夹，运行我们的构建命令，然后把out文件夹中的所有文件上传到我们的新建的S3桶。

S3桶上的静态应用

当这些文件被上传，并且我们已经为网站托管配置了S3桶，我们现在应该能看到我们的项目在网络上线运行！

AWS S3托管Next.js应用程序

第2步: 创建一个新的GitHub Action工作流来自动构建一个Next.js项目

首先，我们需要创建一个新的工作流程(workflow)。

如果你熟悉GitHub Actions，你可以手动创建一个，单我们将通过用户界面快速创建一个。

进入GitHub的仓库中的Action标签，点击set up a workflow yourself,来自行设置工作流。

新的GitHub Action工作流

GitHub提供了一个模板，我们可以在工作流程中使用，不过我们要做一些修改。

让我们做以下工作。

• 可选: 将文件重名为deploy.yml
• 可选: 将workflow重名为CD (因为它与CI不同)
• 可选: 删除所有的注释，使其更容易阅读
• 删除on 属性中的pull_request
• 删除所有的 steps 除了uses: actions/checkout@v2

因此，在这一点上，我们应该剩下的是:

name: CD

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

仅仅这段代码会触发一个流程，会启动一个新的Ubuntu实例，并在GitHub上有新的改动推送到主分支后，拉取代码到Ubuntu上。

接下来， 当我们获取我们的代码后，我们要构建它。然后将输出文件同步到S3。

这一步将基于你的项目使用yarn还是npm有所不同。

如果你使用yarn，在 steps定义下，添加以下内容。

- uses: actions/setup-node@v1
  with:
    node-version: 12
- run: npm install -g yarn
- run: yarn install --frozen-lockfile
- run: yarn build

如果是使用npm，添加以下内容:

- uses: actions/setup-node@v1
  with:
    node-version: 12
- run: npm ci
- run: npm run build

在这两个步骤之间，我们要做的是:

• 设置 node: 这是为了我们能够使用npm 和node 来安装和运行的脚本
• 安装Yarn (仅对使用Yarn): 如果我们使用Yarn，我们将为其安装全局依赖，以便我们使用它
• 安装依赖: 我们安装我们的依赖，我们使用一个特定命令，确保我们使用lock文件，以避免任何意外的软件包升级
• 构建: 最后, 我们运行我们的构建命令，将我们的Next.js项目编译到out目录中。

现在我们可以将该该文件直接提交到我们的main分支，这触发我们的workflow的运行，我们可以子啊Actions标签里看到。

在GitHub Actions中新的workflow

为了看到它的运行状态，我们进入运行的workflow，选择我们的workflow，看到所有我们的项目包含的步骤。

GitHub Action成功构建日志

随着提交!

第3步: 配置一个GitHub Action，将静态网站部署到S3上

现在我们正在自动构建我们的项目，我们想在S3中自动更新我们的网站。

为了做到这一点，我们将使用GitHub Action aws-actions/configure-aws-credentials(配置aws凭证) 和 the AWS CLI(AWS提供的命令行)。

我们使用GitHub Action 将接收我们的AWS凭证和配置，并在workflow的生命周期内使用。

目前，GitHub Action中的Ubuntu实例允许使用AWS CLI，因为它包含在其中。因此，我们将能够在workflow中使用CLI命令。

另外，我们也可以使用S3 Sync action。但是通过使用AWS CLI，我们可以获得更多的灵活性来定制我们的设置，我们可以使用它来获得额外的CLI命令，一般来说，熟悉AWS CLI也是不错的。

为了开始，让我们在workflow添加以下片段作为附加步骤。

- uses: aws-actions/configure-aws-credentials@v1
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: us-east-1

上面要做的是使用AWS凭证配置action，根据我们的设置来设置我们的AWS的Access Key和Secret Key还有region(区域)。

AWS Region可以自定义为你通常使用的AWS账号的任何区域，我在美国东北部，所以我设置为us-east-1。

Access Key和Secret Key是你需要你的AWS账号生成的凭证。我们的代码设置方式是，我们将这些值存储在GitHub Secrets里，要防止这些密钥被泄。当action运行时，GitHub会将这些值改为星星(***)，这样人们就无法访问这些密钥。

为了设置这些secrets,我们首先要在AWS生成 Access Keys。

进入了AWS控制台。在用户菜单下，选择 My Security Credentials，然后选择 Create access key。

在AWS创建一个 Access Key

这会生成两个值 Access key ID 和Secret access key。必须保存好这些值，因为你将无法再次访问Secret key ID 。

在AWS中寻找 Secret Key 和 Access Key

注意: 记住不要再你的代码中包含Access Key和Secret Key。这可能导致有人破坏你的AWS凭证。

下一步，在GitHub repo中，进入到 Settings -> Secrets，然后选择 New secret。

在这里，我们要使用AWS keys添加到下面的secrets:

• AWS_ACCESS_KEY_ID: your AWS Access key ID
• AWS_SECRET_ACCESS_KEY: your AWS Secret key

当保存下来，你就应该记住这两个新的secrets。

在GitHub中创建Secrets

现在我们已经配置好了我们的凭证，我们应该为运行命令，将我们的项目同步到S3，做好准备。

在Github Action，添加以下步骤:

- run: aws s3 sync ./out s3://[bucket-name]

注意: 请确保[bucket-name] 替换为你的S3桶的名称。

这个命令会触发与我们的S3桶的同步(sync)，使用out目录的文件，也就是我们项目构建的地方。

现在，如果我们提交我们的修改，我们可以看到，一旦提交到main分支，我们的actions会自动触发，我们构建我们的项目并同步到S3！

成功通过GitHub Action workflow 同步到AWS S3

注意: 请确保在设置这个action之前，你已经将S3桶配置为网站托管(包括解除S3桶权限) --否则这个action可能失败。

在这一点上，我们的项目可能看起来是一样的，因为我们对代码进行任何修改。

AWS S3的Next.js应用程序

但如果你做了一个代码修改，比如在pages/index.js中改变主页的标题，并提交该修改:

<h1 className={styles.title}>
  Colby's <a href="https://nextjs.org">Next.js!</a> Site
</h1>

我们可以看到，我们的修改触发了workflow的启动:

新的GitHub Action workflow的触发来自代码改变

一旦我们的workflow完成，我们可以看到我们的内容已经在我们的网站上自动更新。

AWS S3托管的应用程序，代码已经更新

随着内容的提交

• 添加ASW的配置和S3 sync命令
• 测试workflow的标题的更新

我们还能做什么?

设置CloudFront

这个篇文章的目的不是要经历AWS配置网站的整个过程，但是你在S3上运行网站服务，你可能在之前考虑过CloudFront。

你可以查看以下我的另一个指南，它指导你如何设置CloudFront，以及如何在S3中创建网站的手把手指南。

CloudFront的缓存失效

如果你的S3网站在CloudFront后面，有可能你会确保CloudFront没有缓存新的变化。

通过AWS CLI，我们也可以触发CloudFront的缓存失效，以确保它正在抓取最新的变化。

请看这里的文档学习更多的知识.

pull request部署

如果你不断地在pull request中的网站修改，有时候更容易看到网站的修改。

你可以设置一个新的workflow，只在pull request上运行，workflow可以根据分支或者环境动态创建一个新的桶，并在pull request上添加一个带有该URL的comment。

你也许能找到一个GitHub Action 作为你管理你pull request上带的comments,你可以查询GitHub Actions文档.

• 🐦 在推特上关注我
• 🎥 在油管上订阅我
• ✉️ 订阅我的Newsletter
• 💝 赞助我

原文：How to Use Github Actions to Deploy a Next.js Website to AWS S3，作者：Colby Fayock

1. 第一部分是使用 Gitea 配置局域网 git 服务器，再使用 Jenkins 将 Gitea 下的项目部署到局域网服务器。
2. 第二部分是使用 Github Actions 将 Github 项目部署到 Github Page 和阿里云。

阅读本教程并不需要你提前了解 Jenkins 和 Github Actions 的知识，只要按照本教程的指引，就能够实现自动化部署项目。

PS：本人所用电脑操作系统为 windows，即以下所有的操作均在 windows 下运行。其他操作系统的配置大同小异，不会有太大差别。

Gitea + Jenkins 自动构建前端项目并部署到服务器

Gitea 用于构建 Git 局域网服务器，Jenkins 是 CI/CD 工具，用于部署前端项目。

配置 Gitea

1. 下载 Gitea，选择一个喜欢的版本，例如 1.13，选择 gitea-1.13-windows-4.0-amd64.exe 下载。
2. 下载完后，新建一个目录（例如 gitea），将下载的 Gitea 软件放到该目录下，双击运行。
3. 打开 localhost:3000 就能看到 Gitea 已经运行在你的电脑上了。
4. 点击注册，第一次会弹出一个初始配置页面，数据库选择 SQLite3。另外把 localhost 改成你电脑的局域网地址，例如我的电脑 IP 为 192.168.0.118。

1. 填完信息后，点击立即安装，等待一会，即可完成配置。
2. 继续点击注册用户，第一个注册的用户将会成会管理员。
3. 打开 Gitea 的安装目录，找到 custom\conf\app.ini，在里面加上一行代码 START_SSH_SERVER = true。这时就可以使用 ssh 进行 push 操作了。

8. 如果使用 http 的方式无法克隆项目，请取消 git 代理。

git config --global --unset http.proxy
git config --global --unset https.proxy
复制代码

配置 Jenkins

1. 需要提前安装 JDK，JDK 安装教程网上很多，请自行搜索。
2. 打开 Jenkins 下载页面。

1. 安装过程中遇到 Logon Type 时，选择第一个。

1. 端口默认为 8080，这里我填的是 8000。安装完会自动打开 http://localhost:8000 网站，这时需要等待一会，进行初始化。
2. 按照提示找到对应的文件（直接复制路径在我的电脑中打开），其中有管理员密码。

6. 安装插件，选择第一个。

1. 创建管理员用户，点击完成并保存，然后一路下一步。

8. 配置完成后自动进入首页，这时点击 Manage Jenkins -> Manage plugins 安装插件。

9. 点击 可选插件，输入 nodejs，搜索插件，然后安装。 10. 安装完成后回到首页，点击 Manage Jenkins -> Global Tool Configuration 配置 nodejs。如果你的电脑是 win7 的话，nodejs 版本最好不要太高，选择 v12 左右的就行。

创建静态服务器

1. 建立一个空目录，在里面执行 npm init -y，初始化项目。
2. 执行 npm i express 下载 express。
3. 然后建立一个 server.js 文件，代码如下：

const express = require('express')
const app = express()
const port = 8080

app.use(express.static('dist'))

app.listen(port, () => {
    console.log(`Example app listening at http://localhost:${port}`)
})
复制代码

它将当前目录下的 dist 文件夹设为静态服务器资源目录，然后执行 node server.js 启动服务器。

由于现在没有 dist 文件夹，所以访问网站是空页面。

不过不要着急，一会就能看到内容了。

自动构建 + 部署到服务器

1. 下载 Jenkins 提供的 demo 项目 building-a-multibranch-pipeline-project，然后在你的 Gitea 新建一个仓库，把内容克隆进去，并提交到 Gitea 服务器。

2. 打开 Jenkins 首页，点击 新建 Item 创建项目。

3. 选择源码管理，输入你的 Gitea 上的仓库地址。

1. 你也可以尝试一下定时构建，下面这个代码表示每 5 分钟构建一次。

1. 选择你的构建环境，这里选择刚才配置的 nodejs。

6. 点击增加构建步骤，windows 要选 execute windows batch command，linux 要选 execute shell。

1. 输入 npm i && npm run build && xcopy .\build\* G:\node-server\dist\ /s/e/y，这行命令的作用是安装依赖，构建项目，并将构建后的静态资源复制到指定目录 G:\node-server\dist\ 。这个目录是静态服务器资源目录。

8. 保存后，返回首页。点击项目旁边的小三角，选择 build now。

9. 开始构建项目，我们可以点击项目查看构建过程。

10. 构建成功，打开 http://localhost:8080/ 看一下结果。

11. 由于刚才设置了每 5 分钟构建一次，我们可以改变一下网站的内容，然后什么都不做，等待一会再打开网站看看。

12. 把修改的内容提交到 Gitea 服务器，稍等一会。打开网站，发现内容已经发生了变化。

使用 pipeline 构建项目

使用流水线构建项目可以结合 Gitea 的 webhook 钩子，以便在执行 git push 的时候，自动构建项目。

1. 点击首页右上角的用户名，选择设置。

1. 添加 token，记得将 token 保存起来。

1. 打开 Jenkins 首页，点击 新建 Item 创建项目。

4. 点击构建触发器，选择触发远程构建，填入刚才创建的 token。

5. 选择流水线，按照提示输入内容，然后点击保存。

6. 打开 Jenkins 安装目录下的 jenkins.xml 文件，找到 <arguments> 标签，在里面加上 -Dhudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION=true。它的作用是关闭 CSRF 验证，不关的话，Gitea 的 webhook 会一直报 403 错误，无法使用。加好参数后，在该目录命令行下输入 jenkins.exe restart 重启 Jenkins。

7. 回到首页，配置全局安全选项。勾上匿名用户具有可读权限，再保存。

1. 打开你的 Gitea 仓库页面，选择仓库设置。

1. 点击管理 web 钩子，添加 web 钩子，钩子选项选择 Gitea。
2. 目标 URL 按照 Jenkins 的提示输入内容。然后点击添加 web 钩子。

11. 点击创建好的 web 钩子，拉到下方，点击测试推送。不出意外，应该能看到推送成功的消息，此时回到 Jenkins 首页，发现已经在构建项目了。

12. 由于没有配置 Jenkinsfile 文件，此时构建是不会成功的。所以接下来需要配置一下 Jenkinsfile 文件。将以下代码复制到你 Gitea 项目下的 Jenkinsfile 文件。jenkins 在构建时会自动读取文件的内容执行构建及部署操作。

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {  // window 使用 bat， linux 使用 sh
                bat 'npm i'
                bat 'npm run build'
            }
        }
        stage('Deploy') {
            steps {
                bat 'xcopy .\\build\\* D:\\node-server\\dist\\ /s/e/y' // 这里需要改成你的静态服务器资源目录
            }
        }
    }
}
复制代码

1. 每当你的 Gitea 项目执行 push 操作时，Gitea 都会通过 webhook 发送一个 post 请求给 Jenkins，让它执行构建及部署操作。

小结

如果你的操作系统是 Linux，可以在 Jenkins 打包完成后，使用 ssh 远程登录到阿里云，将打包后的文件复制到阿里云上的静态服务器上，这样就能实现阿里云自动部署了。具体怎么远程登录到阿里云，请看下文中的 《Github Actions 部署到阿里云》 一节。

Github Actions 自动构建前端项目并部署到服务器

如果你的项目是 Github 项目，那么使用 Github Actions 也许是更好的选择。

部署到 Github Page

接下来看一下如何使用 Github Actions 部署到 Github Page。

在你需要部署到 Github Page 的项目下，建立一个 yml 文件，放在 .github/workflow 目录下。你可以命名为 ci.yml，它类似于 Jenkins 的 Jenkinsfile 文件，里面包含的是要自动执行的脚本代码。

这个 yml 文件的内容如下：

name: Build and Deploy
on: # 监听 master 分支上的 push 事件
  push:
    branches:
      - master
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest # 构建环境使用 ubuntu
    steps:
      - name: Checkout
        uses: actions/checkout@v2.3.1  
        with:
          persist-credentials: false

      - name: Install and Build # 下载依赖 打包项目
        run: |
          npm install
          npm run build

      - name: Deploy # 将打包内容发布到 github page
        uses: JamesIves/github-pages-deploy-action@3.5.9 # 使用别人写好的 actions
        with:  # 自定义环境变量
          ACCESS_TOKEN: ${{ secrets.VUE_ADMIN_TEMPLATE }} # VUE_ADMIN_TEMPLATE 是我的 secret 名称，需要替换成你的
          BRANCH: master
          FOLDER: dist
          REPOSITORY_NAME: woai3c/woai3c.github.io # 这是我的 github page 仓库
          TARGET_FOLDER: github-actions-demo # 打包的文件将放到静态服务器 github-actions-demo 目录下

复制代码

上面有一个 ACCESS_TOKEN 变量需要自己配置。

1. 打开 Github 网站，点击你右上角的头像，选择 settings。

1. 点击左下角的 developer settings。

1. 在左侧边栏中，单击 Personal access tokens（个人访问令牌）。

1. 单击 Generate new token（生成新令牌）。

1. 输入名称并勾选 repo。

1. 拉到最下面，点击 Generate token，并将生成的 token 保存起来。

1. 打开你的 Github 项目，点击 settings。

点击 secrets->new secret。

创建一个密钥，名称随便填（中间用下划线隔开），内容填入刚才创建的 token。

将上文代码中的 ACCESS_TOKEN: ${{ secrets.VUE_ADMIN_TEMPLATE }} 替换成刚才创建的 secret 名字，替换后代码如下 ACCESS_TOKEN: ${{ secrets.TEST_A_B }}。保存后，提交到 Github。

以后你的项目只要执行 git push，Github Actions 就会自动构建项目并发布到你的 Github Page 上。

Github Actions 的执行详情点击仓库中的 Actions 选项查看。

具体详情可以参考一下我的 demo 项目 github-actions-demo。

构建成功后，打开 Github Page 网站，可以发现内容已经发布成功。

Github Actions 部署到阿里云

初始化阿里云服务器

1. 购买阿里云服务器，选择操作系统，我选的 ubuntu
2. 在云服务器管理控制台选择实例->更多->密钥->重置实例密码（一会登陆用）
3. 选择远程连接->VNC，会弹出一个密码，记住它，以后远程连接要用（ctrl + alt + f1~f6 切换终端，例如 ctrl + alt + f1 是第一个终端）
4. 进入后是一个命令行 输入 root（默认用户名），密码为你刚才重置的实例密码
5. 登陆成功， 更新安装源 sudo apt-get update && sudo apt-get upgrade -y
6. 安装 npm sudo apt-get install npm
7. 安装 npm 管理包 sudo npm install -g n
8. 安装 node 最新稳定版 sudo n stable

创建一个静态服务器

mkdir node-server // 创建 node-server 文件夹
cd node-server // 进入 node-server 文件夹
npm init -y // 初始化项目
npm i express
touch server.js // 创建 server.js 文件
vim server.js // 编辑 server.js 文件
复制代码

将以下代码输入进去（用 vim 进入文件后按 i 进行编辑，保存时按 esc 然后输入 :wq，再按 enter），更多使用方法请自行搜索。

const express = require('express')
const app = express()
const port = 3388 // 填入自己的阿里云映射端口，在网络安全组配置。

app.use(express.static('dist'))

app.listen(port, '0.0.0.0', () => {
    console.log(`listening`)
})
复制代码

执行 node server.js 开始监听，由于暂时没有 dist 目录，先不要着急。

注意，监听 IP 必须为 0.0.0.0 ，详情请看部署 Node.js 项目注意事项。

阿里云入端口要在网络安全组中查看与配置。

创建阿里云密钥对

请参考创建 SSH 密钥对和绑定 SSH 密钥对 ，将你的 ECS 服务器实例和密钥绑定，然后将私钥保存到你的电脑（例如保存在 ecs.pem 文件）。

打开你要部署到阿里云的 Github 项目，点击 setting->secrets。

点击 new secret

secret 名称为 SERVER_SSH_KEY，并将刚才的阿里云密钥填入内容。

点击 add secret 完成。

在你项目下建立 .github\workflows\ci.yml 文件，填入以下内容：

name: Build app and deploy to aliyun
on:
  #监听push操作
  push:
    branches:
      # master分支，你也可以改成其他分支
      - master
jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1
    - name: Install Node.js
      uses: actions/setup-node@v1
      with:
        node-version: '12.16.2'
    - name: Install npm dependencies
      run: npm install
    - name: Run build task
      run: npm run build
    - name: Deploy to Server
      uses: easingthemes/ssh-deploy@v2.1.5
      env:
          SSH_PRIVATE_KEY: ${{ secrets.SERVER_SSH_KEY }}
          ARGS: '-rltgoDzvO --delete'
          SOURCE: dist # 这是要复制到阿里云静态服务器的文件夹名称
          REMOTE_HOST: '118.190.217.8' # 你的阿里云公网地址
          REMOTE_USER: root # 阿里云登录后默认为 root 用户，并且所在文件夹为 root
          TARGET: /root/node-server # 打包后的 dist 文件夹将放在 /root/node-server
复制代码

保存，推送到 Github 上。

以后只要你的项目执行 git push 操作，就会自动执行 ci.yml 定义的脚本，将打包文件放到你的阿里云静态服务器上。

这个 Actions 主要做了两件事：

1. 克隆你的项目，下载依赖，打包。
2. 用你的阿里云私钥以 SSH 的方式登录到阿里云，把打包的文件上传（使用 rsync）到阿里云指定的文件夹中。

如果还是不懂，建议看一下我的 demo。

ci.yml 配置文件讲解

1. name，表示这个工作流程（workflow）的名称。
2. on，表示监听的意思，后面可以加上各种事件，例如 push 事件。

下面这段代码表示要监听 master 分支的 push 事件。当 Github Actions 监听到 push 事件发生时，它就会执行下面 jobs 定义的一系列操作。

name: Build app and deploy to aliyun
on:
  #监听push操作
  push:
    branches:
      # master分支，你也可以改成其他分支
      - master
jobs:
...
复制代码

1. jobs，看字面意思就是一系列的作业，你可以在 jobs 字段下面定义很多作业，例如 job1、job2 等等，并且它们是并行执行的。

jobs:
  job1:
  	...
  job2:
  	...
  job3:
	...
复制代码

回头看一下 ci.yml 文件，它只有一个作业，即 build，作业的名称是自己定义的，你叫 good 也可以。

1. runs-on，表示你这个工作流程要运行在什么操作系统上，ci.yml 文件定义的是最新稳定版的 ubuntu。除了 ubuntu，它还可以选择 Mac 或 Windows。

1. steps，看字面意思就是一系列的步骤，也就是说这个作业由一系列的步骤完成。例如先执行 step1，再执行 step2...

setps 步骤讲解

setps 其实是一个数组，在 YAML 语法中，以 - 开始就是一个数组项。例如 ['a', 'b', 'c'] 用 YAML 语法表示为：

- a
- b
- c
复制代码

所以 setps 就是一个步骤数组，从上到下开始执行。从 ci.yml 文件来看，每一个小步骤都有几个相关选项：

1. name，小步骤的名称。
2. uses，小步骤使用的 actions 库名称或路径，Github Actions 允许你使用别人写好的 Actions 库。
3. run，小步骤要执行的 shell 命令。
4. env，设置与小步骤相关的环境变量。
5. with，提供参数。

综上所述，ci.yml 文件中的 setps 就很好理解了，下面从头到尾解释一边：

    steps:
    - uses: actions/checkout@v1
    - name: Install Node.js
      uses: actions/setup-node@v1
      with:
        node-version: '12.16.2'
    - name: Install npm dependencies
      run: npm install
    - name: Run build task
      run: npm run build
    - name: Deploy to Server
      uses: easingthemes/ssh-deploy@v2.1.5
      env:
          SSH_PRIVATE_KEY: ${{ secrets.SERVER_SSH_KEY }}
          ARGS: '-rltgoDzvO --delete'
          SOURCE: dist # 这是要复制到阿里云静态服务器的文件夹名称
          REMOTE_HOST: '118.190.217.8' # 你的阿里云公网地址
          REMOTE_USER: root # 阿里云登录后默认为 root 用户，并且所在文件夹为 root
          TARGET: /root/node-server # 打包后的 dist 文件夹将放在 /root/node-server
复制代码

1. 使用 actions/checkout@v1 库克隆代码到 ubuntu 上。
2. 使用 actions/setup-node@v1 库安装 nodejs，with 提供了一个参数 node-version 表示要安装的 nodejs 版本。
3. 在 ubuntu 的 shell 上执行 npm install 下载依赖。
4. 执行 npm run build 打包项目。
5. 使用 easingthemes/ssh-deploy@v2.1.5 库，这个库的作用就是用 SSH 的方式远程登录到阿里云服务器，将打包好的文件夹复制到阿里云指定的目录上。

从 env 上可以看到，这个 actions 库要求我们提供几个环境变量：

1. SSH_PRIVATE_KEY: 阿里云密钥对中的私钥（需要你提前写在 github secrets 上），
2. ARGS: '-rltgoDzvO --delete'，没仔细研究，我猜是复制完文件就删除掉。
3. SOURCE：打包后的文件夹名称
4. REMOTE_HOST: 阿里云公网 IP 地址
5. REMOTE_USER: 阿里云服务器的用户名
6. TARGET: 你要拷贝到阿里云服务器指定目录的名称

如果你想了解一下其他 actions 库的实现，可以直接复制 actions 库的名称去搜索引擎搜索一下，例如搜索 actions/checkout 的结果为：

都看到这了，给个赞再走吧。

参考资料

• Jenkins 用户手册
• GitHub Actions 文档
• GitHub Pages 文档
• Gitea 文档
• GitHub 操作的工作流程语法

在本教程中，你将学习如何使用两个流行的平台——Netlify 和 GitHub 发布 HTML 网站。

在我们开始之前，请确保你有一个 GitHub 帐户，因为你需要在 GitHub 上托管你的仓库（源代码）。没有它，你将无法按照本教程发布 HTML 网站。

如何在 Netlify 上发布网站

我们要探索的第一种方法是如何在 Netlify 上发布你的网站。

Netlify 是一个托管网站的平台。在 Netlify 上托管站点很容易，因为你不需要手动配置它——最重要的是，它是免费的。如果你还没有注册帐户，现在是注册的好时机。

以下是在 Netlify 上发布网站的步骤：

第 1 步：添加你的新站点

登录后，它会将你带到主页界面。点击 New site from git 按钮将你的新网站添加到 Netlify。

第 2 步：链接到你的 GitHub

当你单击 New site from git 按钮时，它会将你带到 “Create a new site” 页面。确保在 GitHub 上推送你的仓库，以便 Netlify 可以链接到你的 GitHub 帐户。

单击 GitHub 按钮，如下面的屏幕截图所示：

第 3 步：授权 Netlify

接下来，单击 Authorize Netlify by Netlify 按钮。需要权限，以便 Netlify 和 GitHub 可以连接。

第 4 步：选择你的仓库

授予 Netlify 权限后，你可以看到所有仓库的列表。选择要发布的网站。你可以通过向下滚动列表或使用搜索栏缩小列表来找到它。

第 5 步：配置

选择你的网站后，系统会提示你配置用于部署网站的设置。由于你的网站只是一个静态网站，因此这里没有什么可做的 只需单击 Deploy site 即可继续。

第 6 步：发布你的网站

你的网站现在可以发布了！ Netlify 会为你完成剩下的工作，完成整个过程只需要一分钟左右。

现在你完成了！ 你的新网站已发布，可以通过单击绿色链接进行查看。

现在，你的 URL 看起来是随机的，但你可以通过单击 Site settings 按钮，然后单击 Change site name 按钮来编辑它。

祝贺你发布了你的第一个新网站！ 现在我们将学习如何使用 GitHub 发布网站。

如何在 GitHub 上发布网站

我们将研究的第二种方法是使用 GitHub 发布你的站点。GitHub 是一个用于存储、跟踪和管理项目源代码的平台。你还可以在此处发布你的 HTML 网站——与 Netlify 一样，你可以在这里免费托管。

以下是在 GitHub 上发布网站的步骤。

注意：如果你将仓库的可见性设置为公开，你只能在 GitHub 上发布你的网站。如果你想在私密的情况下部署网站，请将你的帐户升级到 Pro 或使用 Netlify 在那里托管。

第 1 步：转到你网站的仓库

登录后，转到左侧边栏上的仓库，然后选择要发布的仓库。

第 2 步：选择设置

在你的仓库中，单击 Settings 链接，它将带你到仓库的设置页面。

第 3 步：转到 GitHub Pages

当你在仓库的设置中时，向下滚动一点，直到你在左侧边栏中看到 Pages 链接。单击它，它将带你进入 GitHub Pages。

第 4 步：选择分支

在源部分，单击下拉菜单，选择主分支，并保存。根据你的命名方式，它可能是 master 或 main。

第 5 步：全部完成

你已经完成了！ 你的网站将被发布，只需一分钟左右即可完成该过程。刷新页面，你将看到一个指向你新发布的网站的链接。

总结

希望本教程对你有所帮助。你已经学习了如何使用 Netlify 和 GitHub 发布 HTML 网站。现在，你可以继续向世界展示你优秀的作品了！

如果你想了解有关现代 Web 开发的更多信息，我邀请你加入我的全栈 JavaScript 课程，或在我的编程博客上阅读更多关于 JS、HTML 和 CSS 的文章。

原文：How to Publish an HTML Website on Netlify or GitHub Pages，作者：Vasyl Lagutin

甚至在我近 10 年的软件开发生涯后，我还在学习 Git 的基本原理和如何更有效地使用 Git。

就在不久前我意识到我对一个已经使用了无数次的关键命令存在最基本的误解。

就像编程的其他很多领域一样，我相信最好的学习方法就是“实践”。

只要开始使用这个工具，就会有成效——随着时间的推移，基本原理和边缘案例最终会得到解决的。

这正是我们在这个教程中要做的。我们会通过一些系列的实例来全面了解如何使用 Git 以及与队友协作。

在这个过程中，我们会使用简单的命令并且解释它们的基本概念，因为它们有用——但是只限于有助于理解的程度。

Git 的内容肯定比这里介绍的多得多，但这些都是你在长期使用过程中会学到东西。

我也不会使用树状图（像下面这个），因为它们会把我搞糊涂，而且作为一名软件开发者，我从来不需要像这样来理解 Git。

https://www.atlassian.com/git/tutorials/using-branches/git-checkout

这些是我们要涉及到的内容。不要被这份清单吓到，我们会一步一步的进行。

• 安装 git 并创建一个 GitHub 帐户
• 如何在 GitHub 上创建一个新的仓库（repository）
• 克隆仓库
• Git 分支（branch）
• 如何查看一个 Git 项目的状态
• 如何做出我们的第一个提交（commit）
• 如何将我们的第一个提交推送（push）到 GitHub
• 如何在 Git 中添加另一个提交
• 如何在 Git 中缓存修改（stage change）
• 如何查看 Git 差异（diff）
• 如何在 Git 中与他人协作
• Git 中的功能分支（feature branch）
• 用于协作的 Git 工作流程
• 如何在 Git 中合并（merge）分支
• 拉取请求（pull request）工作流程
• 如何使本地保持同步
• 如何获取远端数据
• 如何修复 Git 中的合并冲突（merge conflict）
• 回顾：如何启动一个新功能的工作流程
• 总结

说了这么多，我鼓励你在自己的机器上跟着例子一起进行——让我们开始吧！

如何安装 Git 并创建一个 GitHub 账号

首先，在开始前我们需要处理一些无聊的事情。

如果你已经安装了 Git，注册了 GitHub 账户（或者使用任何其他的服务商，像是 GitLab 或者 Bitbucket），并且已经设置了 SSH 密匙的话，可以跳过这个章节。

否则，你将首先需要 安装 Git。

其次，在本教程里我们会使用 GitHub，所以需要注册一个 GitHub 帐户。

GitHub 账户注册完成后，你将会需要创建一个 SSH 密匙以便将你的代码从本地推送到 GitHub （在推送代码时这个密匙可以向 GitHub 证明你是“你”）。

这并不难——只要遵循这里的步骤就可以了。

如何在 GitHub 里创建一个新的仓库（repository）

下一步我们会在 GitHub 里创建一个新的仓库。

这很简单。只需要点击你的主页上的 “New” 仓库按钮。

创建一个新仓库

接下来，为仓库选择一个名字，以及你希望仓库是公开的还是私有的。你还可以选择添加一个 README 文件，然后点击 “Create repository”。

设置新仓库

我把我的仓库命名为 practical-git-tutorial。这个仓库里已经有了这个教程所有的完成步骤，你可以把它作为参考。

如何克隆一个 Git 仓库

首先，我们将“克隆”这个仓库。克隆一个仓库意味着从源头（在这里就是指 GitHub）上下载所有项目的代码和元数据。

我们使用 git clone <URL> 来克隆仓库。

我使用了我刚刚创建的仓库的 URL，但是你应该使用你自己仓库的 URL：

$ git clone git@github.com:johnmosesman/practical-git-tutorial.git
Cloning into 'practical-git-tutorial'...
remote: Enumerating objects: 6, done.
remote: Counting objects: 100% (6/6), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 6 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (6/6), done.

注意： 在你终端运行的命令将以 $ 作为前缀。

我们很快会详细介绍 git clone 的作用，但现在只需知道它会下载项目并将其放在你当前工作目录的一个文件夹中。

接下来，让我们用 cd 切换到新的目录：

$ cd practical-git-tutorial/
/practical-git-tutorial (main)$

我们已经切换到了这个文件夹（和其他文件夹一样），你的终端可能会在目录名旁边显示一些东西： (main) 。

Git 分支（branch）

这个 (main) 意味着我们现在位于一个叫做 main 的 分支 上。你可以把一个 Git 分支看作是项目 在某一特定时间点 的副本，可以独立于其他分支进行修改。

例如，如果我们用 Git 来跟踪一本书的写作，我们可能会有这样的分支：

• main 分支
• table-of-contents 分支
• chapter-1 分支
• chapter-2 分支
• 等等。

main 分支是，嗯，“主”分支——我们将把书中的所有内容合并成一本最终完成的书的地方。

我们可以创建其他分支来分离和跟踪特定的工作。

如果我在写第一章，而你在写第二章，我们可以创建两个不同的分支， chapter-1 和 chapter-2 ——实际上就是这本书当前状态的两个不同副本。

这样我们就可以在各自的章节上工作，而互不影响，也不会改动到对方的内容——我们都有自己的工作副本，彼此是分开的。

当我们中的任何一个人完成了自己的章节，我们就可以把我章节分支的内容加回到 main 分支中。当我们两个都完成后， main 分支就会同时包含第一章和第二章。

然而，有些时候，你 会 覆盖或更改和别人的内容相同的内容，我们必须想办法解决这些分歧——很快就会看到。

注意： 根据项目的不同，你可能会看到一个分支 被命名为 master 而不是 main 。它们没有任何功能上的区别，只需要根据你的项目中的内容输入 master 或 main 即可。

如何查看一个 Git 项目的状态

我们经常会做的一件事是检查我们项目的状态，已经做了哪些改动，我们想用它们做什么？

我们使用 git status 查看项目的状态：

(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

这个命令的结果中有一些东西，让我们把它们分解一下。

git status 告诉我们的第一件事是我们在 main 分支上：

 On branch main

第二句话比较有意思：

Your branch is up to date with 'origin/main'.

Git 告诉我们，我们的分支是与 origin/main “同步”的。

origin 是一个新的概念，被称为 远端（remote）。远端是一个不同于你本地机器的“远程源”。

在这个项目中，我们有自己的本地副本，但我们也可以添加可以协作的远程源。毕竟，这是 Git 最大的好处之一：与他人的可控协作。

继续我们写书的例子，如果我在我的机器上写第一章，你在你的机器上写第二章，我们都可以把对方的电脑添加为“远端”并发送和接收对方的修改。

在实践中，编程社区广泛认同最好有一个代码的 可信单一数据源（SSOT）。一个代码库的当前状态总是“正确”的地方。按照惯例，我们称这个地方为 源（origin）。

在这种情况下，GitHub 是我们的“源”。

事实上，我们可以通过运行 git remote -v（-v 代表 “verbose”）命令看到这一点：

(main)$ git remote -v
origin  git@github.com:johnmosesman/practical-git-tutorial.git (fetch)
origin  git@github.com:johnmosesman/practical-git-tutorial.git (push)

这个命令列出我们所有的远端。从结果我们们可以看到我们有一个远端叫做 origin ，这个远端的 Git URL 指向我们在 Github.com 上的仓库。它是在我们运行 git clone 时自动设置的。

回到 git status 的结果中的这句话：

Your branch is up to date with 'origin/main'.

当我们查询项目状态时， Git 告诉我们，我们本地的 main 分支与源（即 GitHub ）的 main 分支是同步的。

事实上， git clone 自动为我们在本地创建了一个 main 分支，因为它看到我们克隆的源有一个叫 main 的分支作为主分支。

基本上，我们本地机器上没有与 GitHub 不同的变化，反之亦然——我们的本地 main 分支和 GitHub 上的 main 分支是相同的。

随着我们进行修改，我们会看到这条信息的变化，来反映我们本地仓库和源（GitHub）仓库的差异。

git status 的最后一条信息是关于本地项目的状态：

nothing to commit, working tree clean

当我们进行修改时会在这里进行更详细的说明，但这个消息基本上是说我们没有做任何事——所以没有变化要报告。

总结一下 git status 的结果：

• 我们在 main 分支上
• 我们的本地 main 分支与 origin 的（GitHub 的） main 分支相同
• 我们还没有对该项目做出任何修改

如何做出我们的第一次提交（commit）

现在我们了解了我们项目的初始状态，让我们做一些修改并看看结果。

继续我们写书的比喻，让我们创建一个新的文件，命名为 chapter-1.txt 并在其中插入一个句子。

（你可以使用下面的终端命令（terminal command），或者在任何文本编辑器中创建和编辑该文件——这无关紧要。）

(main)$ touch chapter-1.txt
(main)$ echo "Chapter 1 - The Beginning" >> chapter-1.txt
(main)$ cat chapter-1.txt
Chapter 1 - The Beginning

上面的命令用 touch 创建了一个名为 chapter-1.txt 的新文件，用 echo 和 >> 操作符插入句子“第一章——开端”，并且为了检查我们的工作，用 cat 现实文件内容。

结果是一个里面有一句话的简单文本文件。

让我们再次运行 git status ，看看它的输出有什么不同：

(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        chapter-1.txt

nothing added to commit but untracked files present (use "git add" to track)

在这里我们看到一个与之前不同的输出结果。我们看到一个描述“未跟踪文件（untracked file）”的部分，我们的新文件 chapter-1.txt 被列在那里。

在 Git 开始跟踪（track）一个文件的变化之前，我们首先需要告诉 Git 去跟踪它——正如消息底部所显示的——我们可以用 git add 来实现：

(main)$ git add chapter-1.txt

（除了为 git add 制定文件名外，你可以使用（.）来添加目录中的所有修改）。

让我们再检查一下状态：

(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   chapter-1.txt

john:~/code/practical-git-tutorial (main)$

信息又变了。它现在说我们有一些修改，已经准备好“提交”。

Git 中的 commit 是一个被保存的工作块，但它与你在文本编辑器中保存一个文本文件时的保存有点不同。

你可以把提交想成是一个 完成的想法或工作单元（unit of work）。

例如，如果我们继续写书中第一章的内容，它可能看起来是这样的：

• 写下这一章的标题。 *在我们的编辑器中点击保存*
• 写下这一章的第一段。 *在我们的编辑器中点击保存*
• 写下这一章的第二段。 *再次点击保存*
• 写下这一章的最后一段。 *再次点击保存*

在这里，这个文件我们已经“保存”了四次，但在这四次保存结束后，我们现在有了这一章的第一稿，这一稿就是一个“工作单元”。

我们想把这个文件保存在我们的电脑上，但是我们也想表明这是一个已经完成的工作单元——即使它只是一个草稿。这是值得被保留的一大块工作。将来我们可能会想重温它、再次编辑它、或者把这个草稿合并到整本书的当前草稿中。

为此，我们创建一个新的提交来表示这个里程碑。每个提交有自己独特的标识符，而且提交的顺序也被保留下来。

要提交我们的修改，必须先用 git add 把它们添加到 缓存区（staging area） 。

（我们很快会讨论更多关于 缓存区 的问题。）

接下来，我们需要 git commit 来最终完成提交。

最佳实践是提供一个详细的信息，说明你做了 那些修改 ——更重要的是——你 为什么 要提交这些修改。

一旦提交历史达到几百或几千条，如果没有一个好的提交信息（commit message）就几乎不可能理解 为什么 会有这些修改。Git 会显示哪些文件有修改，以及这些修改是什么，但这些 修改的意义 要靠我们自己提供。

让我们来提交我们制作的新文件并用 -m 或 "message" 标志来附上提交信息：

(main)$ git commit -m "New chapter 1 file with chapter heading"
[main a8f8b95] New chapter 1 file with chapter heading
 1 file changed, 1 insertion(+)
 create mode 100644 chapter-1.txt

我们现在已经提交了那块工作，可以通过 git log 查看 Git 日志：

(main)$ git log
commit a8f8b95f19105fe10ed144fead9cab84520181e3 (HEAD -> main)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Fri Mar 19 12:27:35 2021 -0500

    New chapter 1 file with chapter heading

commit 2592324fae9c615a96f856a0d8b8fe1d2d8439f8 (origin/main, origin/HEAD)
Author: John Mosesman <johnmosesman@users.noreply.github.com>
Date:   Wed Mar 17 08:48:25 2021 -0500

    Update README.md

commit 024ea223ee4055ae82ee31fc605bbd8a5a3673a0
Author: John Mosesman <johnmosesman@users.noreply.github.com>
Date:   Wed Mar 17 08:48:10 2021 -0500

    Initial commit

看一下这个日志，我们会发现在项目历史中有三个提交。

最新的提交是我们刚刚做的那个。我们可以看到刚才使用的提交信息： "New chapter 1 file...".

还有两个之前的提交：一个是我初始化项目的时候，另一个是我更新 GitHub 上的 README.md 文件的时候。

注意每个提交都有一长串与之相关的数字和字符：

commit a8f8b95f19105fe10ed144fead9cab84520181e3 (HEAD -> main)

这一串数字和字符叫作安全散列函数（ SHA ）——它是由散列算法（也叫哈希算法）为该提交生成的唯一 ID。现在只需要注意一下，我们很开就会再来讨论这个问题。

在提交 SHA 后面，我们还看到另外两个有趣的东西：

• 在 (HEAD -> main) 旁边是我们最新的提交内容
• 而 (origin/main, origin/HEAD) 则在该提交之前的提交旁边。

这些信息告诉我们 我们的分支和远程的当前状态 （据我们所知——稍后我们再详细讨论）。

关于最新的提交，我们看到 HEAD （也就是项目历史中的“我们现在的位置”）只想我们的 本地 main 分支——由 HEAD -> main 表示。

这是有道理的，因为我们刚刚做了那个提交，并且我们还没有做其他事情——我还在做那个提交的时间点上。

如果我们看一下以 25923 开头的前一个提交，我们可以看到 (origin/main, origin/HEAD)。这告诉我们， 在源点（即 GitHub） ， GitHub 的 HEAD 或 “当前位置”在我们之前的提交上。

基本上，我们的本地机器认为本地 main 分支的最新改动是我们添加第一章的提交，而我们的本地机器认为 GitHub 上 的最新改动是我们在写这篇文章之前更新 README 的提交。

这也是合理的——我们还没有告诉 GitHub 我们最新的提交。GitHub 仍然认为这个仓库是它看到的最新的。

现在让我们把我们的新提交推送（push）到 GitHub。

如何将我们的第一个提交推送（push）到 GitHub

我们在本地机器上有一个新的提交，我们需要更新我们的“可信单一数据源”—— origin 远端——即 GitHub。

我们目前在本地的 main 分支上，所以我们需要告诉 GitHub 用我们的新提交来更新它自己的 main 。

我们使用 git push 命令做到这一点，我们可以指定 我们要推送到哪里 以及 我们要推送到哪个分支。

(main)$ git push origin main
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Delta compression using up to 16 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 326 bytes | 326.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To github.com:johnmosesman/practical-git-tutorial.git
   2592324..a8f8b95  main -> main

这里我们推送到 origin 远端（GitHub）的 main 分支。

输出结果告诉我们 Git 为此所做的一些文件操作，最后一行告诉我们它推送了哪些提交，推送到了哪里。

To github.com:johnmosesman/practical-git-tutorial.git
   2592324..a8f8b95  main -> main

这里显示我们把我们的 main 分支推送到了 GitHub 的 main 分支。

如果我们回头开一下 git log 的输出，会发现我们的本地和 origin 现在都指向同一个提交：

(main)$ git log
commit f5b6e2f18f742e2b851e38f52a969dd921f72d2f (HEAD -> main, origin/main, origin/HEAD)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:07:35 2021 -0500

    Added the intro line to chapter 1

简而言之，在 origin （GitHub）上 main 分支（也写成 origin/main ）现在已经将我们的新提交标记为了历史中的最新提交。

如果我们和其他合作者一些工作，现在他们可以从 GitHub 上拉取（pull）我们的最新修改并开始编辑第一章。

如何在 Git 中添加另一个提交

在我们和其他人合作之前，让我们再做一个小改动，看看当我们编辑一个现有文件时会发生什么。

让我们在第一章的文件里再添加一行：

(main)$ echo "It was the best of times, it was the worst of times" >> chapter-1.txt
(main)$ cat chapter-1.txt
Chapter 1 - The Beginning
It was the best of times, it was the worst of times

使用 cat 我们可以看到我们的文件现在包含两行。

让我们再看看我们的 Git 仓库的状态：

(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   chapter-1.txt

no changes added to commit (use "git add" and/or "git commit -a")

从顶部开始，我们会注意到输出结果显示 Your branch is up to date with 'origin/main'.

这可能看起来比较奇怪，我们刚刚修改了一个文件，但是 Git 只是将我们做的 提交 和 origin/main 中的提交进行比较。

输出的下一部分内容做了更多解释：

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   chapter-1.txt

在这里 Git 告诉我们，我们有“修改未为提交缓存 (changes not staged for commit)”。

在我们提交一组修改之前，我们首先需要把它们 缓存（stage）。

如何在 Git 中缓存修改（stage change）

为了说明缓存区域（staging area）的作用，让我们先用 git add 来缓存我们的修改：

(main)$ git add .
(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   chapter-1.txt

这些修改现在可以提交了，但在提交之前，让我们在 chapter-1.txt 文件中再添加一个修改。

我要把 chapter-1.txt 的内容完全替换成新的文本：

注意： 我在这里使用 > 而不是 >> ，这将替换文件的内容而不是追加到文件中。

(main)$ echo "New file contents" > chapter-1.txt

(main)$ cat chapter-1.txt
New file contents

(main)$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   chapter-1.txt

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   chapter-1.txt

从输出中我们可以看到我们现在有 已缓存的修改（staged changes） ，和 未缓存的修改（not staged changes）。

虽然文件本身只能包含一个东西，但 Git 为我们记录了这两个修改——尽管它们是对同一行的修改！

然而，从上面的输出中我们无法真正知道这些修改是什么——我们只知道它们存在。

我们首先看一下使用命令行（command line）怎么查看这些修改（我从来不用），然后看一下使用图形用户界面（GUI）（100%更好用）。

如何查看 Git 差异（diff）

要查看这些修改，我们需要查看 Git 差异。

差异 是两组修改之间的差异。这些修改可以是从已缓存的修改到未缓存的修改再到提交中的任何一个。

使用命令行的方式查看需要用到 git diff。

为了全面的展示，我们将在这里看一下这个简单案例的输出。但是，正如我之前提到的，我们对有效的 Git 工作流程感兴趣，一旦你要在多个文件中进行任何大规模的修改，这种命令行输出就变得无效了。

但是为了全面，请看下面：

(main)$ git diff
diff --git a/chapter-1.txt b/chapter-1.txt
index 0450d87..4cbeaee 100644
--- a/chapter-1.txt
+++ b/chapter-1.txt
@@ -1,2 +1 @@
-Chapter 1 - The Beginning
-It was the best of times, it was the worst of times
+New file contents

我的终端试图对这个输出进行着色来帮助提高可读性，但是需要注意的地方是，它告诉我们这在比较的文件是 chapter-1.txt ，并且在底部显示了实际差异。让我们来看看这几行输出：

-Chapter 1 - The Beginning
-It was the best of times, it was the worst of times
+New file contents

以减号（ - ）开始的几行是我们完全或部分删除的行，以加号（ + ）开头的行代表完全或部分添加的行。

随着多个文件和修改行的增加，这种输出会很快变得不方便。有一个更好的方法，在我近十年的编程生涯中，我一直使用一个简单的 GUI 程序来帮助查看和管理差异。

我使用的程序叫做 GitX，它是一个老旧过时的软件，甚至已经没有了真正的维护。然而，我只是用它来查看和管理文件差异，所以它对我有用。

我不会着重推荐这个软件，它是免费的。虽然我没有用过，但 GitHub Desktop client 很可能是一个不错的选择。

现在把这个小问题解决了，这是差异在我的工具中的样子。

首先，右侧的已缓存修改显示了我们对第二句话的原始添加：

GitX 中的已缓存修改 (staged changes)

在左侧的未缓存修改 (unstaged changes) 中，我们可以看到完全删除了这两行并添加了新的一行：

GitX 中的未缓存修改 (unstaged changes)

这与我们运行的文件替换命令相对应。

在一个 GUI 程序中了解差异要容易的多。这个程序还允许我们通过拖动文件来快速缓存和取消缓存。我甚至可以缓存或取消缓存一个文件中的个别行。

使用命令行与 GUI 程序相比没有任何加分。使用任何能帮你完成工作的方法。

现在我们已经看到了缓存区域和 Git 差异是如何工作的，让我们放弃未缓存修改，这样我们就可以回去提交我们第一个修改。

在我的 GUI 程序中，我可以右键点击文件并点击“放弃修改”，但是我在这里也会演示命令行是怎么工作的。

我们上个 git status 的输出实际上已经告诉我们如何通过使用 git restore 来做到这一点了。我们可以输入文件路径或者 . 来代表整个目录：

(main)$ git restore .

如果我们再次查看状态，我们就回到了只有我们的已缓存修改，我们可以继续下一步。

注意： Git 只提交已缓存修改，所以我们可以把那些未缓存的修改留在我们的工作目录中，这样不会干扰提交过程。

但是，这会使我们未来的修改处理起来更麻烦——所以放弃这些修改以保持我们的工作目录的良好状态是合理的。

现在，让我们提交这些修改，并附上关于我们所做的事情的信息：

(main)$ git commit -m "Added the intro line to chapter 1"
[main f5b6e2f] Added the intro line to chapter 1
 1 file changed, 1 insertion(+)

再次检查状态，可以发现我们的分支“比 'origin/main' 领先一次提交 (Your branch is ahead of 'origin/main' by 1 commit)”：

(main)$ git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

最后让我们推送我们的修改：

(main)$ git push origin main

如何在 Git 中与他人协作

到目前为止，我们一直在研究最简单的例子：自己单独在一个分支上工作。

在现实中，我们通常会和多人在多个不同的分支上一起工作。这是 Git 的真正威力：一个可以在众多合作者之间进行协作并跟踪变化的系统。

现在让我们先像项目中只有一个人一样继续工作，但让我们稍微调整一下我们的工作流程，为情况发生变化时做准备。

通常最佳实践是 不 直接在 main 分支上工作。

main 分支应该是项目的“可信单一数据源”——对它的改动应该受到仔细审查。origin/main 中的任何改动都会成为其他在项目中工作的任何人的新的“可信数据源”，所以我们不应该在没有经过思考并通过他人审查的情况下随便改动它。

与其直接在 main 上直接工作，不如从 main 分支 出我们自己的 功能分支 (feature branch)， 然后将这些修改 合并 (merge) 到 main。

这里出现了很多新的术语，所以让我们一步步来。

Git 中的功能分支 (feature branch)

首先，让我们从 main 分支出来，创建我们自己的功能分支。

当你从另一个分支上创建一个分支时，你就在 那个时间点上 创建了一个该分支的副本。现在你可以独立于原始分支修改这个新分支。

为了尝试这一点，让我们建立一个名为 chapter-2 的新分支。我们使用 git checkout 加上 -b 标志和我们想要的新分支的名称：

(main)$ git checkout -b chapter-2
Switched to a new branch 'chapter-2'
(chapter-2)$

现在终端显示我们在 chapter-2 分支上。在 chapter-2 分支上的修改完全不会影响 main 分支。我们有了一个新的游乐场，可以在不影响 main 的情况下做任何我们想做的修改。

这里在后台有很多有趣的事情发生，但就本教程而言，我们只需要知道在 Git 中“检出 (checkout)”某个东西意味着“将我的本地项目改变成与该项目 在某个特定时间点上的样子一模一样。 ”你可以把一个分支看作是指向 Git 历史上某个特定时间线的指针。

这里实际发生了很多事情，但现在这个定义应该是足够了。

我们有了一个新的分支，现在这个新的分支和 main 是一样的（我们还没有做任何修改）。

接下来，让我们重复之前已经做过的事情，创建一个名为 chapter-2.txt 的新文件，给它一些内容，然后提交：

(chapter-2)$ touch chapter-2.txt
(chapter-2)$ echo "Chapter 2 - The next chapter" >> chapter-2.txt

(chapter-2)$ git status
On branch chapter-2
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        chapter-2.txt

nothing added to commit but untracked files present (use "git add" to track)

(chapter-2)$ git add .

(chapter-2)$ git commit -m "Creates chapter 2 and adds the topic sentence"
[chapter-2 741822a] Creates chapter 2 and adds the topic sentence
 1 file changed, 1 insertion(+)
 create mode 100644 chapter-2.txt

这里面没有什么新东西——与我们为第一章所做的事情一样。

现在我们在 chapter-2 分支上有了新的提交，让我们看看 Git 日志，将这个新分支与 main 进行比较：

(chapter-2)$ git log
commit 741822a9fd7b15b6e3caf437dd0617fabf918449 (HEAD -> chapter-2)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:33:26 2021 -0500

    Creates chapter 2 and adds the topic sentence

commit f5b6e2f18f742e2b851e38f52a969dd921f72d2f (origin/main, origin/HEAD, main)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:07:35 2021 -0500

    Added the intro line to chapter 1

commit a8f8b95f19105fe10ed144fead9cab84520181e3
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Fri Mar 19 12:27:35 2021 -0500

    New chapter 1 file with chapter heading
...

我们会注意到在日志中，我们最新的提交显示在最上面，而且我们的 HEAD 又与 origin 不同。这也是合理的——我们是在本地做了一些修改，还不在 GitHub 上。

现在我们需要把我们的新改动放到 main 分支中。

用于协作的 Git 工作流程

有几种方法可以让我们新的第二章进入 main 分支和 GitHub，我们选择的方法取决于项目和我们与他人协作所使用的工作流程。

首先让我们来谈谈我们可以使用的几个不同的工作流程。

第一种是最直接的：

1. 将 chapter-2 的修改合并到我们的本地 main 分支
2. 将本地 main 分支推送到 origin/main

第二种方法更复杂一些：

• 将我们的本地 chapter-2 分支推送到 origin （这会在 origin 上创建一个名为 origin/chapter-2 的新分支）
• 将 origin/chapter-2 合并到 GitHub 上的 origin/main
• 从 origin/main 拉取新的修改到我们本地的 main

第一个工作流程肯定更容易，如果我自己一个人做这个项目，没有任何其他合作者，我会用这个工作流程。

然而，如果我有合作者，我不会想从我的本地直接推送到 main 分支。这样做的话，我就会仅凭自己的修改改变和控制了项目历史，而没有获得合作者的任何意见或审查。

出于这个原因，如果多人在同一个项目上工作，我会使用第二种工作流程，因为这对团队来说是一个更好的协作流程。

既然如此，我们就来看看这两种工作流程，让我们从第一个工作流程开始，它不那么复杂。

如何在 Git 中合并 (merge) 一个分支

当你在 Git 中想把两个分支的内容合并成一个时，有几种方法可以做到。第一种，也可能是最简单的方法，是做一个 合并

合并，就像它听起来那样，试图将一个分支的内容（修改）应用（或“合并”）到另一个分支。

在我们的情境中，我们想要把 chapter-2 分支的内容 合并到 main 中。换句话说，我们先在 main 的当前状态中加入 chapter-2 分支的修改。

我们可以通过使用 git merge 来实现，之后我们会看一下它的结果。

我需要做的第一件事是切换到我们想要把修改合并_进去_ 的主要分支上。因为我们想要 main 吸收 chapter-2 的修改，所以我们首先需要在 main 分支上。

要切换回 main 分支，我们可以再次使用 git checkout 并指定 main 的分支名称。这一次我们不使用 -b 标志，因为我们想切换到一个现有分支，而不是创建一个新分支：

(chapter-2)$ git checkout main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.
(main)$

我们现在回到了 main 分支，我们得到了一个简短的信息，告诉我们已经与 origin/main进行了更新。

接下来，让我们把 chapter-2 分支合并到 main：

(main)$ git merge chapter-2
Updating f5b6e2f..741822a
Fast-forward
 chapter-2.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 chapter-2.txt

让我们再看一下 Git 日志：

(main)$ git log
commit 741822a9fd7b15b6e3caf437dd0617fabf918449 (HEAD -> main, chapter-2)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:33:26 2021 -0500

    Creates chapter 2 and adds the topic sentence

commit f5b6e2f18f742e2b851e38f52a969dd921f72d2f (origin/main, origin/HEAD)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:07:35 2021 -0500

    Added the intro line to chapter 1
    
...

我们可以看到我们的 main 分支现在包含了 chapter-2 的新提交，而我们的 origin 仍然在前一个提交（因为我们还没有更新 origin ）。

最后，让我们推送修改到 origin/main：

(main)$ git push origin main
Total 0 (delta 0), reused 0 (delta 0)
To github.com:johnmosesman/practical-git-tutorial.git
   f5b6e2f..741822a  main -> main

我们已经成功合并了 chapter-2 分支，并将修改推送到 GitHub 上了！

作为最后的清理步骤，让我们删除 chapter-2 功能分支，因为它已经被合并到 main 里了：

(main)$ git branch -d chapter-2
Deleted branch chapter-2 (was 741822a).

注意： git branch 命令如果没有分支名称参数，将列出你在本地的所有分支。

加上 -d 标志和一个分支名称，就会删除传递进来的分支。

拉取请求（pull request）工作流程

为了完成我们的协作工作流程，让我们在一个名为 chapter-3 的新分支上重复我们对第一章和第二章所做的同样的事情：

（现在是你自己尝试的好时机！）

(main)$ git checkout -b chapter-3
(chapter-3)$ touch chapter-3.txt
(chapter-3)$ echo "Chapter 3 - The End?" >> chapter-3.txt
(chapter-3)$ git add .
(chapter-3)$ git commit -m "Adds Chapter 3"

现在我们在一个叫做 chapter-3 的新分支上有一个新的提交。

让我们回顾一下如何将这个新的分支合并到 main 中， 而不直接在 main 上操作：

• 将本地 chapter-3 分支推送到origin （这在 origin 上创建一个名为 origin/chapter-3 的新分支）
• 将 origin/chapter-3 合并到 GitHub 上的 origin/main
• 从 origin/main 拉取 (pull) 新的修改到我们本地的 main

还有几个步骤，但都不太复杂。

第一步是把我们的新分支推送到 GitHub。由于这个分支在 GitHub 上还不存在，GitHub 将为我们创建一个新分支，它是我们推送内容的副本：

(chapter-3)$ git push origin chapter-3
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Delta compression using up to 16 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 299 bytes | 299.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
remote:
remote: Create a pull request for 'chapter-3' on GitHub by visiting:
remote:      https://github.com/johnmosesman/practical-git-tutorial/pull/new/chapter-3
remote:
To github.com:johnmosesman/practical-git-tutorial.git
 * [new branch]      chapter-3 -> chapter-3

现在我们在 GitHub 上有了自己的分支，我们可以创建一个 拉取请求，让我们的队友审查。

GitHub 甚至在上面的输出中为我们提供了要访问的 URL： https://github.com/johnmosesman/practical-git-tutorial/pull/new/chapter-3

几个注意事项： 接下来的部分展示了 GitHub 的用户界面和拉取请求的流程，但这个流程应该与其他服务非常相似（如 GitLab、Bitbucket 等）。

另外请记住，我使用的是我自己的仓库，所以你在这里看到的一些 URL 会与你的不同。

访问上面的 URL， 我们到达了一个发起新拉取请求的页面。

我们可以看到几个东西：

• 一个指定拉取请求名称的地方（一个主题句，以便于理解这个拉取请求是关于什么的）
• 一个描述框，以解释我们所做的修改和我们想提供的任何其他背景信息（你也可以在这里添加图片、gif或视频）。
• 而在所有这些下面是我们修改的文件的列表和其中的变化（差异）。

发起一个新的拉取请求

可以注意到，用户界面显示 base: main <- compare: chapter-3。这是 GitHub 在告诉我们，我们正在设置拉取请求将 chapter-3合并 到 main。

在拉取请求的描述下方是我们所做修改的差异：

拉取请求差异

我们会注意到只有文件 chapter-3.txt 被显示出来，这是因为它是我们修改的唯一文件。

目前在我们的项目中还有其他文件（ chapter-1.txt，chapter-2.txt ），但这些文件没有修改，所有没有必要显示。

我们看到我们插入到 chapter-3.txt 中的一行——在该行的开头有一个 + 号，绿色的背景标志着对该文件的补充。

点击“创建拉取请求（Create Pull Request）”后，我们会被带到我们刚刚制作的新的拉取请求。

在这一点上，我们可以个拉取请求指定一个审查员，通过在差异中的特定行上留言，围绕代码进行讨论。在代码被审查，我们进行了任何必要的修改后，我们就可以准备合并了。

在本教程中，我们将跳过审查过程，直接点击绿色的合并（Merge）按钮：

合并的拉取请求

就这样，我们的拉取请求被合并到了 main！

如何使我们的本地保持同步

我们现在以一种安全、可控、经过同行审查的方式对 origin/main 进行了修改。

但是，我们的本地对这个修改一无所知。在本地， Git 仍然认为我们的 chapter-3 分支没有合并到 main：

(chapter-3)$ git log
commit 085ca1ce2d0010fdaa1c0ffc23ff880091ce1692 (HEAD -> chapter-3, origin/chapter-3)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Tue Mar 23 09:19:14 2021 -0500

    Adds Chapter 3

commit 741822a9fd7b15b6e3caf437dd0617fabf918449 (origin/main, origin/HEAD, main)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Mon Mar 22 10:33:26 2021 -0500

    Creates chapter 2 and adds the topic sentence

...

我们的本地显示 origin/main 还在之前的以 741822 开始的提交。我们需要从 origin 拉取新的信息来更新我们的本地仓库。

如何获取远端数据

与 Git 的其他许多事情一样，完成同样的任务可以有许多不同的方法。

以我们的目标出发，我们将研究一种在大多数情况下都能发挥作用的简单方法。

首先，让我们切换到本地的 main 分支：

(chapter-3)$ git checkout main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.

我们的本地认为我们的与 origin/main 保持了更新，因为自从我们在一开始使用 git clone 拉取了项目后，我们没有向远端仓库 (origin) 索要新的信息。

Git 仓库不是实时更新的——它们只是某个时间点上的历史快照。要收到关于仓库的任何新信息，我们必须再次发出请求。

我们使用 git fetch 从远程获取任何新信息：

(main)$ git fetch
From github.com:johnmosesman/practical-git-tutorial
   741822a..10630f2  main       -> origin/main

输出结果显示， origin/main 现在指向一个以 10630f2 开头的提交。这个提交前缀与我们拉取请求的 SHA 一致。

有几种方法可以将两个分支合并到一起，其中一种方法是创建一个 合并提交 (merge commit)。这就是这里发生的事情。

我们的拉取请求的合并提交

我们的本地仓库现在知道这些新提交的存在，但我们还没有对它做任何事情。

运行 git fetch 实际上并没有修改我们的任何文件——它只是从远程下载关于仓库状态的新信息。

现在我们的本地仓库已经知道了每个分支的状态（ 但还没有 修改或更新 任何分支），让我们再次检查一下状态：

(main)$ git status
Your branch is behind 'origin/main' by 2 commits, and can be fast-forwarded.
  (use "git pull" to update your local branch)

我们的本地现在知道我们的本地 main 比 origin/main 晚了两个提交（来自 chapter-3 分支的提交和拉取请求的合并提交）。

它还提示我们使用 git pull 来更新我们的本地分支：

john:~/code/practical-git-tutorial (main)$ git pull origin main
From github.com:johnmosesman/practical-git-tutorial
 * branch            main       -> FETCH_HEAD
Updating 741822a..10630f2
Fast-forward
 chapter-3.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 chapter-3.txt

git pull 命令实际上是运行两条命令的简写：运行 git fetch 后运行 git merge。

由于 git fetch 不会在本地运行任何修改，所以用 git fetch 来查看我们的分支是否与远端同步（也许我们还不想合并修改），或者拉取存在与远端而不在本地上的新分支，都是很有用的。

从远端获取 (fetch) 一个新的分支就会把这个分支也下载到你的本地机器上——因为它是一个新的分支，所以不会与你本地设置中的任何东西冲突。

我们最初可以只做 git pull 而不是先做 git fetch ，但我想解释一下 git fetch，因为它本身非常有用。

运行了 git pull 之后，如果我们再运行一次 git status ，我们会看到所有东西都已经更新了。

就这样，我们从远端拉取了修改，使我们的本地获得了更新！

如何修复 Git 中的合并冲突（merge conflict）

我们要讨论的最后一个话题是如何处理冲突。

到目前为止， Git 神奇地处理了所有的文件更新，而且大多数时候 Git 都能直接处理。但是，有些时候 Git 不知道如何把修改合并起来，这就产生了 冲突。

当合并两个改动了文件中同一行的修改时，就会发生冲突。如果两个提交修改了文件中的同一行， Git 不知道该使用哪一个提交的修改，它就会要求你做出选择。

为了模拟这种情境，我在 Github 上创建了另一个名为 chapter-3-collaboration 的分支。让我们想象一下，一个队友已经开始在个分支上工作，他要求你和他合作完成第三章。

由于这是一个我们本地没有的新分支，我可以用 git fetch 从远程获取新分支的信息，然后用 git checkout 切换到该分支：

(main)$ git fetch
From github.com:johnmosesman/practical-git-tutorial
 * [new branch]      chapter-3-collaboration -> origin/chapter-3-collaboration

(main)$ git checkout chapter-3-collaboration
Branch 'chapter-3-collaboration' set up to track remote branch 'chapter-3-collaboration' from 'origin'.
Switched to a new branch 'chapter-3-collaboration'
(chapter-3-collaboration)$

现在我们已经把新的分支拉取到本地仓库并切换到了它上。这是目前这个新分支上 chapter-3.txt 的内容：

(chapter-3-collaboration)$ cat chapter-3.txt
Chapter 3 - The End?

This is a sentence.

这是一个标题和一个句子。让我们把标题改成新的东西，比如 "Chapter 3 - The End Is Only The Beginning."

chapter-3.txt 的内容现在看起来像这样：

(chapter-3-collaboration)$ cat chapter-3.txt
Chapter 3 - The End Is Only The Beginning

This is a sentence.

在提交修改后，如果我们试图推送它就会得到这个消息：

(chapter-3-collaboration)$ git push origin chapter-3-collaboration
To github.com:johnmosesman/practical-git-tutorial.git
 ! [rejected]        chapter-3-collaboration -> chapter-3-collaboration (non-fast-forward)
error: failed to push some refs to 'git@github.com:johnmosesman/practical-git-tutorial.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

我们的队友已经在我们之前做了一些提交，并推送到了远端分支。我们的本地分支现在与远端分支不一致， 直到我们合并队友的修改前 GitHub 会持续拒绝我们的推送。

... the tip of your current branch is behind its remote counterpart. Integrate the remote changes ... before pushing again.

它也给了我们一个如何操作的提示： git pull。

(chapter-3-collaboration)$ git pull origin chapter-3-collaboration
From github.com:johnmosesman/practical-git-tutorial
 * branch            chapter-3-collaboration -> FETCH_HEAD
Auto-merging chapter-3.txt
CONFLICT (content): Merge conflict in chapter-3.txt
Automatic merge failed; fix conflicts and then commit the result.

在拉取后——正如我们可能已经预料到的那样，考虑到我们目前正在讨论的主题——我们有一个合并冲突。

Git 试图将我们队友的修改自动合并到我们的文件中，但文件中有一个地方它不能自动合并——我们都修改了同一行。

Git 在“合并中途”停止了工作，并告诉我们在完成合并之前需要修复合并冲突。让我们看看当前的 git status ：

(chapter-3-collaboration)$ git status
On branch chapter-3-collaboration
Your branch and 'origin/chapter-3-collaboration' have diverged,
and have 1 and 1 different commits each, respectively.
  (use "git pull" to merge the remote branch into yours)

You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Unmerged paths:
  (use "git add <file>..." to mark resolution)
        both modified:   chapter-3.txt

no changes added to commit (use "git add" and/or "git commit -a")

Git 告诉我们，我们的分支和远端分支之间有一个不同的提交，它还告诉我们，我们有一些“未合并的路径（unmerged paths）”——我们目前正在合并中途，需要修复冲突。

它显示 chapter-3.txt 目前已被修改，那让我们来看看 chapter-3.txt 的内容：

(chapter-3-collaboration)$ cat chapter-3.txt
<<<<<<< HEAD
Chapter 3 - The End Is Only The Beginning
=======
Chapter 3 - The End But Not The Ending
>>>>>>> 2f6874f650a6a9d2b7ccefa7c9618deb1d45541e

This is a sentence.

Git 在文件中添加了一些标记以显示冲突发生的位置。我们和队友都修改了标题，所以它被 Git 的冲突标记包裹着： <<< 和 >>> 箭头，以一行 === 分隔。

最上面的一行，以 <<<<<<< HEAD 为标志，后面是 "Chapter 3 - The End Is Only The Beginning" ，是我们刚刚做的修改。 Git 告诉我们，这一行是我们当前 HEAD 所在的位置——也就是说，这是我们当前提交的修改。

它下面的一行，"Chapter 3 - The End But Not The Ending" 后面跟着 >>>>>>> 2f6874f650a6a9d2b7ccefa7c9618deb1d45541e ，是我们队友的行和提交。

基本上， Git 是在告诉我们，“你想保留这些行（或这些行的组合）里的哪一条？”

你会注意到文件底部那一行没有被冲突标记包裹——他没有被两个提交同时修改。

我们需要通过删除一行或将两行合并为一行来解决冲突（记得也要删除 Git 放在那里的所有额外标记）。

我将组合这些行，所以最后的文件看起来像这样：

(chapter-3-collaboration)$ cat chapter-3.txt
Chapter 3 - The End Is Not The Ending--But Only The Beginning

This is a sentence.

我们只需要提交我们的冲突解决方案来完成合并：

(chapter-3-collaboration)$ git add .
(chapter-3-collaboration)$ git commit -m "Merge new title from teammate"
[chapter-3-collaboration bd621aa] Merge new title from teammate

(chapter-3-collaboration)$ git status
On branch chapter-3-collaboration
Your branch is ahead of 'origin/chapter-3-collaboration' by 2 commits.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

git status 的结果告诉我们，我们的本地分支比 origin/chapter-3-collaboration 领先两个提交（ is ahead of 'origin/chapter-3-collaboration' by 2 commits.）。

看一下 git log 就可以证明这一点：

commit bd621aa0e491a291af409283f5fd1f68407b94e0 (HEAD -> chapter-3-collaboration)
Merge: 74ed9b0 2f6874f
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Thu Mar 25 09:20:42 2021 -0500

    Merge new title from teammate

commit 74ed9b0d0d9154c912e1f194f04dbd6abea602e6
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Thu Mar 25 09:02:03 2021 -0500

    New title

commit 2f6874f650a6a9d2b7ccefa7c9618deb1d45541e (origin/chapter-3-collaboration)
Author: John Mosesman <johnmosesman@gmail.com>
Date:   Thu Mar 25 08:58:58 2021 -0500

    Update title

...

由此产生的提交历史中，分支上的提交和我们的合并提交都在顶部。

从这里，我们只需要把我们的修改推送到远端：

(chapter-3-collaboration)$ git pull origin chapter-3-collaboration
Enumerating objects: 10, done.
Counting objects: 100% (10/10), done.
Delta compression using up to 16 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 647 bytes | 647.00 KiB/s, done.
Total 6 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), completed with 1 local object.
To github.com:johnmosesman/practical-git-tutorial.git
   2f6874f..bd621aa  chapter-3-collaboration -> chapter-3-collaboration

现在我们已经改变了远端分支，我们的队友需要做一个 git pull 来合并我们新的合并修改。

而且，最好是告诉我们的队友，我们推送了一个新的修改，这样他们就可以在继续编辑之前把它拉取下来——减少他们在未来也要修复合并冲突的可能性。

在分支上创建分支

我们也可以在 chapter-3-collaboration 分支上创建自己的分支。这将使我们直到工作最后才需要解决合并冲突。

当我们在自己的独立分支上完成了工作，我们就可以将 我们 的功能分支合并到 队友 的功能分支上，然后再合并到 main。

chapter-3-collaboration-john -> chapter-3-collaboration -> main

正如你所看到的，随着越来越多的分支彼此分离，并成为彼此的前分支和后分支，分支结构会变得相当复杂。

因此，一般来说，保持分支的 **小而独立 (small and isolated) ** 并尝试 快速和经常合并它们（merge them quickly and often） 是个好主意。

这可以帮助避免很多痛苦的合并冲突。

回顾：如何启动一个新的功能工作流程

最后，我将快速的回顾一下如何着手开始一个新的任务，以及做这个任务需要的命令和流程。

假设你在新工作中得到了第一个任务：处理你的团队产品中的一个小错误（bug）。

你需要做的第一件事时使用 git clone <URL> 拉取该仓库。

接下来，你要用 git checkout -b <BRANCH_NAME> 在 main 之外创建一个功能分支。之后，你将修复这个错误，并使用 git add 和 git commit 提交修改。

也许解决这个问题需要进行多次提交，或者你在试图解决这个问题时做了多次提交，最后才找到了解决方案。这也是可以的。

提交后，将新分支推送到 origin （git push origin <BRANCH_NAME>）并创建一个拉取请求。经过代码审查，你的分支被合并了（耶！）。

现在你已经完成了你的功能，是时候切换回 main 了（使用 git checkout main），使用 git pull 获取你的最新修改和其他人的修改，然后从新的分支开始。

总结

正如开头所提到的，使用 Git 和 Git 工作流程有很多种方法。

还有很多 Git 底层的“魔法”（也就是说，正在运行的代码你还不了解），但是随着时间的推移，你会学到并掌握更多东西。

在我职业生涯的前几年，我只是通过记忆命令和工作流程来使用 Git，这很有效。当我遇到问题或与队友协作时，我学到了更多的东西，最终我的 Git 技能得到了扩展。

刚开始的时候，不要把事情搞得太复杂！随着时间的推移，你会学会的。

如果你喜欢这篇文章，我在我的网站上写像这样的技术话题以及非技术话题。

我也在推特（Twitter）@johnmosesman 上写相似的东西。

无论怎样，请随时给我发信息。

谢谢阅读！

John

原文：How to Use Git and Git Workflows – a Practical Guide，作者：John Mosesman