Just Notes
0%

Git 指北

Posted on Edited on In

本指南暂不包含 fetch , pull, push, clone 等 Git 版本库操作和 CI/CD 工作流搭建等

一、版本规范：

结合 semver 语义化版本以及 software release life cycle 软件发布生命周期两块概念，约定 git tag 标签规则

格式命名

基础版本格式：

<主版本号>.<次版本号>.<修订版本号> 三位数字用 . 连接组成一个版本号，如 1.0.0
版本号数字递增规则：

  • 主版本号：对代码进行了不向前兼容的修改
  • 次版本号：向前兼容的修改，只是新增了功能
  • 修订版本号：向前兼容的故障修复、需求细节变更

    细化版本格式：

    在原来 x.y.z 基础版本号后面添加软件生命周期作为先行版本号，以及添加附加信息（编译信息、时间戳、序号等）来进一步细化控制版本
  • 先行版本号：表示在正式版之前发布的版本，并非稳定而且可能无法满足预期的兼容性需求，格式是标注在修订版之后，先加上一个连接号-, 再加上一连串以句点分隔的标识符来修饰, 。范例：1.0.0-alpha.1、1.0.0-rc.22、1.0.0-beta.33 …

    常见的先行版本

    • alpha: 内测版本，通常提测至测试部
    • beta: 公测版本，通常可以面向用户全量或者灰度发布
    • rc: 即 Release candiate，正式版本的候选版本，用作预发布
      注：这些版本的发布可能需要团队的工作流程以及部署环境的隔离去支撑
  • 版本编译信息: 可以在修订版或先行版本号之后，先加上一个加号再加上一连串以句点分隔的标识符来修饰。范例：1.0.0+jested、1.0.0-alpha+001、1.0.0-rc+20130313144700、1.0.0-beta+exp.sha.5114f85、1.0.0-next+0…

创建标签

1
2
3
4
# 创建
$ git tag -a "x.y.z-alpha+timestamp" -m "summary..."
# 推送
$ git push --tags

常用命令行:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# < xxx > just means variable

# List tags
$ git tag

# Show details of the tag
$ git show <TAG Name>

# Add tag to newest commit
$ git tag <TAG Name>

# Add tag to specified commit
$ git tag <TAG Name> <Commit Hash ID>

# remove tag (local)
$ git tag -d <TAG Name>

# remove tag (remote)
$ git push <Host Name> :refs/tags/<TAG Name>
$ git push <Host Name> :<TAG Name>
$ git push --delete <Host Name> <TAG Name>
$ git push -d <Host Name> <TAG Name>

# Push specified tag to remote
$ git push <Host Name> <TAG Name>

# Push all tags to remote
$ git push <Host Name> --tags

# Fetch all tags from remote
$ git fetch --tags

# Create a new branch from the TAG
$ git checkout -b <New Branch Name> <TAG Name>

二、提交规范

提交人

根据团队约定，从项目维度上去设置<用户名>和<邮箱>,不影响开发着全局配置

方法一：进入当前项目根目录，执行如下命令

1
2
3
4
5
6
7
8
# 列出全局配置信息
$ git config --global -l
# 列出项目当前的配置信息，没有字段的将继承全局，相同的字段将优先于全局
$ git config --local -l

# 设置当前项目
$ git config --local user.name xxx
$ git config --local user.email xxx

方式二： 在当前项目根目录 .git/config 配置文件中设置

1
2
3
[user]
name = xxx
email = xxx

提交风格


如上图为 AngularJS 开源仓库参考 Google’s JavaScript Style Guide 制定并使用的提交风格，目前前端开源生态普遍遵循。
这样统一标准的提交好处是：

  • 降低 Code Review 成本
  • 标准化结构化的提交消息文本格式，便于 git log 格式化打印输出日志如 git log --format='%s (%h)' --reverse --grep '^\(feat\|fix\)' --since=2020-01-01 或者直接借助一些工具可自动化地“一键”生成 Change Log
  • 便于追溯历史时快速搜索过滤

