当前位置：首页 > news >正文

面向 GitHub 协作的 Git 实战规范：分支、PR、Actions 与常见事故处理

news 2026/5/28 8:21:56

面向 GitHub 协作的 Git 实战规范：分支、PR、Actions 与常见事故处理

源代码管理的重点不只是“保存历史版本”。在实际工程中，它承担的是变更治理：谁改了什么、为什么改、怎样审查、是否通过测试、能否安全回滚。对今天的大多数团队而言，这套治理通常建立在 Git + GitHub 之上。

Git 负责本地版本控制、提交、分支、合并与历史重写；GitHub 负责远程托管、Pull Request、代码审查、权限控制、CI/CD、Issue 与发布协作。本文不按“工具发展史”展开，而是以一个严肃项目的日常协作为主线，说明如何把 Git、GitHub Flow、GitHub Actions、分支保护、.gitkeep、submodule 和常见事故处理组合成一套可执行的工程规范。

适用读者：已经知道 git add、git commit、git push 的基本含义，但希望系统理解 GitHub 协作流程、误操作恢复和仓库治理的人。

1. 先建立正确边界：Git 是版本系统，GitHub 是协作系统

Git 是分布式版本控制系统。它可以在完全离线的本地环境中记录提交、创建分支、查看历史、回退版本。GitHub 则是围绕 Git 仓库构建的协作平台，提供远程仓库、Pull Request、代码审查、GitHub Actions、分支保护、CODEOWNERS、Issues、Releases 等能力。

可以把二者关系简化为：

层次	工具	责任
本地版本控制	Git	记录快照、管理提交、分支、合并、回退、重写历史
远程协作	GitHub	托管仓库、审查 Pull Request、保护主分支、触发自动化流程
自动化交付	GitHub Actions	在 push、pull_request、release 等事件发生后运行测试、构建、部署
治理与安全	Branch protection / Rulesets / CODEOWNERS / Secret scanning	限制直接推送、强制审查、强制状态检查、发现密钥泄露

一个成熟团队不应只问“怎么把代码 push 上去”，而应问：这次变更是否在独立分支开发？是否经过 Pull Request？是否有明确提交说明？是否通过 CI？是否由代码负责人审查？是否可以回滚？

2. Git 的基本模型：工作区、暂存区、本地仓库、远程仓库

理解 Git，不要从命令死记硬背开始，而要先理解它的数据流。Git 项目至少涉及四个位置：工作区、暂存区、本地仓库和远程仓库。

Git 的工作区、暂存区和本地仓库

图 1：Git 的 Working Directory、Staging Area 和 Git Directory。图片来源：Pro Git 官方文档。

区域	英文	作用	常见命令
工作区	Working Tree / Working Directory	你实际编辑的文件	`git diff`, `git restore`
暂存区	Staging Area / Index	下一次提交的候选内容	`git add`, `git restore --staged`
本地仓库	Local Repository	`.git` 目录，保存提交对象、树对象、引用等	`git commit`, `git log`, `git reset`
远程仓库	Remote Repository	GitHub 上的仓库副本	`git fetch`, `git pull`, `git push`

日常最小闭环如下：

# 查看当前修改
git status
git diff# 把需要进入下一次提交的内容放入暂存区
git add src/login.ts# 提交到本地仓库
git commit -m "fix: handle empty login token"# 推送到 GitHub
git push

暂存区的存在是 Git 与普通“保存文件”最大的差异之一。它允许你把一次复杂修改拆成多个清晰提交，而不是把所有文件一次性塞进一个模糊的 update 提交。

例如，你同时修改了登录逻辑和 README，应该拆成两个提交：

# 只暂存登录逻辑
git add src/auth/login.ts src/auth/token.ts
git commit -m "fix: reject expired login token"# 再暂存文档
git add README.md
git commit -m "docs: document login error codes"

如果只想暂存文件中的一部分修改，可以使用交互式暂存：

git add -p

这对保持提交粒度非常重要。提交粒度越清楚，后续审查、回滚、定位问题越容易。

3. Git 记录的是快照，不是简单差异

许多传统版本控制系统强调记录文件之间的差异。Git 的核心理解方式更接近“提交时保存项目快照”。如果某个文件没有变化，Git 不会重复保存完整文件，而是复用之前的对象引用。

