学习总结

学习datawhale的git教程。Pull Requests：PR，是github中将修改过的代码分支合并到目标分支的操作。commit是git的最小工作单元，在github的仓库中，PR是主要的工作单元。Pull Requests字面的翻译是拉取请求，在gitLab中，PR的操作叫做Merge Request，可以把PR理解为“我修改好了你的代码，现在请求你把代码拉回主仓库中”。
具体的PR操作（可参考这篇—git基本命令、提交pr）：
- 将需要进行pr(Pull Requests)操作的源项目fork到自己的github；
- 然后通过命令行克隆fork到自己github的项目；
- 然后再开发分支创建自己的新分支，基于自己的新分支进行相关操作；
- 然后git push origin 自己的新分支名，再根据产生的pull链接在github页面进行pr相关的操作，然后创建pr，最后就是等待合并审核。

七、Git提交规范

Git是目前程序员必备基础技能，可以用来管理代码、文档、博客，甚至菜谱。个人的私有仓库的提交相对而言可以较为随意，但是在团队开发中，还是要遵循相应的规范。

在这里插入图片描述

如上图所示（截取自Angular commit 970a3b5），
一个commit包含如下几个信息：

commit message - 提交的内容相关描述
author & committer - 作者及提交者
changed files - 修改的文件
hash & parent - 提交内容的hash及在提交树上的位置

7.1 Commit Message

提交消息描述的是当前提交的功能相关信息，一般可以包括header，body，footer，

<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

业内做的好的可以参考Angular的提交标准：Commit Message Format

其中header是必须的。Angular官方建议的格式如下

<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │       │
  │       └─⫸ Commit Scope: animations|bazel|benchpress|common|compiler|compiler-cli|core...
  │
  └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test

<header>中，<type>与<summary>是必须的，<scope>可以选填。建议<header>需要保持在50个字符之内。

（1）<type>表明本次提交的类型，一般有如下几种：

build: 涉及构建相关的改动
ci: 持续集成相关的改动
docs: 文档
feat: 新功能
fix: bug修复
perf: 性能相关改动
refactor: 重构相关（非bug、非新功能）
test: 测试相关，包括新增测试或者更改已有测试

（2）<scope>表示改动影响的范围。在Angular中，某个提交可能涉及的范围有表单处理、动画处理等。在实际工作中可以视项目而定。

（3）<summary>则是对本次提交的简要描述，使用祈使句、现在时。如使用change而不是changed或changes。

（4）<body>是提交信息的更为详细的描述，与<header>一样也是用祈使句、现在时。

（5）<body>描述本次修改的动机，比如为什么引入本次改动，之前的逻辑是什么，现在的逻辑是什么，本次改动有哪些影响，等等。

（6）<footer>是可选项，一般涉及破坏性改动、功能的弃用等说明，以及对GitHub issue或Jira ticket的引用，PR的引用等。

规范的提交信息可以使用工具对内容进行解析，自动化生成文档或者发布日志。在一些大型的开源项目中，版本的更新文档，接口的更新及兼容性影响，纯粹靠人工整理是很费时费力的，用统一的规范能够极大自动化这部分工作。当然不同的项目对提交信息的要求和格式标准也不一样，开源项目或者公司项目对提交信息的要求也有差异，一般需要遵从所在项目的约定。较为成熟的开源项目一般可以在README文档中找到如何贡献，或者有单独的CONTRIBUTING.md文档，对代码风格、提交方式等进行约定。

（1）动化校验`commit message`

有了提交信息的规范，如何确保开发者对规范进行遵守呢？我们可以使用Git提供的Git Hooks功能对提交的信息进行校验。这里仅对Git Hooks做基础的说明，具体细节可以参考官方文档或Atlassian的文档。

在新初始化的git项目内，可以在.git/hooks文件夹中找到官方提供的样例：

