Gerrit 使用教程

一、Gerrit简介

Gerrit，一种开放源代码的代码审查软件，使用网页界面。利用网页浏览器，同一个团队的程序员，可以相互审阅彼此修改后的代码，决定是否能够提交，退回或是继续修改。它使用版本控制系统Git作为底层。

Gerrit 与 Git 区别

Git 是一种版本控制系统；而 Gerrit 是一种基于 Web 的代码审查软件。
Git 用于代码的存储和版本控制；Gerrit 用于团队间相互审阅彼此修改后的程序代码，决定是否能够提交，退回或者继续修改。

理论上Git虽然是一个分布式版本管理系统，不需要中心代码库就能相互同步数据。而在实际的操作过程中，为了方便一个团队的多名开发人员通常需要指定一个确定的代码库用于提交和相互同步代码。所以我们开发团队代码管理一般使用如下结构：

图片

在引入Gerrit代码审核机制后，我们的代码提交和同步的方式发生了变化。

图片

二、工作流程

如果你使用过 git，当我们 git add --> git commit --> git push 之后，你的代码会被直接提交到 repo，也就是代码仓库中。而 Gerrit 的流程是：

程序员编写代码。
push 到 gerrit 服务器。
审核人员，在 web 页面进行代码的审核(review)，（可以单人审核，也可以邀请其他成员一同审核）。
审核通过(approve)之后。
提交(submit)到代码仓库(repo)中去。

android项目的源代码就是使用Gerrit进行管理的，在 Android 项目的网站的代码贡献流程图更为详细的介绍了 Gerrit 代码审核服务器的工作流程。

图片

相信在阅读完上面Gerrit的工作流程图后，大家对Gerrit有个大致的了解，接下来我们将进入实际的操作步骤，细致讲解如何利用Git完成上诉流程。我们已经准备了一个叫Gerrit-Base的测试项目供大家练手。

三、克隆代码仓库

Gerrit仓库提供了HTTP和SSH两种服务供大家从远程服务器获取代码，获取方式可在项目基本信息页面查看。

图片

当然，为个人账户安全，建议选择SSH协议获取代码，使用SSH协议需要配置本机密钥。

$ git clone ssh://[username]@[hostname]:[port]/Gerrit-Base


Cloning into Gerrit-Base...
remote: Counting objects: 2, done
remote: Finding sources: 100% (2/2)
remote: Total 2 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (2/2), done.
Checking connectivity... done.

四、创建审查

本步骤操作前默认已完成了创建、删除或修改本地文件，并将修改添加、提交到本地版本库。

$ git status


On branch master
Your branch is up-to-date with 'origin/master'.


Untracked files:
  (use "git add <file>..." to include in what will be committed)


    hello_gerrit
    hello_gerrit.c


nothing added to commit but untracked files present (use "git add" to track)


$ git add .
$ git commit -m "this is a new change"
$ git push origin HEAD:refs/for/master

在初次克隆代码时需要从服务器下载hook脚本用于每次审查自动生成change-id。

$ scp -p -P [port] [username]@[hostname]:hooks/commit-msg Gerrit-Base/.git/hooks/
$ git commit --amend
$ git push origin HEAD:refs/for/master

创建一个审核后，服务器的状态也会发送变化：

图片

五、审查代码

当提交修改成功后，默认情况下项目的所有者、管理员能够指定代码的审核人。指定审核人后，Gerrit会给审核人发送邮件提醒有审核任务。

审核代码的流程：

浏览代码增量，并给出注释;
浏览完成所有代码，并给出综合评价和评分(-2, -1, 0, 1, 2)。

多人评审后当总分>=2时，表示审核通过，进入下一步的代码验证流程；否则需要提交者返工修改。

图片

这些根据规则的不同，可以进行对应的配置修改，例如不用评分。

六、返工修改

根据上面Gerrit流程图，当代码审核、确认未通过或合并的过程中出现冲突，这个时候就需要返工修改后再提交。

返工流程有三步：

获取未通过的代码到本地工作目录；
修改代码；
再提交审核。

对应的Git命令实现为：

$ git fetch http://[username]@[hostname]/Gerrit-Base refs/changes/35/35/1
$ git checkout FETCH_HEAD
  ... // 修改代码
$ git add <path-of-reworked-file>


// amend commit
$ git commit --amend


// push patch set
$ git push origin HEAD:refs/for/master