Git 以快照方式理解项目历史

图 2：Git 将历史理解为一系列快照。图片来源：Pro Git 官方文档。

因此，Git 中的分支并不是复制一份完整代码目录，而是指向某个提交的可移动引用。创建分支的成本很低，切换分支也主要是在改变当前工作区对应的提交状态。

# 创建分支
git branch feature/login-page# 切换分支
git switch feature/login-page# 创建并切换，日常更常用
git switch -c feature/login-page

这解释了为什么 GitHub Flow 会鼓励“每个变更一个短生命周期分支”。在 Git 中，分支不是重型发布流程，而是日常工作单位。

4. 推荐主线：GitHub Flow，而不是复杂化的分支体系

对于多数课程项目、Web 项目、内部工具、小中型团队和开源仓库，默认建议采用 GitHub Flow。它比 Git Flow 更轻，不预设长期存在的 develop、release、hotfix 分支，而是围绕 main、短分支、Pull Request 和自动化检查展开。

GitHub Flow 官方示意图

图 3：GitHub Flow 中，feature 分支从 main 派生，经过提交、Pull Request、讨论后合并回 main。图片来源：GitHub Docs。

GitHub Flow 的基本规则如下：

main 始终代表可集成、可部署或至少可运行的状态。
所有变更都从 main 创建短生命周期分支。
开发者在功能分支上提交，并持续 push 到 GitHub。
通过 Pull Request 发起审查，不直接向 main 推送。
Pull Request 必须通过代码审查和 GitHub Actions 状态检查。
合并后删除功能分支，保持分支列表干净。

flowchart LRA[main: 稳定主线] --> B[创建短分支 feature/x]B --> C[本地修改并提交]C --> D[push 到 GitHub]D --> E[创建 Pull Request]E --> F[代码审查]E --> G[GitHub Actions: 测试/构建/扫描]F --> H{审查与检查通过?}G --> HH -- 否 --> CH -- 是 --> I[Squash/Merge 到 main]I --> J[删除功能分支]

一套标准命令流程如下：

# 1. 回到主分支并获取最新代码
git switch main
git pull origin main# 2. 从 main 创建功能分支
git switch -c feature/login-page# 3. 修改代码后查看状态
git status
git diff# 4. 暂存与提交
git add .
git commit -m "feat: add login page"# 5. 推送分支到 GitHub
git push -u origin feature/login-page# 6. 在 GitHub 创建 Pull Request
# 可选：使用 GitHub CLI
gh pr create --web

如果 Pull Request 开发过程中 main 已经前进，推荐在功能分支上同步主线：

git fetch origin
git rebase origin/main

如有冲突，处理后继续：

git status
# 编辑冲突文件，删除 <<<<<<< ======= >>>>>>> 标记
git add 冲突文件
git rebase --continue

如果 rebase 方向错了，或冲突处理无法继续：

git rebase --abort

如果 rebase 后需要更新远程功能分支，不要使用粗暴的 git push -f，应使用：

git push --force-with-lease

--force-with-lease 会在强制更新前检查远程分支是否已被他人更新，比 --force 更适合团队协作。

5. GitHub 上的三种合并方式：不是随便选

GitHub Pull Request 常见合并方式有三种：Create a merge commit、Squash and merge、Rebase and merge。三者不是语法差异，而是历史管理策略差异。

合并方式	历史形态	适合场景	主要代价
Create a merge commit	保留分支结构，并额外生成 merge commit	长期分支合并、需要保留完整上下文的项目	主线历史分叉较多
Squash and merge	将 PR 内多个提交压缩成一个提交进入主线	GitHub Flow、小团队、一般业务项目	分支上的细粒度提交不会原样保留在 `main`
Rebase and merge	将分支提交逐个重放到主线，形成线性历史	团队熟悉 rebase，追求线性提交历史	冲突处理和历史理解成本较高

建议默认策略：

普通业务项目：Squash and merge。
需要保留分支语义的长期分支：Create a merge commit。
强调线性历史且团队熟悉 Git：Rebase and merge。

Squash and merge 的优势是主线历史干净。一个 Pull Request 对应一个主线提交，便于回滚：

git revert <squash-commit-hash>