ls -l .git/hooks
total 120
-rwxr-xr-x  1 tomo  staff   478B Nov 11 20:44 applypatch-msg.sample
-rwxr-xr-x  1 tomo  staff   896B Nov 11 20:44 commit-msg.sample
-rwxr-xr-x  1 tomo  staff   4.5K Nov 11 20:44 fsmonitor-watchman.sample
-rwxr-xr-x  1 tomo  staff   189B Nov 11 20:44 post-update.sample
-rwxr-xr-x  1 tomo  staff   424B Nov 11 20:44 pre-applypatch.sample
-rwxr-xr-x  1 tomo  staff   1.6K Nov 11 20:44 pre-commit.sample
-rwxr-xr-x  1 tomo  staff   416B Nov 11 20:44 pre-merge-commit.sample
-rwxr-xr-x  1 tomo  staff   1.3K Nov 11 20:44 pre-push.sample
-rwxr-xr-x  1 tomo  staff   4.8K Nov 11 20:44 pre-rebase.sample
-rwxr-xr-x  1 tomo  staff   544B Nov 11 20:44 pre-receive.sample
-rwxr-xr-x  1 tomo  staff   1.5K Nov 11 20:44 prepare-commit-msg.sample
-rwxr-xr-x  1 tomo  staff   2.7K Nov 11 20:44 push-to-checkout.sample
-rwxr-xr-x  1 tomo  staff   3.6K Nov 11 20:44 update.sample

涉及提交相关的是下面四个：

pre-commit - 在Git生成commit对象前执行
prepare-commit-msg - 在pre-commit后执行，用以生成默认的提交信息，脚本接收三个参数：
1. 包含提交信息的临时文件名
2. 提交的类型，如message, template, merge, squash
3. 相关提交的SHA1，仅在有-c, -C或--amend参数时提供该参数
commit-msg - 在开发者编写提交信息后执行，仅有临时文件名一个参数
post-commit - 在commit-msg后立马执行，更多做通知用

我们可以用prepare-commit-msg对提交信息规范做说明，并用commit-msg对规范的执行进行检查，脚本的非0的返回会中断本次提交。

如我们想应用简单的类似Angular的<header>的格式，可以参考如下的实现。

下面是prepare-commit-msg的示例：

#!/usr/bin/env python

import sys, os, re
from subprocess import check_output

# Collect the parameters
commit_msg_filepath = sys.argv[1]
if len(sys.argv) > 2:
    commit_type = sys.argv[2]
else:
    commit_type = ''
if len(sys.argv) > 3:
    commit_hash = sys.argv[3]
else:
    commit_hash = ''

print("prepare-commit-msg: File: %s\nType: %s\nHash: %s" % (commit_msg_filepath, commit_type, commit_hash))

msg_spec = '''# Please use follow format
# <type>(<scope>): <short summary>
#  │       │             │
#  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
#  │       │
#  │       └─⫸ Commit Scope: animations|bazel|benchpress|common|compiler|compiler-cli|core
#  │
#  └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test'''

with open(commit_msg_filepath, 'r+') as f:
    f.write("\n" + msg_spec)

sys.exit(0)  # return non-zero will abort current commit

下面是简单的commit-msg示例：

#!/usr/bin/env python

import sys, os, re
# Collect the parameters
commit_msg_filepath = sys.argv[1]
print("commit-msg: File: %s" % commit_msg_filepath)

header_pattern = re.compile(r'^(?P<type>\w+)(\((?P<scope>\w+)\))?: .+$')
commit_types = 'build|ci|docs|feat|fix|perf|refactor|test'.split('|')
commit_scopes = 'animations|bazel|benchpress|common|compiler|compiler-cli|core'.split('|')

with open(commit_msg_filepath, 'r') as f:
    commit_msg_header = f.readline().rstrip('\n')  # header line
    print('<header>: %s' % commit_msg_header)
    match = header_pattern.match(commit_msg_header)
    if not match:
        print('commit message does not meet spec')
        sys.exit(1)
    commit_type = match.group('type')
    commit_scope = match.group('scope')
    if commit_type not in commit_types:
        print('invalid <type>')
        sys.exit(1)
    if commit_scope and commit_scope not in commit_scopes:  # scope is optional
        print('invalid <scope>')
        sys.exit(1)

