mkdocs/docs/学习笔记/gerrit上传代码详细指南.md

gerrit上传代码详细指南

Gerrit 代码上传详细指南

一、Gerrit 工作流程概述

开发者 → 本地开发 → 推送代码审查 → Gerrit 评审 → 评审通过 → 合并代码
     ↑                                                     ↓
     └─────────────── 需要修改 ← 评审不通过 ←───────────────┘

二、环境准备

1. 安装必要的工具

# 安装 Git
sudo apt-get install git  # Ubuntu/Debian
brew install git          # macOS

# 安装 commit-msg 钩子（关键步骤）
curl -Lo .git/hooks/commit-msg http://YOUR_GERRIT:8080/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg

2. 配置 Git 用户信息

git config --global user.name "你的姓名"
git config --global user.email "你的邮箱@company.com"
git config --global core.autocrlf input  # Windows 用户重要！
git config --global core.safecrlf warn

3. 配置 SSH 密钥

# 生成 SSH 密钥
ssh-keygen -t ed25519 -C "your_email@company.com"

# 查看公钥
cat ~/.ssh/id_ed25519.pub

# 将公钥添加到 Gerrit: Settings → SSH Keys

三、日常开发流程

1. 克隆项目

# 方式1：通过 SSH（推荐）
git clone ssh://username@gerrit-server:29418/project-name

# 方式2：通过 HTTP
git clone http://gerrit-server:8080/project-name

2. 创建开发分支

# 从 master 创建功能分支
git checkout master
git pull origin master
git checkout -b feature/your-feature-name

# 或者从特定版本创建
git checkout -b feature/xxx release-1.0

3. 进行开发

# 修改文件
git add .
git status  # 查看状态

# 提交代码（commit-msg 钩子会自动添加 Change-Id）
git commit -m "功能描述

详细描述：
1. 做了什么修改
2. 为什么修改
3. 测试情况

Bug: BUG-12345  # 如果有 Bug 编号
Feature: FEAT-6789  # 如果有需求编号

Change-Id: I自动生成"

4. 推送代码审查

# 标准推送方式（创建/更新代码审查）
git push origin HEAD:refs/for/目标分支

# 示例：
git push origin HEAD:refs/for/master          # 推送到 master 评审
git push origin HEAD:refs/for/release-1.0     # 推送到 release 分支评审
git push origin HEAD:refs/for/feature/xxx     # 推送到功能分支评审

四、推送参数详解

1. 普通推送

# 创建新的代码审查
git push origin HEAD:refs/for/master

# 创建草稿代码审查
git push origin HEAD:refs/drafts/master

2. 推送并设置评审人

# 推送并添加 Reviewer
git push origin HEAD:refs/for/master%r=reviewer1@company.com,r=reviewer2@company.com

# 推送并添加 CC
git push origin HEAD:refs/for/master%cc=manager@company.com

# 推送并设置 Topic
git push origin HEAD:refs/for/master%topic=feature/login

3. 推送选项组合

# 完整示例
git push origin HEAD:refs/for/master%\
r=alice@company.com,\
r=bob@company.com,\
cc=manager@company.com,\
topic=feature/login,\
l=Code-Review+2,\
l=Verified+1

五、更新已有的代码审查

1. 修改后更新

# 修改代码后
git add .
git commit --amend  # 重要：必须使用 --amend 保留 Change-Id

# 重新推送（会自动更新原有代码审查）
git push origin HEAD:refs/for/master

2. 基于评审意见修改

# 查看评审意见后修改
git fetch origin refs/changes/XX/YYYY/Z && git checkout FETCH_HEAD
# 或者
git review -d 12345  # 如果安装了 git-review

# 修改代码
git add .
git commit --amend

# 重新推送
git push origin HEAD:refs/for/master

3. 创建新的 Patch Set

# 每次 git commit --amend 后推送都会创建新的 Patch Set
git log --oneline -1  # 确认 Change-Id 存在
git push origin HEAD:refs/for/master

六、解决常见问题

问题1：缺少 Change-Id

# 安装 commit-msg 钩子
curl -Lo .git/hooks/commit-msg http://gerrit:8080/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg

# 为现有提交添加 Change-Id
git commit --amend --no-edit  # 重新提交，钩子会自动添加

# 或者手动添加
git commit --amend -m "原提交信息

Change-Id: I旧的ChangeId"  # 从 Gerrit 界面复制

问题2：权限拒绝