但无论使用哪种方式，都应通过分支保护限制直接向 main 推送。

6. 主分支保护：把规范写进系统，而不是靠自觉

一个项目只要多人协作，就不应允许随意向 main 直接 push。GitHub 的 Branch protection 或 Rulesets 可以把流程要求固化为仓库规则。

建议对 main 启用以下限制：

规则	建议
Require a pull request before merging	开启
Require approvals	至少 1 人；关键仓库至少 2 人
Require review from Code Owners	涉及关键目录时开启
Require status checks to pass	必须开启，将 CI 作为合并前置条件
Require branches to be up to date before merging	推荐开启，减少合并后失败
Do not allow force pushes	必须开启
Do not allow deletions	必须开启
Require signed commits	高安全项目建议开启

可以同时使用 CODEOWNERS 指定目录负责人。例如：

# .github/CODEOWNERS# 默认负责人
* @org/core-team# 前端目录由前端组审查
/frontend/ @org/frontend-team# 后端目录由后端组审查
/backend/ @org/backend-team# CI/CD 配置由 DevOps 或平台组审查
/.github/workflows/ @org/platform-team

这样，当 Pull Request 修改 .github/workflows/ 或 /backend/ 时，GitHub 可以自动请求对应团队审查。对生产系统而言，CI 配置、部署脚本、权限文件、数据库迁移文件都应有明确负责人。

7. 日常命令清单：按任务记，不按命令背

7.1 初始化与配置

# 设置提交身份
git config --global user.name "你的名字"
git config --global user.email "your.email@example.com"# 建议默认分支名为 main
git config --global init.defaultBranch main# 初始化新仓库
git init# 或直接指定初始分支
git init -b main

7.2 克隆与远程仓库

# HTTPS 克隆
git clone https://github.com/org/repo.git# SSH 克隆
git clone git@github.com:org/repo.git# 查看远程地址
git remote -v# 添加远程仓库
git remote add origin git@github.com:org/repo.git# 修改远程地址
git remote set-url origin git@github.com:org/new-repo.git

7.3 查看状态与差异

git statusgit diff                 # 工作区 vs 暂存区
git diff --staged        # 暂存区 vs 上次提交
git diff HEAD            # 工作区整体 vs 上次提交

7.4 提交与历史

git add .
git commit -m "feat: add user profile page"git log --oneline --graph --decorate --all
git show <commit-hash>
git blame path/to/file

7.5 分支与同步

git branch
git switch main
git switch -c fix/avatar-nullgit fetch origin
git pull origin maingit push -u origin fix/avatar-null

7.6 临时保存工作

# 保存当前未提交修改
git stash push -m "wip: login refactor"# 查看 stash 列表
git stash list# 恢复最近一次 stash，并从列表移除
git stash pop# 只恢复但保留 stash 记录
git stash apply stash@{0}

stash 适合临时切换任务，不适合长期保存工作。长期工作应提交到分支，而不是堆在 stash 中。

8. 常见误操作处理：先判断是否已经 push

Git 误操作的处理原则很明确：

未 push 的本地历史，可以 amend、reset、rebase；已经进入公共分支的历史，优先 revert，不要随意重写。

8.1 提交信息写错或漏加文件：`git commit --amend`

最后一次提交尚未 push，可以修改提交信息：

git commit --amend -m "fix: correct token validation"

如果漏加文件：

git add src/auth/token.ts
git commit --amend --no-edit

--amend 会创建一个新的提交替代原提交，提交哈希会变化。因此，不要随意 amend 已经推送到公共分支的提交。

8.2 文件误加入暂存区：`git restore --staged`

git restore --staged config.local.json

这只会把文件从暂存区移回工作区，不会删除你的修改。

8.3 工作区改乱了，丢弃某个文件的未提交修改

git restore path/to/file

此命令会丢弃该文件未提交的工作区修改。执行前应先看：

git diff path/to/file

8.4 撤销最后一次提交，但保留修改：`reset --soft`

git reset --soft HEAD~1

效果：提交被撤销，但修改仍保留在暂存区。适合“刚提交完发现提交说明或提交边界不对”的场景。

8.5 撤销最后一次提交，并把修改放回工作区：`reset --mixed`

git reset --mixed HEAD~1

