Gerrit项目管理指南

Gerrit项目管理

前提条件

• Gerrit系统以及相关插件已成功安装、配置，可正常运行。

• 已有Gerrit账号，并且有管理员权限，有权限才能执行本文所述的各种操作。

• 本文以3.1.11版为例，不同版本的Gerrit系统，菜单位置和名称可能略有差异。

创建项目

图形界面方式

1. 通过网页的BROWSE->Repositories进入项目管理页面；

2. 点击右上角的Create New菜单，弹出Create Repository对话框；

3. 在Repository name对话框中输入仓名等信息后，点CREATE菜单即可创建成功，其中几个选项分别是：

   • Repository name，仓名，必填，可以包含/字符、英文大小写、数字；
   • Rights inherit from，权限集成自，选填，指定已有仓名，默认是All-Projects；
   • Owner，选填，指定项目所有者，指定的所有者即便不是管理员也有Review+2等权限；
   • Create initial empty commit，用于指定是否创建一个空提交，默认为True；
   • Only serve as parent for other repositories，用于指定当前仓仅作为Parent仓，默认为False；

命令行界面方式

Gerrit命令行界面的统一使用方式为：

$ ssh -p 29418 $GERRIT_USER@$GERRIT_HOST gerrit sub-cmd

其中，

• $GERRIT_USER 是具有管理员权限的Gerrit用户名；
• $GERRIT_HOST是Geriit系统主机名或IP地址；
• sub-cmd是具体的gerrit子命令，可以用--help查看；

创建项目的子命令为create-project，具体使用方式可以加--help查看：

$ ssh -p 29418 gerritadmin@localhost gerrit create-project --help
gerrit create-project [NAME] [--] [--branch (-b) BRANCH] [--change-id [TRUE | FALSE | INHERIT]] [--content-merge [TRUE | FALSE | INHERIT]] [--contributor-agreements [TRUE | FALSE | INHERIT]] [--create-new-change-for-all-not-in-target (--ncfa)] [--description (-d) DESCRIPTION] [--empty-commit] [--help (-h)] [--max-object-size-limit VAL] [--new-change-for-all-not-in-target [TRUE | FALSE | INHERIT]] [--owner (-o) GROUP] [--parent (-p) NAME] [--permissions-only] [--plugin-config VAL] [--reject-empty-commit [TRUE | FALSE | INHERIT]] [--require-change-id (--id)] [--signed-off-by [TRUE | FALSE | INHERIT]] [--submit-type (-t) [INHERIT | FAST_FORWARD_ONLY | MERGE_IF_NECESSARY | REBASE_IF_NECESSARY | REBASE_ALWAYS | MERGE_ALWAYS | CHERRY_PICK]] [--suggest-parents (-S)] [--trace] [--trace-id VAL] [--use-content-merge] [--use-contributor-agreements (--ca)] [--use-signed-off-by (--so)]

 NAME                                   : name of project to be created
 --                                     : end of options (default: false)
 --branch (-b) BRANCH                   : initial branch name
                                          (default: master)
 --change-id [TRUE | FALSE | INHERIT]   : if change-id is required (default:
                                          INHERIT)
 --content-merge [TRUE | FALSE |        : allow automatic conflict resolving
 INHERIT]                                 within files (default: INHERIT)
 --contributor-agreements [TRUE |       : if contributor agreement is required
 FALSE | INHERIT]                         (default: INHERIT)
 --create-new-change-for-all-not-in-tar : if a new change will be created for
 get (--ncfa)                             every commit not in target branch
 --description (-d) DESCRIPTION         : description of project (default: )
 --empty-commit                         : to create initial empty commit
                                          (default: false)
 --help (-h)                            : display this help text (default: true)
 --max-object-size-limit VAL            : max Git object size for this project
 --new-change-for-all-not-in-target     : if a new change will be created for
 [TRUE | FALSE | INHERIT]                 every commit not in target branch
                                          (default: INHERIT)
 --owner (-o) GROUP                     : owner(s) of project
 --parent (-p) NAME                     : parent project
 --permissions-only                     : create project for use only as parent
                                          (default: false)
 --plugin-config VAL                    : plugin configuration parameter with
                                          format '<plugin-name>.<parameter-name>
                                          =<value>'
 --reject-empty-commit [TRUE | FALSE |  : if empty commits should be rejected
 INHERIT]                                 on submit (default: INHERIT)
 --require-change-id (--id)             : if change-id is required
 --signed-off-by [TRUE | FALSE |        : if signed-off-by is required
 INHERIT]                                 (default: INHERIT)
 --submit-type (-t) [INHERIT |          : project submit type
 FAST_FORWARD_ONLY | MERGE_IF_NECESSARY    
 | REBASE_IF_NECESSARY | REBASE_ALWAYS     
 | MERGE_ALWAYS | CHERRY_PICK]             
 --suggest-parents (-S)                 : suggest parent candidates, if this
                                          option is used all other options and
                                          arguments are ignored (default: false)
 --trace                                : enable request tracing (default:
                                          false)
 --trace-id VAL                         : trace ID (can only be set if --trace
                                          was set too)
 --use-content-merge                    : allow automatic conflict resolving
                                          within files
 --use-contributor-agreements (--ca)    : if contributor agreement is required
 --use-signed-off-by (--so)             : if signed-off-by is required