修改后的提交，change-id不会发生变化，而仅仅是patch-id加1。因此对返工后的修改引用为“refs\/changes\/35\/35\/2”。

图片

七、验证、提交修改

新提交的修改，如果已经通过代码审核，下一步流程则是代码验证。验证之前需要代码测试人员先将修改获取到本地，然后对代码进行测试。代码测试后，则投票对本次修改做出评价。

图片

当代码成功通过Review和Verified后，此时这段修改后的代码片段就可以合并到主分支里面去了。

图片

八、常用命令

参考：Gerrit Code Review - Command Line Tools

gerrit ls-projects

显示项目名称列表，每行一个，调用用户帐户已被授予“读取”访问权限。如果调用者是特权“管理员”组的成员，则会列出所有项目。

ssh -p <port> <host> gerrit ls-projects
  [--show-branch <BRANCH> …]
  [--description | -d]
  [--tree | -t]
  [--type {code | permissions | all}]
  [--format {text | json | json_compact}]
  [--all]
  [--limit <N>]
  [--prefix | -p <prefix>]
  [--has-acl-for GROUP]

选项说明：

--show-branch：该命令将显示每个项目的 sha 的分支。该命令可能有多个 --show-branch 参数，在这种情况下，将为每个分支显示 sha。如果用户没有对某个分支的 READ 访问权限或该分支不存在，则-显示存根（40 个符号）。如果用户无权访问项目中的任何分支，则不会显示整个项目。
--description允许列出项目及其各自的描述。对于文本格式输出，所有不可打印的字符（ASCII 值 31 或更小）都根据 C、Python 和 Perl 等语言中使用的约定进行转义，使用标准序列（如\nand \t），以及 \xNN所有其他语言。在 shell 脚本中，该printf命令可用于取消转义输出。
--tree：以树状格式显示项目继承。此选项不能与 show-branch 选项一起使用。
--type：仅显示指定类型的项目。如果未指定，则默认为all. 支持的类型：code：任何可能包含用户文件的项目。permissions：使用--permissions-only标志创建的项目。all：任何类型的项目。
--format：显示结果的输出格式。text：简单的基于文本的格式。json：描述每个项目的 JSON 对象的映射。json_compact：最小化 JSON 输出。
- --all：显示调用用户帐户可访问的所有项目。除了调用用户帐户已被授予“读取”访问权限的项目外，这包括调用用户帐户拥有的所有项目（即使这些项目的“读取”访问权限未分配给调用用户帐户）。
--limit：将结果数限制为前 N 个匹配项。
--prefix：将结果限制为以指定前缀开头的项目。
--has-acl-for：仅显示直接分配了该组访问权限的项目。仅继承该组访问权限的项目未列出。
使用此选项，您可以了解在哪些项目上使用了一个组。

gerrit query

Gerrit 的 gerrit query 命令就是要查询 Gerrit 的 changes 数据库。默认，查询结果是根据 changes 的更新时间，由近及远排序。对于有多个 patch set 的 change，默认查询结果只包含最后的 patch set。如果查询结果有很大，则默认只返回有限个查询结果，可以设置 limit:参数指定查询结果包含的 changes 数量。

ssh -p <port> <host> gerrit query
  [--format {TEXT | JSON}]
  [--current-patch-set]
  [--patch-sets | --all-approvals]
  [--files]
  [--comments]
  [--commit-message]
  [--dependencies]
  [--submit-records]
  [--all-reviewers]
  [--start <n> | -S <n>]
  <query>
  [limit:<n>]

选项说明:

format=TEXT，默认
format=JSON
current-patch-set，给出当前 patch set 的信息
patch-sets，给出所有 patch set 的信息
commit-message，给出 change 的完整 commit message
all-reviewers，给出所有 reviewer 的 name 和 email

举个例子：查询某个提交的信息，可以得到这次提交的，项目名字，owner, uploader，commit 信息，更新时间，code-reviewer,appover等。

ssh -p 29418 {gerrit_server} gerrit query --format=text change:123456 --current-patch-set

其他常用命令：

git review：将本地代码推送到Gerrit进行审查。
git review -s：设置Gerrit的地址。
git review -d ：下载Gerrit上的代码变更。
git review -m ：查看Gerrit上的代码变更。
git review -s ：提交对Gerrit上的代码变更的评论。
git review -R ：提交对Gerrit上的代码变更的审批。
git review -l ：列出Gerrit上的指定仓库的代码变更。