--mixed 是 git reset 的默认模式。它撤销提交，同时清空暂存区，修改保留在工作区。

8.6 撤销最后一次提交，并丢弃修改：`reset --hard`

git reset --hard HEAD~1

这是危险命令。它会移动 HEAD，并覆盖暂存区和工作区。执行前应确认没有未保存的有效工作。

8.7 已经 push 的错误提交：用 `git revert`

如果错误提交已经进入 main 或多人共享分支，优先使用：

git revert <commit-hash>

revert 不删除历史，而是创建一个新的反向提交。它适合公共分支，因为它不会破坏其他人已经基于旧历史开展的工作。

如果要撤销一个 merge commit，需要指定主线父提交：

git revert -m 1 <merge-commit-hash>

这类操作建议先在本地测试，再通过 Pull Request 合并。

8.8 整理 PR 中的杂乱提交：`git rebase -i`

Pull Request 中出现多个无意义提交，例如 update、fix typo、try again，可以在功能分支上整理：

git rebase -i HEAD~5

常用指令：

指令	含义
`pick`	保留提交
`reword`	修改提交信息
`edit`	停在该提交，允许修改内容
`squash`	合并到上一个提交，并保留说明
`fixup`	合并到上一个提交，但丢弃说明
`drop`	删除提交

整理后如果分支已经 push，需要：

git push --force-with-lease

不要对 main 这样的公共主线执行交互式 rebase。

8.9 rebase 冲突处理

git status
# 手动处理冲突文件
git add path/to/conflict-file
git rebase --continue

放弃本次 rebase：

git rebase --abort

8.10 不小心在 main 上提交了代码

如果尚未 push，可以把提交转移到新分支，再让 main 回退：

# 当前在 main，且刚刚错误提交
git switch -c feature/misplaced-work# 回到 main
git switch main# main 回到错误提交之前
git reset --hard HEAD~1# 回到正确分支继续工作
git switch feature/misplaced-work

如果已经 push 到远程 main，不要私自 reset 后强推，应创建修复 Pull Request 或使用 git revert。

8.11 找回误删提交：`git reflog`

git reflog

找到丢失提交对应的哈希后：

git switch -c recovery <commit-hash>

reflog 记录的是本地 HEAD 和引用的移动历史。只要对象尚未被 Git 垃圾回收，很多误 reset、误 rebase 后的提交都能找回。

8.12 清理未跟踪文件：`git clean`

先预演，不直接删除：

git clean -nd

确认后删除：

git clean -fd

此命令会删除未跟踪文件。不要在不了解输出的情况下直接执行 git clean -fdx，因为 -x 会连 .gitignore 忽略的文件一起删除。

9. `reset`、`revert`、`rebase`、`amend` 的决策表

场景	推荐命令	是否重写历史	是否适合公共分支
最后一次提交信息写错，未 push	`git commit --amend`	是	否
最后一次提交多加了文件，未 push	`git reset --mixed HEAD~1` 后重新提交	是	否
本地提交想撤销但保留修改	`git reset --soft HEAD~1`	是	否
本地提交和修改都不要	`git reset --hard HEAD~1`	是	否
已合并到 `main` 的错误提交	`git revert <hash>`	否	是
PR 提交太乱，需要整理	`git rebase -i`	是	仅限个人功能分支
功能分支落后于 `main`	`git fetch && git rebase origin/main`	是	仅限个人功能分支
误删提交需要找回	`git reflog`	否	本地恢复用

最重要的边界是：不要改写已经被多人依赖的公共历史。历史重写不是错误，但必须限定在个人分支或团队明确允许的范围内。

10. `.gitignore` 与 `.gitkeep`：一个忽略文件，一个保留空目录

10.1 `.gitignore`：不要把不该进仓库的东西提交进去

.gitignore 用来声明 Git 应该忽略的未跟踪文件。典型内容包括依赖目录、构建产物、系统文件、编辑器配置、日志文件、临时文件和本地环境变量文件。

示例：

# dependencies
node_modules/
.venv/# build outputs
dist/
build/
coverage/# OS / editor
.DS_Store
.idea/
.vscode/# local env
.env
.env.local# logs
*.log

注意：.gitignore 不会自动影响已经被 Git 跟踪的文件。如果一个文件已经提交过，再把它写入 .gitignore 并不会让 Git 停止跟踪它。需要先移出索引：