其中，

• --parent和图形界面的Rights inherit from对应，用于指定权限继承自哪个仓；
• --owner 和图形界面的Owner对应；
• --empty-commit和图形界面的Create initial empty commit对应，用于指定是否创建一个空提交；
• --permissions-only和图形界面的Only serve as parent for other repositories对应，用于指定当前仓仅作为Parent仓；

创建分支

图形界面方式

1. 在Gerrit项目管理界面搜索到项目之后，点击项目名称进入某个项目的设置页面，例如hello-world；
2. 点击界面左侧的Branches进入分支管理页面，点击右上角的CREATE NEW，弹出Create Branch对话框；
3. 在Create Branch对话框中，输入分支名点击CREATE即可创建分支；
   • Branch name，必填，分支名；
   • Initial Revision，选填，版本号，默认是HEAD所指向的版本号；

命令行界面方式

使用gerrit命令的create-branch子命令创建分支，具体参数及使用方式如下：

$ ssh -p 29418 gerritadmin@localhost gerrit create-branch --help
gerrit create-branch PROJECT NAME REVISION [--] [--help (-h)] [--trace] [--trace-id VAL]

 PROJECT        : name of the project
 NAME           : name of branch to be created
 REVISION       : base revision of the new branch
 --             : end of options (default: false)
 --help (-h)    : display this help text (default: true)
 --trace        : enable request tracing (default: false)
 --trace-id VAL : trace ID (can only be set if --trace was set too)

其中，

• PROJECT对应界面操作中，选择的项目；
• NAME对应Branch name，为分支名；
• REVISION对应Initial Revision，版本号；

git push方式创建分支

管理员权限的用户可以直接向refs/heads/*推送，refs/heads/*引用是直接和Gerrit仓库中的分支对应的，不用进行Review流程；

所以，也可以通过git push的方式创建分支，具体操作为：

在代码仓中执行如下命令：

$ git push origin HEAD:refs/heads/$BRANCH_NAME

其中，$BRANCH_NAME 为具体分支名；

已有项目导入

已有项目的导入，需要对已有项目的所有代码仓执行如下两个步骤，分别为：

1. 创建gerrit代码仓，可以使用gerrit命令行的create-project子命令进行；
2. 将已有提交记录导入gerrit对应代码仓中，可以对refs/heads/*引用直接使用git push的方式进行；

关于直接推送提交记录，需要注意的是，

• Gerrit默认限制了git push一次性推送的提交记录条数，默认10000条，一次推送的提交记录数大于该值会导致push失败；
• Gerrit默认不允许强制推送（git push的--force选项），需要修改All-Projects的refs/heads/*的Push权限后才可以强制推送；

关于强制推送，需要注意的是，

• 强制推送功允许使用最新的推送覆盖目标分支上已有的提交记录，需要谨慎使用；
• 但是强制推送功能对于分批此推送提交记录较多的仓非常有用；

提交记录大于10000条的代码仓的导入方法

处理思路——分批次提交：

1. 从最早的提交记录开始计算；
2. 将该仓的当前版本指针（HEAD）向后移动5000条提交记录；
3. 进行一次push，如果push成功则重复执行第2步；否则，执行报错并结束推送过程；

成员权限管理

Gerrit支持多种方式的权限管理方式：

• 项目默认权限（All-Projects）设置
  • 项目权限继承
  • All-Projects是新项目的默认继承项目（不指定parent）
• 单个项目的权限管理
  • 单个项目也可以设置每一种权限允许的范围
  • 允许范围是以组（Group）为单位的
  • 权限可以被其他项目继承，但是不要删除它
• 组（Group）管理
  • 管理员可以创建组，没有删除界面（图形和命令都没有）
  • 管理员和组Owner可以管理组成员（Memebers）
  • 一个组可以添加多个成员
  • 一个成员可以属于多个组