Gerrit 使用教程

1 简介

Gerrit 是建立在 git 版本控制系统之上的，基于 web 的代码审核工具。Gerrit 是免费的，开源的，有一个可视化界面可供用户操作。主要解决的问题是代码审核。他在传统的源码工具管理协作流程中强制性引入代码审核机制，通过人工代码审核和自动化代码验证的方式，不符合要求的代码屏蔽在代码库之外，确保核心代码多人校验、多人互备和自动化构建核验。

1.1 Gerrit 和 Git 区别

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

1.2 Gerrit 和 Gitlab 区别

• 开发风格
  gitlab 的特点是一个人维系一个分支。
  gerrit 的特点是一个团队维系一个分支。
• 权限管理
  gitlab 可以根据需要创建 project，每个团队可以根据自己的需求管理自己的代码，方式更加的灵活。
  gerrit 比较单一，而且权限配置比较复杂，往往都是要联系管理员做出修改，每个团队很难做到对代码的个性化管理。
• 代码评审
  gitlab 是以 merge request 作为一次 review，merge request 中可能包含多个 commit，如果 review 不通过也不需要发起另一次 merge request。
  gerrit 是以 commit 作为一次 review，由于 changeId 的存在，可以对一次commit反复的进行review。 如果task划分的粒度够细的话，并不会影响各个团队的review习惯。
• 团队协作
  gitlab 可以选择公开代码，团队间可以看到互相的代码，有利于团队的协作。
  gerrit 由于权限控制问题，只能在权限范围内公开代码。
• 信息共享
  gitlab 可以提供 issues，wiki 等功能方便开发者与使用者之间的沟通，并且 gitlab 可以无缝的与一些项目管理工具集成，比如:jira。
  gerrit 这个方面比较欠缺。

2 工作流程

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

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

在使用过程中，有两点需要特别注意下：

1. 当进行 commit 时，必须要生成一个 Change-Id，否则，push 到 gerrit 服务器时，会收到一个错误提醒。
2. 提交者不能直接把代码推到远程的 master 主线(或者其他远程分支)上去。这样就相当于越过了 gerrit了。 gerrit 必须依赖于一个 refs/for/*的分支。假如我们远程只有一个 master 主线，那么只有当你的代码被提交到 refs/for/master 分支时，gerrit 才会知道，我收到了一个需要审核的代码推送，需要通知审核员来审核代码了。

当审核通过之后，gerrit 会自动将这条分支合并到 master 主线上，然后邮件通知相关成员，master 分支有更新，需要的成员再去pull就好了。

3 常用 ssh 命令

参考文档：Gerrit 代码审查 - 命令行工具

3.1 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
-b
该命令将显示每个项目的 sha 的分支。该命令可能有多个 --show-branch 参数，在这种情况下，将为每个分支显示 sha。如果用户没有对某个分支的 READ 访问权限或该分支不存在，则-显示存根（40 个符号）。如果用户无权访问项目中的任何分支，则不会显示整个项目。
–description
-d
允许列出项目及其各自的描述。
对于文本格式输出，所有不可打印的字符（ASCII 值 31 或更小）都根据 C、Python 和 Perl 等语言中使用的约定进行转义，使用标准序列（如\nand \t），以及 \xNN所有其他语言。在 shell 脚本中，该printf命令可用于取消转义输出。
–tree
-t
以树状格式显示项目继承。此选项不能与 show-branch 选项一起使用。
–type
仅显示指定类型的项目。如果未指定，则默认为all. 支持的类型：

• code：任何可能包含用户文件的项目。
• permissions：使用–permissions-only标志创建的项目。
• all：任何类型的项目。

–format
显示结果的输出格式。

• text：简单的基于文本的格式。
• json：描述每个项目的 JSON 对象的映射。
• json_compact：最小化 JSON 输出。

–all
显示调用用户帐户可访问的所有项目。除了调用用户帐户已被授予“读取”访问权限的项目外，这包括调用用户帐户拥有的所有项目（即使这些项目的“读取”访问权限未分配给调用用户帐户）。
–limit
将结果数限制为前 N 个匹配项。
–prefix
将结果限制为以指定前缀开头的项目。
–has-acl-for
仅显示直接分配了该组访问权限的项目。仅继承该组访问权限的项目未列出。
使用此选项，您可以了解在哪些项目上使用了一个组。

3.2 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 

返回格式如下（敏感信息已修改）：

change 
{
    
    
    "project":"android",
    "branch":"master",
    "id":"I123456e0b9a36b7298e34d1fafea7cc316086af2",
    "number":123456,
    "subject":"gerrit test.",
    "owner":{
    
    
        "name":"zhangsan",
        "email":"[email protected]",
        "username":"zhangsan"
    },
    "url":"http://tvcode.alibaba-inc.com/c/android/platform/frameworks/av/+/123456",
    "commitMessage":"gerrit test.\n\nChange-Id: I123456e0b9a36b7298e34d1fafea7cc316086af2\n",
    "createdOn":1662521286,
    "lastUpdated":1662521286,
    "open":true,
    "status":"NEW",
    "currentPatchSet":{
    
    
        "number":1,
        "revision":"a34e0ae3cff867a3da208fde01e4bbd0b1b12cfe",
        "parents":[
            "3ee56663b2006606bc2003973761ad778067534f"
        ],
        "ref":"refs/changes/04/123456/1",
        "uploader":{
    
    
            "name":"zhangsan",
            "email":"[email protected]",
            "username":"zhangsan"
        },
        "createdOn":1662521286,
        "author":{
    
    
            "name":"zhangsan",
            "email":"[email protected]",
            "username":"zhangsan"
        },
        "kind":"REWORK",
        "approvals":[{
    
    
          type: Commit-Msg
          description: Commit-Msg
          value: 1
          grantedOn: 2022-9-07 09:29:25 CET
          by:
            name: 
            email: 
            username: 
        },
        {
    
    
          type: Verified
          description: Verified
          value: 1
          grantedOn: 2022-9-07 06:48:50 CET
          by:
            name: 
            username: 
        },
        {
    
    
          type: Code-Review
          description: Code-Review
          value: 1
          grantedOn: 2022-9-07 10:05:14 CET
          by:
            name:  
            email: .@.com
            username: 
        },
        {
    
    
          type: Code-Review
          description: Code-Review
          value: 1
          grantedOn: 2022-9-07 08:08:44 CET
          by:
            name:  
            email: .@.com
            username: 
        },
        {
    
    
          type: Code-Review
          description: Code-Review
          value: 2
          grantedOn: 2022-9-07 08:09:17 CET
          by:
            name:   
            email: 
            username: 
        },
        {
    
    
          type: SUBM
          value: 1
          grantedOn: 2022-9-07 08:14:25 CET
          by:
            name:  
            email: .@.com
            username: 
        }],
        "sizeInsertions":2,
        "sizeDeletions":-1
    }
}
 
{
    
    
    "type":"stats",
    "rowCount":1,
    "runTimeMilliseconds":126,
    "moreChanges":false
}

4 总结

gerrit 作为谷歌管理安卓项目的版本管理工具还是有其优点的， 多部门之间的权限隔离，强制 review 的机制都是其优点。反观 gitlab 作为 github 的开源版，遵循了一套开源的流程，比较符合大多数人得习惯。
所以，通过比较，推荐使用 gitlab 作为版本管理工具，尤其是小团队，gitlab的审核功能足够了。gitlab + gerrit 更是架空了 gitlab，还多费一遍事。