Git 使用文档

Git 使用文档

适用目标：

• 新同事快速上手 Git

• 团队统一分支和提交规范

• 日常开发、发版、紧急修复时有统一操作方式

---

1. Git 基础配置

1.1 安装 Git

Windows：

winget install --id Git.Git -e

Mac：

brew install git

Ubuntu：

sudo apt update
sudo apt install git

1.2 首次配置

首次安装后建议先配置用户名、邮箱和默认分支名：

git config --global user.name "你的名字"
git config --global user.email "your_email@example.com"
git config --global init.defaultBranch main

查看配置：

git config --global --list
git config --list

说明：

• --global 表示当前用户下所有仓库通用

• git config --list 会同时显示系统、全局、仓库级配置

1.3 生成 SSH Key

推荐使用 SSH 连接远程仓库：

ssh-keygen -t ed25519 -C "your_email@example.com"

如果环境不支持 ed25519，可退回 RSA：

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

查看公钥并复制到 GitHub / GitLab / Gitee：

cat ~/.ssh/id_ed25519.pub

Windows Git Bash 下通常也是同样命令；PowerShell 可直接打开对应公钥文件复制内容。

测试连接：

ssh -T git@github.com

---

2. 常用仓库操作

2.1 新建仓库

git init

2.2 克隆仓库

git clone <仓库地址>

示例：

git clone git@github.com:org/repo.git

2.3 查看状态

git status

2.4 查看提交历史

git log
git log --oneline --graph --decorate --all

2.5 查看差异

git diff
git diff --cached

说明：

• git diff 查看工作区与暂存区差异

• git diff --cached 查看暂存区与最近一次提交差异

2.6 添加与提交

git add <文件>
git add .
git commit -m "feat: 新增用户登录校验"

2.7 撤销常见操作

撤销工作区修改：

git restore <文件>

取消暂存：

git restore --staged <文件>

修改最近一次提交说明：

git commit --amend

---

3. 分支工作流规范

团队建议采用 Git Flow 思路，核心分支如下。

3.1 永久分支

master / main

• 用于对外发布稳定版本

• 不允许直接在该分支开发

• 仅在发版、热修复合入时更新

develop

• 团队日常开发主干

• 所有功能分支从这里拉出

• 不建议直接在该分支上提交业务开发代码

3.2 临时分支