# 检查 SSH 配置
ssh -p 29418 username@gerrit-server

# 检查公钥是否添加
cat ~/.ssh/id_ed25519.pub

# 检查项目权限
# 联系管理员或查看 Gerrit Web 界面

问题3：冲突无法推送

# 拉取最新代码
git fetch origin
git rebase origin/master  # 或者 git merge origin/master

# 解决冲突
git mergetool  # 或手动解决
git add .
git rebase --continue  # 如果使用 rebase

# 重新推送
git push origin HEAD:refs/for/master

问题4：错误的分支目标

# 查看当前分支
git branch -a

# 查看远程分支
git branch -r

# 推送到正确的分支
git push origin HEAD:refs/for/正确的分支名

七、高级操作

1. 提交多个相关修改

# 创建多个提交
git add file1
git commit -m "修改1: 功能A"
git add file2
git commit -m "修改2: 功能B"

# 推送到同一个 Topic
git push origin HEAD~2:refs/for/master%topic=feature/xxx

2. 依赖链提交

# 第一个提交
git commit -m "基础修改"

# 第二个提交依赖第一个
git commit -m "依赖修改"

# 推送到 Gerrit 时保持依赖关系
git push origin HEAD~1:refs/for/master
git push origin HEAD:refs/for/master%depends=第一个提交的Change-Id

3. 使用 git-review 工具

# 安装
pip install git-review

# 初始化
git review -s

# 提交代码审查
git review

# 下载代码审查
git review -d 12345  # Change-Number

八、Gerrit Web 界面操作

1. 查看代码审查

• 访问：http://gerrit:8080
• 登录 → Dashboard → 查看你的代码审查
• 点击 Change-Number 进入详情

2. 评审操作

• +1 / -1：代码风格、建议性意见
• +2 / -2：代码评审通过/拒绝（需要权限）
• Submit：合并代码（需要权限）
• Abandon：放弃代码审查
• Rebase：重新基于最新代码
• Cherry Pick：应用到其他分支

3. 查看差异

• Side-by-Side：并排对比
• Unified Diff：统一差异
• Patch Set：切换不同版本

九、最佳实践

1. 提交信息规范

一句话摘要（50字以内）

详细描述：
• 做了什么修改
• 为什么修改
• 如何测试
• 可能的影响

Bug: BUG-12345
Feature: FEAT-6789
Test: 通过单元测试/集成测试

Change-Id: I自动生成

2. 代码审查前自查

# 1. 运行代码检查
git diff --check  # 检查空白字符

# 2. 运行测试
npm test  # 或 mvn test, pytest 等

# 3. 检查提交信息
git log --oneline -1

# 4. 确保 Change-Id 存在
git log -1 | grep Change-Id

3. 每日工作流程

# 早上
git fetch origin
git rebase origin/master  # 更新本地代码

# 开发中
git add .
git commit -m "..."

# 推送前
git pull --rebase origin master  # 再次更新
解决冲突（如果有）
git push origin HEAD:refs/for/master

# 查看 Gerrit 反馈
# 根据评审意见修改

十、常用命令速查

# 初始化
git clone ssh://user@gerrit:29418/project
scp -p -P 29418 user@gerrit:hooks/commit-msg .git/hooks/

# 日常开发
git checkout -b feature/xxx
git add .
git commit -m "..."
git push origin HEAD:refs/for/master

# 更新
git commit --amend
git push origin HEAD:refs/for/master

# 查看
git log --oneline -5
git status
git diff

# 解决冲突
git fetch origin
git rebase origin/master
解决冲突 → git add → git rebase --continue

十一、故障排除

问题	解决方案
403 Forbidden	检查 SSH 密钥/HTTP 密码
缺少 Change-Id	安装 commit-msg 钩子
分支不存在	先创建分支或确认分支名
冲突无法推送	rebase 解决冲突
权限不足	联系管理员添加权限
推送被拒绝	检查目标分支是否正确

十二、快速参考卡片

✅ 正确流程：
1. git clone
2. 安装 commit-msg 钩子
3. git checkout -b feature/xxx
4. 开发并提交
5. git push origin HEAD:refs/for/目标分支

✅ 更新流程：
1. git commit --amend  # 必须！
2. git push origin HEAD:refs/for/目标分支

✅ 关键要点：
• 每次提交都必须有 Change-Id
• 更新必须用 --amend
• 只能推送到 refs/for/
• 在 Gerrit Web 界面查看结果