Git提交规范

良好的代码习惯是保持项目高质量的关键

Table of contents

Step 1: Fork 仓库

操作：登录 GitHub，找到目标仓库，点击右上角”Fork”按钮，将仓库复制到个人账户。
结果：在 GitHub 上拥有原仓库的副本。

Step 2: Git 设置与下载

2.1、克隆 Fork 的仓库到本地（使用 SSH URL 或 HTTPS），对自己的Fork仓库在本地进行工作

git clone git@github.com:<Your-Username>/<Repo-Name>.git

git clone会自动执行

git remote add origin git@github.com:<Your-Username>/<Repo-Name>.git

origin 就是本地仓库默认的远程仓库名称。

2.2、添加原仓库（Fork 的源仓库）作为 upstream 远程

git remote add upstream git@github.com:<Original-Owner>/<Repo-Name>.git

2.3、获取 upstream 数据。Fork 仓库不会自动同步原仓库的变更，需要手动拉取更新

git fetch upstream

2.4、切换到本地 main 分支，准备进行合并操作

git checkout main  # 或 master，取决于项目默认分支

2.5、将原仓库 (upstream) 的最新代码合并到本地的 main 分支

git merge upstream/main

Step 3: 创建并发布工作分支

3.1、创建并切换到新分支，遵循命名规则

git checkout -b <type>/<issue|issue-number>/{<additional-fixes>} # 相当于git branch <branch-name> git checkout <branch-name>

分支命名规则：

• wip：进行中的工作（长期主流变更）。
• feat：新功能（未来计划的非主流变更）。
• bug：错误修复。
• exp：实验性功能。

示例：feat/123/add-login-auth 表示 issue #123 的新功能分支。

3.2、推送分支到 Fork 仓库

git push origin <type>/<issue|issue-number>/{<additional-fixes>}

一个分支应专注于一个逻辑变更（如一个功能或修复）。

工作完成后

Step 4: 提交和推送更改

4.1、确认当前分支

git branch

4.2、同步 upstream 主分支，原仓库的主分支可能会有更新，使用 git fetch 和 git merge 确保自己的工作不会与这些更新产生冲突

git fetch upstream
git merge upstream/main

4.3、编辑文件后添加更改

git add .

4.4、提交更改，使用规范（Git提交信息规范）的提交信息

git commit -m ""

4.5、再次同步（确保无冲突）

git fetch upstream
git merge upstream/main

4.6、推送更改到 Fork 仓库

git push origin <type>/<issue|issue-number>/{<additional-fixes>}

Step 5: 在 GitHub 上创建 Pull Request

操作：

在 GitHub 上访问 Fork 仓库。

• 找到分支 /<issue|issue-number>/{}，点击”New Pull Request”。
• 设置 PR 从自己的分支指向 upstream/main（或项目默认分支）。
• 添加 Reviewer（管理员）和自己作为 Assignee。
• 关联相关 Issue（如 Resolves #123）或 Project/Milestone。
• 提交 PR，等待审核。

注意： 不要自行合并 PR，除非管理员明确要求。
检查项目指南，可能有分支命名或 PR 提交要求（Scott 建议）。

Step 6: PR 合并后的清理

6.1、删除本地分支。删除已经完成工作或已经合并到主分支的分支，保持分支列表简洁，减少混乱。

git branch -d <type>/<issue|issue-number>/{<additional-fixes>}

6.2、删除 Fork 仓库中的远程分支。一旦分支上的工作完成并且已合并到主分支，删除远程分支是为了避免积累过多的未使用分支，保持仓库干净整洁。

git push --delete origin <type>/<issue|issue-number>/{<additional-fixes>}

6.3、切换到主分支

git checkout main

6.4、从原仓库（upstream）的主分支拉取最新的更改并合并到本地的 main 分支。确保本地的主分支是最新的，包含了所有来自原仓库的更改。

git pull upstream main

6.5、更新 Fork 仓库的主分支

git push origin main

Step 7: 保持 Fork 同步

7.1、定期同步。Fork 不会自动与原仓库同步，需手动执行。

git checkout main
git pull upstream main
git push origin main

OTHER

Git提交信息规范

• 用空行分隔主题和正文：主题是简短总结（通常单行），正文提供详细说明，便于工具如 git log 区分。
• 主题行限制在 50 个字符：保持简洁易读，强制作者提炼核心内容。
• 主题行首字母大写：标准化格式，提升可读性。
• 主题行不以句号结尾：节省字符，避免冗余。
• 主题行使用祈使语气：如”Fix bug”而非”Fixed bug”，与 Git 默认行为一致，便于理解”此提交将要做什么”。
• 正文换行在 72 个字符：确保文本在终端显示时整洁，通常配合编辑器设置实现。
• 正文解释”是什么”和”为何”，而非”如何”：代码已展示”如何”，提交信息应聚焦变更原因和背景。

示例

git commit 
-m "Git Submission Topics" 
-m "
Use the body to explain what and why
Resolves: #Issue No."

提交类型参考表