提交的消息格式如下：

1
2
3
4
5
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

  • 每次提交可以包含页眉(header)、正文(body)和脚注(footer)
  • 每次提交必须包含页眉内容，其他可选
  • 每次提交的信息尽量不超过 100 个字符

具体说明文档：

Commit vs Issue

1. 自有的Issue 系统事务操作

Github 、 Gitlab 等都提供了关键字，允许在提交 commit message 中通过声明关键字以及对应的 ISSUE- NUMBER 来操作事务

1) Github 关闭事务
keywords
  • close,closes,closed,Close,Closes,Closed,
  • fix,fixes,fixed,Fix,Fixes,Fixed
  • resolve,resolves,resolved,Resolve,Resolves,Resolved
syntax
  • 同一个仓库 KEYWORD #ISSUE-NUMBER, 如 Closes #10
  • 不同的仓库 KEYWORD OWNER/REPOSITORY#ISSUE-NUMBER, 如Fixes octo-org/octo-repo#100
  • 多个Issue <full syntax>, <full syntax>, ..., 如 Resolves #10, fix #123, closes owner/octo-repo#100
2) Gitlab 关闭事务
keywords syntax pattern
1
\b((?:[Cc]los(?:e[sd]?|ing)|\b[Ff]ix(?:e[sd]|ing)?|\b[Rr]esolv(?:e[sd]?|ing)|\b[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?: *,? +and +| *,? *)?)|([A-Z][A-Z0-9_]+-\d+))+)
all keywords
  • Close, Closes, Closed, Closing, close, closes, closed, closing
  • Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing
  • Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving
  • Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing
examples
  • 当前项目仓库的 issue , 如 close #123
  • 组内跨仓库的 issue, 如 fix group/project#123
  • 直接链接其他仓库 issue, 如 Resolve https://gitlab.example.com/group/project/issues/123

2. 第三方事务管理系统

Git 服务端推荐优先私有化部署 GitLab 以支持集成第三方事务管理系统
第三方事务管理系统可以是 Jira 、 禅道等

Git 可以与 Jira 、禅道 等第三方相互集成后，就可以同样通过关键字来直接操作事务，区别是操作的事务的编号将以第三方提供的信息为准

提交操作

CLI 手动

以下适用于 Mac OS X (or Linux like Ubuntu)

1. 准备一个 *.txt 作为提交模版

打开 template 后另存为到本地，建议存放在 home 目录 ～/ 下, 并可选择性地重命名为 .git-commit-template.txt 隐藏文件

2. Git 配置提交模版

直接运行命令

1
$ git config --global commit.template ～/.git-commit-template.txt

或者在 ～/.gitconfig 中编辑 git 配置项：

1
2
[commit]
template = ～/.git-commit-template.txt
3. Git 配置默认编辑器

配置默认 git 默认编辑器，建议同自己的代码编辑器，例如 vscode:

1
2
[core]
editor = code -w  ( -w 参数必须 ，代表等待提交信息编辑完成)

test

在 Terminal 中 执行 git commit 回车，自动使用配置的默认编辑器调起配置好的“提交模版”

Done, 编写完提交信息文本保存后关闭则提交成功，如果未保存关闭则退出保存，提交成功可以 git log 查看提交信息, 也可以在 push 前， 通过 git commit --amend 堪误本次提交信息。

CLI 脚本工具

IDE 插件

像 IntelliJ IDEA 此类集成 GIT 的开发环境，可以直接安装一些第三方插件，如

三、发布管理

CHANGELOG 变更日志

Change Log 属于软件发布生命周期，面向内部协作。
在项目根目录书写 CHANGELOG.md，如：

通常在遵循提交规范后，直接使用类似 conventional-changelog 这样的工具可以一键生成 Change Log。

Release Notes 发行说明

与 Change Log 同属于软件发布生命周期，区别是 Release Notes是面向外部交付的
Release Notes 没有标准格式可循，通常根据要传播表达的信息的要求来采用定制化的格式样式。