sys.exit(0)

想使用相关的Git Hooks，可以在目录.git/hooks创建对应的文件，文件名为prepare-commit-msg
及commit-msg，并赋予可执行权限。这样在我们进行git commit操作时，对应的脚本就会执行。
下图是相关执行示意图，其中不合规范的提交会被中断。

在这里插入图片描述

具体执行过程可以参考在线执行过程

Git的提交不会包含.git目录，所以对应的hooks的改动并不会被提交到仓库中。我们可以在仓库根目录
创建.githooks文件夹并将我们实现的代码放到该目录中，通过更改配置或者软连接的方式进行引用：

# use config
git config core.hooksPath .githooks
# OR use soft link
ln -sf .githooks/* .git/hooks

当然这些都是客户端的校验，开发者可以完全忽视这样的一些Git Hooks的配置并引入不合规范的提交，这种情况下我们可以使用服务端校验进行处理，或者引入一些CI工具或使用GitHub Action进行校验。

7.2 Author & Committer

Git中，Author表示原始纂写该提交的作者，Committer表示应用该提交的人，如合并Pull Request的项目管理员。如果是个人开发者或只使用单个Git平台服务（如GitHub、BitBucket等），我们一般不需要对作者进行特别的配置。但如果使用多个Git平台或者有公司内部要求，我们可能需要针对不同的仓库设置不同的用户及邮箱，比如全局可以设置个人的GitHub账号，企业内部仓库设置企业邮箱等。

# 全局默认配置
git config --global user.email "<github email>"
git config --global user.name "<github username>"

# 企业内部仓库
git config user.email "<enterprise email>"
git config user.name "<real name>"

7.3 Changed files

我们所有的提交，核心的其实我们提交的文件。不同的提交涉及的文件可多可少，一般遵循以下一些原则：

提交前使用git diff查看文件的改动，使用git add添加期望进入提交的文件，使用git status查看文件状态，最终使用git commit进行提交
单次提交仅提交相关的改动，例如修复两个不同的bug应该使用两次独立的提交
鼓励经常性的提交，这样可以更快的分享实现的功能，并且减少代码丢失的风险；但在主分支或者协作的功能分支不能提交半成品，提交之前需要进过测试
编译输出，日志，中间产物等，不要引入到提交中，使用.gitignore进行相关文件的排除，不同语言或者操作系统有一些通用的排除配置，参考github/gitignore。
密码、授权凭证、密钥等，不要提交。如AWS的certificate.csv文件或内容，
GCP的Service Account文件等，泄露到公开仓库会导致资源被不法分子使用，造成损失。同时由于Git的特性，想从历史提交中移除这类文件会较为困难，参考GitHub官方相关文档及描述
对于配置文件（如数据库连接信息等），一般使用配置模板，个人维护本地文件，且该文件在.gitignore中配置。或者使用git update-index --[no-]assume-unchanged <file>来忽略某些文件的改动
其他一些常用命令（请在明确知道其含义后使用）
- git reset <file> - 移除被添加的文件（提交之前），reset命令的其他可以查看帮助文档
- git clean -f - 移除较多的未被追踪的中间文件
- git checkout <file> - 回退对某个文件的改动（提交之前）

7.4 Hash & Parent

一般情况，commit hash及父节点信息我们不需要额外关注，但在特定场景下我们可能需要对commit进行修复或者其他处理。在这样的场景下，我们需要理解：

整个git的提交链，每个提交对应的父节点，分支间的共同祖先；
本地与远端的差异，尤其涉及rebase相关的操作时。
同时我们需要在整个提交中遵循项目使用的工作流模型，使用对应工作流模型中建议的操作（常见的工作流模型参考Atlassian文档）。

下面是一些实际开发过程中涉及的场景：

在自身的开发分支，某个功能涉及多个提交，在正式合并至主分支前对相关的提交进行整理，可以使用git rebase -i <commit>命令，对提交进行合并、废弃、修改提交信息等处理。需要注意的是如果提交已经发布到远端，需要使用git push -f进行覆盖（仅限个人开发分支）。下面是一个简单的例子及相关命令描述，常见的命令有pick, reword, fixup, drop等。

$ git rebase -i 8717c71fc
reword 27e67629b feat: some feature first commit
fixup 7a3f0cd25 feat: some feature second commit
fixup d9a9d7f04 feat: some feature third commit

# Rebase 8717c71fc..d9a9d7f04 onto 8717c71fc (3 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
#                    commit's log message, unless -C is used, in which case
#                    keep only this commit's message; -c is same as -C but
#                    opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
# .       create a merge commit using the original merge commit's
# .       message (or the oneline, if no original merge commit was
# .       specified); use -c <commit> to reword the commit message
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.

在一些Git工作流模型中，使用git pull --rebase对本地提交进行更新
原则上禁止对主分支等进行git push -f操作，涉及需要回退的，使用git revert <commit>
涉及多分枝代码同步，可以使用git cherry-pick命令

7.5 练习

基于上面7.1中（1）自动化校验commit message方案，实现README.md中提交信息规范的git-hook的实现。

在这里插入图片描述

八、Github/Gitee使用说明

Github是一个使用Git作为版本管理工具的代码托管平台。依赖于git的强大协作能力，Github是开源软件发展的主战场之一。

8.1 使用github托管代码

（1）创建仓库

Github上几乎所有的事情都是围绕着仓库展开的。我们首先来学习如何新建一个仓库并满足自己的开发需求。一个GitHub仓库实质上是一个包含了你的项目所有文件的文件夹。 .git文件夹也包含在其中用于版本控制。

登陆GitHub主页，点击右上角+号即可创建一个仓库，如下图：

在这里插入图片描述
点击后会跳转到新建仓库的表单，

注意：

github上的仓库一般都会包含readme文件，该readme文件会在项目页面进行展示
.gitignore文件可以用来忽略工作区的私有文件（例如本地配置、缓存文件、node_modules等）

在这里插入图片描述

点击绿色的code按钮，选择相应的协议即可拿到该项目的地址，在本地只需要clone下来就可以进行开发了，开发完成后push到原仓库即可

（2）仓库界面介绍

我们以vscode项目进行介绍，访问https://github.com/microsoft/vscode即可看到如下的界面：

在这里插入图片描述

1）页面的左上角：

Star：Star类似于朋友圈的点赞，给项目star代表了你对项目的认可
Fork：Fork操作实际上是创建一个仓库的副本，并将仓库的upstream指向原仓库

小问题：为什么要fork呢？为什么不直接push呢？
回答：fork方便了多人协作

Watch：Watch操作可以向你的邮箱中推送该仓库的推送信息

在这里插入图片描述

Issues：Issues在Github官方文档中被翻译为议题，作用是针对仓库的内容进行讨论（例如bug反馈/新功能推荐）

提示：Issues不等同于评论区，Issues板块应该专注于解决问题，不要在Issues中发一些和项目无关的内容，这样可能会消耗很多maintainer的精力。

Pull Requests：Pull Requests，简称PR，是github中将修改过的代码分支合并到目标分支的操作。commit是git的最小工作单元，在github的仓库中，PR是主要的工作单元。Pull Requests字面的翻译是拉取请求，在gitLab中，PR的操作叫做Merge Request，可以把PR理解为“我修改好了你的代码，现在请求你把代码拉回主仓库中”。
Action：Github Action 是GitHub推出的自动化构建工具，感兴趣的同学可以阅读文档
Projects：针对某一仓库的项目板（看板）

2）Wiki：存放一些介绍性的内容

Security：与安全相关
Insight：里面包含里项目的一些数据，包括代码贡献的时间分布图，每个人的贡献量等metric
discussion：vscode仓库中并没有开启discussion功能，这里展示一下wagtail社区的，该功能像一个真正的讨论区

在这里插入图片描述

8.2 提交issue

以vscode为例展示提交issue

在这里插入图片描述

进入Issues选项卡，可以看到vscode项目已经准备了一些模版，我们点击Bug report

在这里插入图片描述

提示：在提bug时，请尽可能详细的描述出bug发生的步骤以及所运行的环境（https://stackoverflow.com/help/minimal-reproducible-example）。一般来说，Issue是参与项目贡献的起点，一个高质量的Issue也会让maintainer更愿意交流、处理。

如果你是项目的maintainer，也可以通过右侧对该issue进行更详细的设置。

8.3 提交PR（重点）

如果你fork了一份项目代码并做了修改，并且希望将修改的代码合并进上游仓库中，就可以提交PR（全称是：pull request）

参考：基于向开源项目提PR的常见git操作

在这里插入图片描述

上图为vscode的pr界面，点击New pull request即可新建pr。

注意：不是所有的PR都会被合并，所以在提交PR前请先和maintainer进行沟通，并且在开发的过程中反馈进度，一种比较好的方式就是draft PR，如下图所示：

在这里插入图片描述

注意：
（1）在提交PR时，尽可能关联相关Issue，并说明你的代码解决了什么问题。
（2）draft PR表示该PR还没有开发完，项目的maintainer不需要进行reveiw和merge，只需要简单看看代码是否符合预期。

8.4 探索Github

对于大多数程序员来说，Github的一个重要用途就是学习别人的代码，看自己的任务有没有已经写好的轮子可以用。因此如何高效的探索Github也是很重要的，几种探索GitHub的小技巧：

GitHub Explore

点击GitHub最上方的Explore或输入https://github.com/explore即可进入。Explore板块不仅可以根据你的兴趣进行项目的推荐，而且Trending榜展示了当前综合热度最高的项目。关注Trending可以随时掌握整个Github的最新动向

在这里插入图片描述

补充 https://kamranahmed.info/githunt/也是一个追踪热门项目的网站

GitHub 快捷键

GitHub网站拥有一系列快捷键，你可以通过快捷键来完成你想要完成的动作，例如ctrl/command+k会调起一个类似于powertoy一样的搜索框，在这里你可以直接进行搜索。

在这里插入图片描述

类似的快捷键有很多，完整的快捷键见文档https://docs.github.com/cn/get-started/using-github/keyboard-shortcuts

高级搜索

高效的搜索方式可以节约你很多时间，例如下面代码可以帮助你找到Github中star量超过10000的项目

stars:>10000

在这里插入图片描述

其他搜索技巧可以参考上图红框中的链接

内置IDE — CodeSpace

在你的仓库界面，输入英文状态下的 .，即可进入该项目的web editor，这实质上是一个云端的vscode，方便用户查找编辑代码。很可惜现在CodeSpace还不能支持在线运行代码，一些简单的修改可以配合Action使用

Copilot

Copilot是Github通过公开代码训练的一个强大的代码补全工具，现在还在内测阶段，有感兴趣的同学可以在https://copilot.github.com/申请，这里不过多介绍了

用户主页

用户主页也是探索Github很好的地方，我的用户主页如下图

在这里插入图片描述

左边展示了你参与过的项目，右边展示了Github Explore推荐的项目，中间展示了你Follow的用户最近的动态通常来说，你Follow的用户越多，主页动态越精彩。

补充资料：思否今年做过一个中国开源爱好者榜单，有兴趣的同学可以看下https://github.com/OpenSourceWin/hacking-force

用数据探索GitHub–Github API

Github对针对开发者提供了一系列API，详情见https://docs.github.com/en/developers。通过API可以对数据采集分析，探索更微观的GitHub。也有开源项目专门做这件事情，例如open-digger开源项目（https://github.com/X-lab2017/open-digger），感兴趣的同学去自己探索下，这里也不多讲了。

练习一：github readme-profile练习

练习二：小组内PR练习（已完成）

8.5 国内其他代码托管平台简介

Gitee/Coding/jihulab

作为代码托管平台，Github由于网速等原因的限制，访问起来会很慢，这时可以采用国内的代码托管平台，这里我们只介绍下Gitee

网址：https://gitee.com/

Gitee整体的功能与github相差不大，这里就不多介绍了，等待大家的探索。

下面我们讲一下，如何通过Gitee 克隆Github上的项目

在Gitee创建仓库时，点击右上角点击导入

在这里插入图片描述

即可导入其他平台项目，并享受高速的克隆速度。非常方便～

如果大家想将代码回传到GitHub中，请复习git remote相关知识进行操作。

8.6 补充资料

（1）补充资料一：一些Git相关的开源仓库

Progit2:https://github.com/progit/progit2

git-cheat-sheet:https://github.com/arslanbilal/git-cheat-sheet

githug–一个ruby编写的git练习游戏:https://github.com/Gazler/githug

gitignore模版：https://github.com/github/gitignore

git-extras：https://github.com/tj/git-extras

git-recipes：https://github.com/geeeeeeeeek/git-recipes

（2）补充资料二：GitHub高赞项目推荐

awesome系列：

主仓库https://github.com/sindresorhus/awesome

周刊系列：

https://github.com/GrowingGit/GitHub-Chinese-Top-Charts

https://github.com/ruanyf/weekly

https://github.com/GitHubDaily/GitHubDaily

资源集合系列：

https://github.com/papers-we-love/papers-we-love

https://github.com/public-apis/public-apis

https://github.com/danistefanovic/build-your-own-x

https://github.com/GorvGoyl/Clone-Wars

https://github.com/TheAlgorithms

附：时间表

Task	任务信息	时间
Task01：	Git基础：第一、二章（2天）	16、17号，即周一周二
Task02：	Git分支管理及工具使用：第三、四章（2天）	18、19号，即周三周四
Task03：	Git内部原理及工作流实战：第五、六章（3天）	20、21、22号，即周五周六周日
Task04：	Git提交规范及Github/Gitee的使用：第七、八章（3天）	23、24、25号，即周一周二周三
Task05：	Git可视化工具下载和团队协作：第九、十章（3天）	26、27、28号，即周四周五周六

【git】(task4)git提交规范和github说明（更新ing）

学习总结

文章目录

七、Git提交规范

7.1 Commit Message

（1）动化校验`commit message`

7.2 Author & Committer

7.3 Changed files

7.4 Hash & Parent

7.5 练习

八、Github/Gitee使用说明

8.1 使用github托管代码

（1）创建仓库

（2）仓库界面介绍

1）页面的左上角：

2）Wiki：存放一些介绍性的内容

8.2 提交issue

8.3 提交PR（重点）

8.4 探索Github

8.5 国内其他代码托管平台简介

8.6 补充资料

（1）补充资料一：一些Git相关的开源仓库

（2）补充资料二：GitHub高赞项目推荐

附：时间表

Reference

猜你喜欢

【git】(task4)git提交规范和github说明（更新ing）

学习总结

文章目录

七、Git提交规范

7.1 Commit Message

（1）动化校验commit message

7.2 Author & Committer

7.3 Changed files

7.4 Hash & Parent

7.5 练习

八、Github/Gitee使用说明

8.1 使用github托管代码

（1）创建仓库

（2）仓库界面介绍

1）页面的左上角：

2）Wiki： 存放一些介绍性的内容

8.2 提交issue

8.3 提交PR（重点）

8.4 探索Github

8.5 国内其他代码托管平台简介

8.6 补充资料

（1）补充资料一：一些Git相关的开源仓库

（2）补充资料二：GitHub高赞项目推荐

附：时间表

Reference

猜你喜欢

（1）动化校验`commit message`

2）Wiki：存放一些介绍性的内容