feature/*

• 新功能开发分支

• 从 develop 拉出

• 自测通过后合并回 develop

release/*

• 提测、预发、发版准备分支

• 从 develop 拉出

• 只允许做发版前修正，不继续叠加新功能

• 完成后合并回 master/main 和 develop

hotfix/*

• 线上问题紧急修复分支

• 从 master/main 拉出

• 修复后同时合并回 master/main 和 develop

3.3 分支命名建议

feature/login
feature/order-export
release/2026.05.01
hotfix/payment-timeout

3.4 标准开发流程

git checkout develop
git pull origin develop
git checkout -b feature/login

开发完成后：

git add .
git commit -m "feat: 新增用户登录验证逻辑"
git push origin feature/login

然后发起合并请求，由评审后并入 develop。

---

4. Commit Message 规范

4.1 标准格式

<type>(scope): <description>

scope 可选，推荐在跨模块协作时使用。

4.2 type 类型

类型	说明	示例
feat	新功能	feat: 新增报价单导出功能
fix	Bug 修复	fix: 修复价格计算结果错误
docs	文档变更	docs: 更新接口使用说明
style	代码风格调整	style: 统一报价模块命名风格
refactor	重构	refactor: 重构订单状态转换逻辑
perf	性能优化	perf: 优化报价列表查询索引
test	测试相关	test: 新增登录服务单元测试
chore	构建、配置、杂项	chore: 升级 Spring Boot 版本
build	构建系统变更	build: 调整 Maven 打包参数
ci	CI 配置变更	ci: 增加发布前校验步骤
revert	回滚提交	revert: 回滚订单导出接口改动

4.3 描述规则

• 尽量简短清晰，建议不超过 50 字

• 直接描述"做了什么"或"修了什么"

• 不建议只写"修改""调整""优化"这种泛化词

• 标点、括号、冒号、空格统一使用英文符号

示例：

fix: 修复报价截止时间为空时导出报错
feat(设备): 新增设备离线状态消息处理
perf(查询): 优化历史台账关联查询索引

---

5. 提交粒度规范

5.1 为什么要控制粒度

• 方便 Code Review

• 方便定位问题和回滚

• 降低分支合并冲突

• 提升团队协作效率

5.2 建议标准

文件数建议：

• 功能开发：建议不超过 10 个文件，最多不超过 20 个

• Bug 修复：建议不超过 5 个文件，最多不超过 10 个

• 重构优化：建议不超过 15 个文件，最多不超过 25 个

代码量建议：

• 日常开发 / Bug 修复：建议不超过 300 行，最多不超过 500 行

• 重构 / 迁移：建议不超过 500 行，最多不超过 800 行

5.3 反模式

git add .
git commit -m "feat: 用户模块开发+登录修复+配置调整"

问题：

• 一个提交里混了多个主题

• Review 成本高

• 以后很难精准回滚

5.4 推荐做法

git add config/database.yml
git commit -m "chore: 数据库连接池配置优化"

git add src/login/
git commit -m "feat: 新增用户登录验证逻辑"

git add tests/login.test.js
git commit -m "test: 新增登录模块单元测试"

---

6. 远程仓库操作

6.1 查看远程仓库

git remote -v

6.2 添加远程仓库

git remote add origin <仓库地址>

6.3 拉取远程更新

git pull origin develop

如果希望历史更线性，可使用：

git pull --rebase origin develop

6.4 推送本地分支

git push origin feature/login

首次推送并建立上游关系：

git push -u origin feature/login

6.5 推送标签

git push origin v1.0.0
git push origin --tags

---

7. 合并与变基

7.1 merge

适合保留完整分支合并历史：

git checkout develop
git merge feature/login

7.2 rebase

适合整理个人开发分支历史，让提交记录更线性：

git checkout feature/login
git rebase develop

注意：

• 不要随意 rebase 已经多人共享且他人正在使用的公共分支

• 如果 rebase 后需要推送已存在远程分支，通常要：

git push --force-with-lease

优先使用 --force-with-lease，不要直接用 --force。

---

8. 标签管理

标签通常用于版本发布。

创建轻量标签：

git tag v1.0.0

创建附注标签：

git tag -a v1.0.0 -m "release 1.0.0"

查看标签：

git tag

查看标签详情：

git show v1.0.0

---

9. 高级常用操作

9.1 cherry-pick

把指定提交挑到当前分支：

git cherry-pick <commit-id>

适用场景：

• 把某个修复从开发分支同步到热修复分支

• 只选择某一个提交，不整体合并整个分支

9.2 stash

临时保存当前未提交修改：

git stash
git stash list
git stash pop

9.3 reflog

查看本地所有 HEAD 变更记录，可用于找回误删提交：

git reflog

9.4 bisect

二分定位是哪次提交引入问题：

git bisect start
git bisect bad
git bisect good <commit-id>

---

10. 全局钩子配置

如果希望所有仓库统一校验提交信息，推荐配置 Git 全局钩子。

10.1 创建全局 hooks 目录

Windows：

mkdir C:\Users\YourName\.git_hooks

Mac / Linux：

mkdir -p ~/.git_hooks

10.2 创建 commit-msg 钩子

文件名必须是 commit-msg，不要带后缀。

示例脚本：

#!/bin/sh

commit_msg=$(cat "$1")
pattern="^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\(.+\))?: .+"

if ! echo "$commit_msg" | grep -Eq "$pattern"; then
    echo "============================================================================="
    echo "提交拒绝: 格式错误"
    echo "当前信息: $commit_msg"
    echo "正确格式: <type>(scope): <description>"
    echo "示例: feat(报价): 新增导出功能"
    echo "============================================================================="
    exit 1
fi

10.3 配置 Git 使用全局 hooks

Windows 示例：

git config --global core.hooksPath "D:/your-path/.git_hooks"

Mac / Linux 示例：

git config --global core.hooksPath ~/.git_hooks
chmod +x ~/.git_hooks/commit-msg

10.4 验证是否生效

在任意 Git 仓库执行：

git commit -m "随便写一个不合规信息"

如果配置成功，提交会被拦截。

说明：

• 全局钩子适合统一团队约束

• 仓库内如果另有独立钩子，需要确认是否与全局规则冲突

---

11. 第三方依赖管理规范

这一部分更适合前端或依赖较多的项目，但其他技术栈也可参考。

11.1 引入前评估

引入第三方库前建议检查：

• 活跃度：近 6 个月是否还有更新

• 维护性：是否持续发版、修复安全问题

• 社区质量：文档是否完善、社区是否活跃

• 依赖复杂度：是否引入过多子依赖

• 兼容性：是否匹配当前技术栈

• 安全性：是否有已知高危漏洞

• License：是否符合公司开源协议要求

11.2 版本管理建议

{
  "dependencies": {
    "lodash": "^4.17.21",
    "axios": "~1.6.0",
    "dayjs": "1.11.10"
  }
}

说明：

• ^1.2.3：允许次版本和补丁版本更新

• ~1.2.3：只允许补丁版本更新

• 1.2.3：完全锁定版本

不建议：

• 使用 latest

• 使用 *

11.3 锁文件必须提交

例如：

• package-lock.json

• yarn.lock

• pnpm-lock.yaml

原因：

• 保证团队安装结果一致

• 避免"我本地能跑，你本地不行"

• 让 CI/CD 构建可复现

11.4 禁止直接修改第三方安装目录

不要直接修改：

node_modules/

推荐方式：

• 升级到合适版本

• 使用补丁方案，例如 patch-package

• 记录修改原因和影响范围

---

12. 常见问题处理

12.1 提交后发现用户名或邮箱错误

修改全局配置：

git config --global user.name "正确名字"
git config --global user.email "correct@example.com"

如果只是最近一次提交写错了：

git commit --amend --reset-author

12.2 合并或变基出现冲突

处理步骤：

1. 用编辑器打开冲突文件

2. 删除冲突标记并保留正确内容

3. 重新暂存文件

4. 继续 merge 或 rebase

rebase 冲突后继续：

git add <文件>
git rebase --continue

放弃本次 rebase：

git rebase --abort

12.3 本地提交落后远程，无法 push

先同步再推送：

git pull --rebase origin develop
git push origin develop

12.4 提交丢了，想找回来

git reflog
git checkout <commit-id>

必要时可基于该提交重建分支：

git checkout -b rescue-branch <commit-id>

---

13. 团队推荐实践

• 功能开发从 develop 拉 feature/*

• 发版从 develop 拉 release/*

• 线上修复从 master/main 拉 hotfix/*

• 不直接在 master/main 上开发

• 提交信息遵循 type(scope): description

• 一个提交只做一件事

• 提交前先看 git status 和 git diff --cached

• 优先用小步提交，避免超大提交

• 团队统一启用全局 commit-msg 钩子

---

14. 建议掌握的最小命令集

如果你刚开始用 Git，先熟悉下面这些命令就够了：

git clone <url>
git status
git branch
git checkout -b feature/xxx
git add .
git commit -m "feat: xxx"
git pull --rebase origin develop
git push -u origin feature/xxx
git log --oneline --graph --decorate --all
git stash
git reflog

---