git rm --cached .env
git commit -m "chore: stop tracking local env file"

如果 .env 中已经出现真实密钥，仅从仓库删除不够，必须立即轮换密钥，并视情况清理历史。

10.2 `.gitkeep`：Git 不跟踪空目录时的约定

Git 跟踪的是文件内容和目录树，不会单独跟踪“空目录”。如果项目需要保留一个空目录结构，例如 logs/、uploads/、tmp/，常见做法是在目录中放一个空文件 .gitkeep。

mkdir -p logs
touch logs/.gitkeep
git add logs/.gitkeep
git commit -m "chore: keep logs directory"

.gitkeep 不是 Git 官方特殊文件名，只是社区约定。理论上文件名可以是 .keep、README.md 或其他名称，但 .gitkeep 的语义更明确：该文件存在的目的只是让 Git 保留目录。

如果希望保留目录，但忽略目录下运行时生成的文件，可以这样写：

logs/*
!logs/.gitkeep

不要滥用 .gitkeep。只有当空目录本身对项目运行、部署或说明有意义时，才需要保留。

11. Submodule：把另一个 Git 仓库嵌入当前仓库

Submodule 适用于这样一种情况：主项目需要引用另一个独立 Git 仓库，并且希望两个仓库保留各自独立的提交历史。例如：

主项目引用内部共享库；
固件项目引用特定版本的驱动仓库；
文档站点引用独立维护的主题；
大型系统需要锁定某个外部组件的精确提交。

Submodule 不是包管理器的替代品。能用 npm、pip、Maven、Go modules、Cargo 等包管理器解决的依赖，通常不应优先使用 submodule。Submodule 的价值在于“把另一个仓库固定到一个明确 commit”。

11.1 添加 submodule

git submodule add https://github.com/org/shared-lib.git libs/shared-lib
git commit -m "chore: add shared-lib submodule"

添加后，主仓库会出现两个变化：

.gitmodules
libs/shared-lib

.gitmodules 记录 submodule 的路径和远程地址；主仓库中记录的不是子仓库全部文件内容，而是子仓库当前指向的 commit。

11.2 克隆带有 submodule 的仓库

11.3 更新 submodule

进入子仓库更新：

cd libs/shared-lib
git fetch origin
git switch main
git pull origin main
cd ../..# 重要：主仓库需要提交“子模块指针”的变化
git status
git add libs/shared-lib
git commit -m "chore: update shared-lib submodule"

也可以在主仓库中使用：

git submodule update --remote --merge

随后仍然需要在主仓库提交 submodule 指针变化。

11.4 删除 submodule

git submodule deinit -f libs/shared-lib
git rm -f libs/shared-lib
rm -rf .git/modules/libs/shared-lib
git commit -m "chore: remove shared-lib submodule"

11.5 Submodule 的常见问题

问题	原因	处理方式
clone 后目录为空	没有初始化 submodule	`git submodule update --init --recursive`
CI 找不到子模块内容	checkout 没有拉 submodule	GitHub Actions 中设置 `submodules: recursive`
子模块显示 modified	子模块 HEAD 与主仓库记录的 commit 不一致	进入子模块检查状态，或重新 `git submodule update`
子模块处于 detached HEAD	submodule 默认检出的是固定 commit	如需开发，进入子模块后切换到具体分支
私有 submodule 拉取失败	CI 或开发者没有权限	配置 SSH key、PAT 或统一访问策略

GitHub Actions 中拉取 submodule 的示例：

- name: Checkout repositoryuses: actions/checkout@v4with:submodules: recursive

使用 submodule 前要评估团队是否能接受它的心智负担。它适合精确锁定外部仓库版本，但也会增加 clone、CI、权限、更新流程的复杂度。

12. Git LFS：不要把大二进制文件硬塞进普通 Git 历史

Git 适合文本代码，不适合频繁修改的大型二进制文件，例如视频、模型、PSD、数据集、设计素材、游戏资源。把这些文件直接提交进普通 Git 历史，会导致仓库膨胀，clone 和 fetch 变慢。

Git LFS 的做法是：在 Git 仓库中存储小的指针文件，把真实大文件内容存储在 LFS 服务端。

常见配置：

git lfs install
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.onnx"git add .gitattributes
git commit -m "chore: track large assets with Git LFS"

需要注意：

Git LFS 不是无限存储，GitHub 上有配额和计费限制；
已经提交进普通 Git 历史的大文件，需要迁移历史，不能只靠 .gitignore；
团队成员和 CI 环境都需要具备 Git LFS 支持。

13. GitHub Actions：把测试和部署接入 Pull Request

GitHub Actions 是 GitHub 的自动化工作流系统。它可以在 push、pull_request、release、workflow_dispatch 等事件发生后运行任务。一个 workflow 通常由 event、job、step、runner 和 action 组成。

概念	含义
workflow	一个自动化流程，定义在 `.github/workflows/*.yml`
event	触发 workflow 的事件，例如 `pull_request`、`push`
job	workflow 中的一组任务，可并行或串行执行
step	job 内的单个步骤
runner	执行 job 的机器，例如 `ubuntu-latest`
action	可复用步骤，例如 `actions/checkout`

13.1 一个最小 CI 示例

name: CIon:pull_request:branches: [main]push:branches: [main]permissions:contents: readjobs:test:runs-on: ubuntu-lateststeps:- name: Checkout repositoryuses: actions/checkout@v4- name: Setup Node.jsuses: actions/setup-node@v4with:node-version: 20cache: npm- name: Install dependenciesrun: npm ci- name: Run testsrun: npm test

这段配置的含义是：当有人向 main 发起 Pull Request，或有代码 push 到 main 时，自动安装依赖并运行测试。随后可以在分支保护中把该 workflow 的状态检查设为必需检查。这样，测试失败的 Pull Request 不能合并。

13.2 不同事件应承担不同责任

事件	适合做什么	不适合做什么
`pull_request`	测试、Lint、类型检查、安全扫描	使用生产密钥部署
`push` 到 `main`	构建、部署到测试/生产环境	跳过测试直接部署
`release`	发布制品、上传包、生成 changelog	做普通 PR 检查
`workflow_dispatch`	手动触发运维任务	替代正常 CI
`schedule`	定时依赖检查、定时扫描	对实时发布强依赖的任务

13.3 部署 workflow 示例

name: Deployon:push:branches: [main]permissions:contents: readdeployments: writeconcurrency:group: deploy-productioncancel-in-progress: falsejobs:deploy:runs-on: ubuntu-latestenvironment: productionsteps:- uses: actions/checkout@v4- name: Buildrun: npm ci && npm run build- name: Deployrun: ./scripts/deploy.sh

这里的 environment: production 可以配合 GitHub Environments 做部署审批、环境密钥隔离和部署记录管理。

13.4 GitHub Actions 安全原则

Actions 配置本身属于高风险代码。因为它可能接触密钥、部署凭证和发布权限，所以必须纳入代码审查。

基本原则：

默认给 GITHUB_TOKEN 最小权限，例如 contents: read。
不要在 pull_request 上使用生产密钥。
不要用 pull_request_target 执行来自外部 PR 的未可信代码。
第三方 action 应来自可信维护者；高安全项目应固定到 commit SHA，而不是只用浮动 tag。
.github/workflows/ 修改应由平台或 DevOps 负责人审查。
私有 runner 不应执行不可信 fork PR 的代码，除非有隔离措施。

pull_request_target 尤其需要谨慎。它运行在 base repository 的上下文中，适合打标签、评论等不执行 PR 代码的任务；如果用它 checkout 并运行外部 PR 的代码，可能造成密钥泄露或权限滥用。

14. Secrets、密钥泄露与仓库安全

最常见的仓库安全事故是把密钥提交到 GitHub：API key、数据库密码、云厂商访问令牌、私钥、.env 文件等。

处理原则：

先轮换密钥。只删除提交不等于密钥安全。
删除仓库中的敏感文件，并加入 .gitignore。
如果密钥进入历史，视情况使用 git filter-repo 或 BFG Repo-Cleaner 清理历史。
开启 GitHub secret scanning 和 push protection。
CI/CD 使用 GitHub Secrets、Environments、OIDC，不要把密钥写在仓库中。

错误示例：

# 错误：把 .env 提交上去后，只删除文件并不能让泄露密钥失效
git rm .env
git commit -m "remove env"

正确处置应先在服务商后台吊销或轮换密钥，再处理仓库历史。

15. Releases、Tags 与版本发布

当项目需要对外发布版本时，应使用 Git tag 和 GitHub Releases。

# 创建带说明的 tag
git tag -a v1.2.0 -m "release: v1.2.0"# 推送 tag
git push origin v1.2.0

GitHub Release 通常基于 tag 创建，用于附加 release notes、构建产物、二进制包或安装说明。

常见策略：

项目类型	推荐做法
库或 SDK	使用语义化版本，如 `v1.2.3`
Web 服务	每次生产部署可生成 tag 或 release note
CLI 工具	Release 附带二进制包和校验信息
文档站点	可按里程碑或重要变更发布

如果配合 GitHub Actions，可以在 release: published 时自动构建和上传产物。

16. Pull Request 的工程规范

Pull Request 是 GitHub 协作的核心单位。一个高质量 PR 应该让审查者快速回答三个问题：为什么改、改了什么、如何验证。

建议 PR 模板：

## 变更目的说明本 PR 解决的问题、需求或缺陷。## 主要改动- 
- ## 验证方式- [ ] 本地测试通过
- [ ] 单元测试通过
- [ ] 已验证关键路径## 风险与回滚说明潜在影响、兼容性问题和回滚方式。

建议规则：

一个 PR 解决一个问题；
避免把格式化、重构、功能开发混在同一个 PR；
PR 尽量小，审查者能在合理时间内理解；
修改数据库迁移、权限、CI/CD、认证逻辑时必须增加风险说明；
CI 不通过不合并；
审查意见未处理不合并。

17. 提交信息规范：让历史可读

提交信息不是给机器看的注释，而是给未来维护者看的审计记录。推荐使用近似 Conventional Commits 的格式：

<type>(scope): <subject>

示例：

git commit -m "feat(auth): add OAuth callback handler"
git commit -m "fix(api): return 401 for expired token"
git commit -m "docs(readme): add local setup guide"
git commit -m "refactor(user): split profile service"
git commit -m "test(auth): cover invalid password case"

常见 type：

type	含义
`feat`	新功能
`fix`	缺陷修复
`docs`	文档
`style`	格式调整，不改变逻辑
`refactor`	重构，不改变外部行为
`test`	测试
`chore`	构建、依赖、配置等维护任务
`ci`	CI/CD 配置

避免提交信息：

update
fix
change
test
aaa
临时提交

如果临时提交只存在于功能分支，可以在合并前通过 squash 或交互式 rebase 整理。

18. Forking Flow：开源项目常见协作方式

如果你没有目标仓库写权限，通常不能直接创建分支推到原仓库。这时使用 Forking Flow：

在 GitHub 上 fork 原仓库到自己账号；
clone 自己的 fork；
添加原仓库为 upstream；
从最新 upstream/main 创建分支；
push 到自己的 fork；
从 fork 向原仓库发起 Pull Request。

命令示例：

# clone 自己的 fork
git clone git@github.com:your-name/project.git
cd project# 添加上游仓库
git remote add upstream git@github.com:origin-owner/project.git# 同步上游 main
git fetch upstream
git switch main
git rebase upstream/main# 创建贡献分支
git switch -c fix/readme-typo# 提交并推送到自己的 fork
git add README.md
git commit -m "docs: fix README typo"
git push -u origin fix/readme-typo

在 GitHub 页面上，从 your-name:fix/readme-typo 向 origin-owner:main 发起 Pull Request。

19. 一套可落地的团队默认规范

如果要为一个新项目制定 Git/GitHub 规范，可以直接采用以下基线。

19.1 分支策略

main                  受保护主分支，可部署或可集成
feature/<name>        新功能
fix/<name>            缺陷修复
docs/<name>           文档
refactor/<name>       重构
chore/<name>          配置、依赖、脚本等维护工作

19.2 合并策略

默认：Squash and merge
例外：长期分支之间可使用 merge commit
禁止：未经 PR 直接 push 到 main
禁止：对 main force push

19.3 Pull Request 策略

至少 1 人 review
关键模块使用 CODEOWNERS
CI 必须通过
PR 描述必须说明验证方式
涉及生产风险的 PR 必须说明回滚方案

19.4 GitHub Actions 策略

pull_request: 运行测试、Lint、类型检查、安全扫描
push main: 构建与部署
release published: 发布制品
GITHUB_TOKEN: 默认 contents: read，按 job 提权
.github/workflows/: 必须由平台负责人审查

19.5 仓库文件策略

必须提交：README.md、LICENSE、.gitignore、必要的 .github 配置
谨慎提交：大文件、生成文件、锁文件视项目语言而定
禁止提交：密钥、个人配置、本地数据库、构建缓存
空目录：必要时使用 .gitkeep
大文件：必要时使用 Git LFS
外部仓库嵌入：必要时使用 submodule，并写清更新流程

20. 最后给一份日常速查表

任务	命令
查看状态	`git status`
查看工作区差异	`git diff`
查看暂存区差异	`git diff --staged`
暂存全部修改	`git add .`
交互式暂存	`git add -p`
提交	`git commit -m "message"`
修改最后一次提交	`git commit --amend`
创建并切换分支	`git switch -c feature/x`
推送新分支	`git push -u origin feature/x`
获取远程更新	`git fetch origin`
拉取并合并	`git pull origin main`
在功能分支上接最新 main	`git rebase origin/main`
取消 rebase	`git rebase --abort`
继续 rebase	`git rebase --continue`
撤销已公开提交	`git revert <hash>`
本地撤销最后提交但保留修改	`git reset --soft HEAD~1`
本地撤销最后提交并清空暂存	`git reset --mixed HEAD~1`
本地丢弃最后提交和修改	`git reset --hard HEAD~1`
找回历史位置	`git reflog`
临时保存修改	`git stash push -m "message"`
恢复临时修改	`git stash pop`
添加 submodule	`git submodule add <url> <path>`
初始化 submodule	`git submodule update --init --recursive`
保留空目录	`touch path/.gitkeep`
跟踪大文件	`git lfs track "*.psd"`

结语

Git 的核心价值不是命令数量，而是把代码变更变成可审查、可测试、可追踪、可回滚的工程对象。GitHub 则把这一套机制扩展为团队协作流程：分支承载变更，Pull Request 承载讨论，Actions 承载自动化验证，分支保护承载治理规则，Releases 承载交付记录。

对一个严肃项目而言，最低限度的实践不是“会 push”，而是：不直接改 main；每个变更走短分支；通过 Pull Request 合并；CI 不通过不合并；公共历史不随意重写；密钥不进仓库；大文件用 LFS；空目录用 .gitkeep；真正需要嵌入独立仓库时才使用 submodule。

当这些规则成为习惯，Git 就不再是提交代码的工具，而是项目秩序的一部分。

参考资料

Git 官方网站：https://git-scm.com/
Pro Git：What is Git? https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F
Pro Git：Branches in a Nutshell https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell
Pro Git：Submodules https://git-scm.com/book/en/v2/Git-Tools-Submodules
Git reset 官方文档：https://git-scm.com/docs/git-reset
Git revert 官方文档：https://git-scm.com/docs/git-revert
Git rebase 官方文档：https://git-scm.com/docs/git-rebase
Git commit 官方文档：https://git-scm.com/docs/git-commit
Git ignore 官方文档：https://git-scm.com/docs/gitignore
GitHub Docs：GitHub Flow https://docs.github.com/en/get-started/using-github/github-flow
GitHub Docs：About pull requests https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
GitHub Docs：About pull request merges https://docs.github.com/articles/about-pull-request-merges
GitHub Docs：Protected branches https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
GitHub Docs：CODEOWNERS https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
GitHub Docs：GitHub Actions https://docs.github.com/actions
GitHub Docs：Events that trigger workflows https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows
GitHub Docs：GitHub Actions secure use https://docs.github.com/en/actions/reference/security/secure-use
GitHub Docs：Git LFS https://docs.github.com/repositories/working-with-files/managing-large-files/about-git-large-file-storage
Git LFS 官方网站：https://git-lfs.com/
GitHub Docs：Secret scanning https://docs.github.com/code-security/secret-scanning/about-secret-scanning
用户提供参考视频：https://www.bilibili.com/video/BV19e4y1q7JJ/