git-docs

charlie / January 2015 (370 Words, 3 Minutes)

docs

Git Docs

Getting Start

每一个git项目的准备工作

如果本地 ~/.ssh/ 文件夹不存在或者为空，在本地命令行执行下面命令

apt-get install git
ssh-keygen -t rsa #三次回车

复制 id_rsa.pub文件内容到github: 登录 github -> Accounting settings -> SSH key -> Add SSH key -> 填写 SSH key的名称（可以起一个自己容易区分的），然后将拷贝的 .ssh/id\_rsa.pub文件内容粘帖 -> add key 按钮添加。

然后在github创建一个仓库 projeåct_name,本地创建相同名字的仓库 project_name。

根据下面的命令初始化本地项目

git init
git add . # 提交所有变动文件
git commit -m "first commit"
git remote add origin git@github.com:ai-charlie/project_name.git
git branch -M main
git push -u origin main

每一次提交常用命令

git pull # 拉取
git add . # 提交所有变动文件
git commit -m "XXX commit"
git push -u origin main

删除远程仓库命令

git remote rm origin

添加 git-lfs大文件存储

use Updated git hooks. Git LFS initialized.

apt-get install git-lfs
git lfs install

重置到某一次历史提交状态

设置远程项目允许强制推送

设置 -> 仓库 -> 受保护的分支 -> 允许强制推送

重置到某一历史提交状态å

git reset --hard 复制提交SHA

强制推送

git push origin main --force

常用顺序

git stash, git pull, git stash pop

github action

术语
- workflow
  - 持续集成一次运行的过程
- job
  - 一个workflow由一个或多个jobs构成
- step
  - 每个job由多个step构成，一步步完成
- action
  - 每个step可以一次执行一个或多个action
workflow文件
- 官方文档
  - https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
- 文件路径
  - .github/workflows目录下的.yml文件
- 基本字段
  - name
    - workflow的名称，如果省略该字段，默认为workflow的文件名
  - on
    - 触发workflow的条件，通常为某些事件
      - release
      - push
      - pull
      - pull_request
      - workflow_dispatch
        
        手动触发
  - jobs
    - workflow文件的主体内容，通常表示要执行的一项或者多项任务
      - name
        
        任务的描述
      - runs-on
        
        运行时所需要的虚拟机环境，必填字段
      - needs
        
        当前任务的依赖关系，即运行顺序
      - steps
        
        指定每个任务的运行步骤，可以包含一个或多个步骤

公司项目提交遵循规则

提交版本号设置

https://semver.org/lang/zh-CN/

版本格式：主版本号.次版本号.修订号，版本号递增规则如下：

主版本号：当你做了不兼容的 API 修改，
次版本号：当你做了向下兼容的功能性新增，
修订号：当你做了向下兼容的问题修正。

提交原则：

应该把握好提交的频率，尽量按照原子功能提交，并在每次commit时给与清晰简洁的注释。
在完成一个较完整的功能后，进行一次push动作。
如果多人在同一个分支开发，用fetch + rebase命令替代pull, 避免不必要的分支merge。
Merge代码时需要两人以上进行代码Review。

格式化的Commit message好处：

提供更多的历史信息，方便快速浏览。
可以过滤某些commit（比如文档改动），便于快速查找信息。
可以直接从commit生成Change log。

Commit message 格式：

每次提交Commit message应符合以下规范，包含三个部分：header, body和footer，其中 header 部分必选，body和footer可选，如下：

<type>: <subject> // header【必填】
// 空一行
<body> // body 【可选】
// 空一行
<footer> // footer【可选】
// 任何一行都不得超过72个字符

type

type代表某次提交的类型，比如是修复一个bug还是增加一个新的feature。

所有的type类型如下：

类型	意义
feat	新增 feature,[v版本号][需求简短说明][提交说明]
fix	修复 bug，有jira编号，附上jira编号
docs	仅修改了文档，比如README,CHANGELOG,CONTRIBUTE等等
style	只修改了代码格式：空格、格式缩进、换行等等，没改代码逻辑
refactor	代码重构，没有加新功能或者修复bug
perf	优化相关，比如提升性能、体验
test	测试用例，包括单元测试、集成测试等
chore	改变构建流程、或者增加依赖库、工具、变更版本号等
revert	版本回滚

详细说明

<header> 50个字符以内，描述主要变更内容
<body> 更详细的说明文本，建议72个字符以内。 需要描述的信息包括:
* 为什么这个变更是必须的? 它可能是用来修复一个bug，增加一个feature，提升性能、可靠性、稳定性等等
* 他如何解决这个问题? 具体描述解决问题的步骤
* 是否存在副作用、风险?
<footer> 如果需要的化可以添加一个链接到issue地址或者其它文档，或者关闭某个issue。

示例

// 需求开发过程中
feat: [G2 4.5.0][String UID][完成UserInfo功能开发]
// 文档更新，简明的细节说明
docs: 更新README.md
- 项目目录说明
- 新增提交例子

Merge request的MR message

和代码提交的 Commit message 类似，MR message 也需要遵循上面提到的格式规范，唯一不同的是：MR 的 message 里还需要增加一个 reviewer 的部分，即包含四个部分：reviewer 、header、body和footer，其中 reviewer 和 header 部分必选，body和footer可选。如下所示：

@Evan
// 空一行
<type>: <subject> // header【必填】
// 空一行
<body> // body 【可选】
// 空一行
<footer> // footer【可选】
// 任何一行都不得超过72个字符

示例如下：

@Evan
feat: [G2 4.5.0][String UID][完成UserInfo功能开发]