Release Notes 可能包括以下部分：

  • Header – 文档名称（即发行说明）、产品名称、发行编号、发行日期、注释日期、注释版本等。
  • 概述 - 在没有其他正式文档的情况下，对产品和更改的简要概述。
  • 目的 - 简要概述发行说明的目的，并列出此版本中的新增功能，包括错误修复和新功能。
  • 问题摘要 - 对该版本中的错误或增强功能的简短描述。
  • 重现步骤 - 遇到错误时遵循的步骤。
  • 解决方案 - 为修复错误而进行的修改/增强的简短描述。
  • 最终用户影响 - 应用程序的最终用户需要哪些不同的操作。这应该包括其他功能是否受到这些更改的影响。
  • 支持影响 - 管理软件的日常过程中所需的更改。
  • 注释 - 有关软件或硬件安装)、升级和产品文档（包括文档更新）的注释
  • 免责声明 - 公司和标准产品相关信息。例如; 免费软件、反盗版、复制等。另见免责声明。
  • 联系 - 支持联系信息

GitLab 和 GitHub 均将 Release Notes 功能集成在 Tags 中，当 Tag 推送到远程仓库，可以找到 Tag 对应的编辑按钮，在远程仓库直接在线编写 Release Notes
如 React 版本库：

参考资料：

四、README

始终遵循 规范 书写 README.md 将利于项目维护以及交接流转。

五、分支管理

Renaming default branch, ‘master’ to ‘main’

由于 cultural sensitivity ，2020年, 计算机行业对 master，slave 这两个词的使用引起了关注，这两个词被认为 harmful and antiquated ，不适合作为行业术语，同时也引发了众多抗议。
GitHub 根据 Conservancy 的建议 采取了行动，并在 Git 存储库初始化时不再使用术语 master， 因此，GitHub 将默认分支从 master 重命名为了 main。

相关资料：

模型

  • 生产/开发模型 main/dev
  • 特性/发布模型 main/dev/feat
  • 开发/发布分离模型 main/dev/feat/release
  • 开发/发布/缺陷分离模型 main/dev/feat/release/hotfix

常驻分支

main 主干分支（锁定，被保护），仅用于发布新版本，必须限制任何角色包括管理员自己在此分支上的任何提交操作，只允许管理员在此分支上进行 merge request or pull request 请求，以及进行打版本标签的操作，同时搭建好 CI/CD 流程，理论上每当对 main 分支有一个合并操作，就可以自动触发 Git 钩子脚本来构建并且发布软件到生产服务器。
​
dev开发分支（非锁定），平时干活的地方。每当发版时，需要被合并到 main。对于简单的项目而言，这样的分支模型已经够用了。

辅助分支 (临时分支)

除了常驻分支，通常大的特性开发或生产缺陷修复还建议创建相应的临时分支。
因为：

  1. 在分支上开发可以让你随意尝试，进退自如，比如碰上无法正常工作的特性或补丁，可以先搁置，直到有时间仔细核查修复为止。
  2. 团队中如果有代码审查流程，独立的分支还可以留给审查者抽空审查的时间和改进代码的余地，并将是否合并、是否发布的权利留给审查者，为代码质量设一道门槛。

每一类分支都有一个特定目的，如何命名每一类分支？建议用相关的主题关键字进行命名，并且建议将分支名称分置于不同命名空间（前缀）下，例如：

分支 来源分支 合并分支 锁定 说明
feat-* dev dev NO 特性分支，为了开发新增特定功能而建
release-* dev dev,main YES 预发布分支，为了新版本的发布做准备，一般命名为release-<版本号>
hotfix-* main dev,main NO 补丁分支，为了修复生产缺陷而建，一般命名为 hotfix-<故障名或故障编号>

与常驻分支不同，这些辅助性分支总是有一个有限的生命期，等被合并到常驻分支之后，就应该会被移除掉。
​

六、扩展资料