前言
在使用 Gerrit 代码审查系统的过程中，无论是日常的代码审核，还是作为管理员对服务器进行维护管理，命令行接口（CLI）都提供了非常高效的交互方式。Gerrit 在 SSH 端口（默认 29418）上提供了一个专用的 SSH 守护进程（SSH Daemon）来处理各类管理命令，用户可以像执行普通 shell 命令一样，通过 SSH 连接到 Gerrit 服务器并执行 gerrit 开头的管理指令。
本文将系统性地总结 Gerrit 命令行环境下的常用管理操作，涵盖项目（project）、分支（branch）、标签（tag）以及提交（commit）的查询与管理方法，并介绍提高查询效率的实用技巧。
一、准备工作：SSH 访问配置
在执行任何 Gerrit SSH 命令之前，需要确保正确配置了 SSH 访问：
- 生成 SSH 密钥对 （如尚未生成）：
ssh-keygen -t rsa -C "your_email@example.com" - 获取公钥内容 ：
cat ~/.ssh/id_rsa.pub - 将公钥添加到 Gerrit 账户：登录 Gerrit Web 界面 → 点击右上角齿轮图标进入 Settings → SSH Keys → 粘贴公钥并保存
配置完成后，即可通过以下格式执行命令：
bash
ssh -p <端口> <用户名>@<Gerrit服务器地址> gerrit <命令> [参数]若不确定正确的 SSH 端口号，可通过 Gerrit Web 界面的用户设置查看，或联系管理员确认。如需查看所有可用命令，可执行：ssh -p 29418 <用户名>@<服务器> gerrit --help。
二、项目（Project）管理
2.1 基础命令：ls-projects
ls-projects 命令用于列出当前用户可见的项目列表。这是 Gerrit 命令行中最基础、最常用的查询命令之一。
基本用法：
bash
ssh -p 29418 <用户名>@<gerrit服务器> gerrit ls-projects一般输出示例：
platform/manifest
tools/gerrit
tools/gwtorm默认输出格式为纯文本，每行一个项目名称，仅显示调用用户被授予了 READ 权限的项目。如果调用用户是 Administrators 组的成员，则会列出所有项目。
2.2 常用选项详解
| 选项 | 简写 | 说明 |
|---|---|---|
--show-branch <分支> |
-b |
为每个项目显示指定分支的最新 commit SHA |
--description |
-d |
同时显示项目的描述信息 |
--tree |
-t |
以树形结构展示项目的继承关系 |
| `--type {code | permissions | all}` |
| `--format {text | json | json_compact}` |
--all |
- | 显示所有可访问的项目（包括用户拥有的项目） |
--limit <N> |
- | 限制输出结果数量 |
--prefix <前缀> |
-p |
只显示以指定前缀开头的项目 |
--has-acl-for <GROUP> |
- | 只显示对该组直接分配了访问权限的项目 |
2.3 效率提升与高级用法
2.3.1 使用 JSON 格式输出
对于脚本自动化处理，建议使用 JSON 格式输出，便于解析：
bash
ssh -p 29418 <用户名>@<服务器> gerrit ls-projects --format jsonJSON 格式输出为 Map 对象，每个项目的详细信息以键值对形式呈现。JSON 输出格式在通过 HTTP 接口调用时，需要注意第一行为防脚本执行的垃圾 JSON 字符串，实际数据从第二行开始。
2.3.2 按前缀筛选（最常用的效率优化）
当 Gerrit 服务器上存在大量项目时，使用 --prefix 选项可以大幅减少输出量，提高查询效率：
bash
# 只显示以 platform/ 开头的项目
ssh -p 29418 <用户名>@<服务器> gerrit ls-projects --prefix platform/2.3.3 显示项目分支状态
使用 --show-branch 可以同时查看每个项目指定分支的最新 commit：
bash
ssh -p 29418 <用户名>@<服务器> gerrit ls-projects --show-branch master --show-branch stable输出示例：
platform/manifest 8a3b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b 9f8e7d6c5b4a3b2c1d0e9f8a7b6c5d4e3f2a1b2c
tools/gerrit d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0如果用户对某个分支没有 READ 权限或分支不存在，则显示 40 个减号（---...---）作为占位符。如果用户对项目中的任意分支都没有访问权限，则整个项目不会显示。
2.3.4 查看项目继承关系
使用 --tree 参数以树形结构查看项目之间的继承关系（该选项不能与 --show-branch 同时使用）：
bash
ssh -p 29418 <用户名>@<服务器> gerrit ls-projects --tree输出示例：
All-Projects
|-- parent-project
|-- child-project如果调用用户不符合特定条件（如父项目状态为 HIDDEN 且用户无 refs/meta/config 的 READ 权限），parent 字段会被标记为 ?-N，其中 N 表示在项目树结构中的嵌套层级。
2.3.5 查询权限分配情况
使用 --has-acl-for 选项可以找出哪些项目直接为某个组分配了访问权限（仅显示直接分配的项目，不显示仅通过继承获得权限的项目）：
bash
ssh -p 29418 <用户名>@<服务器> gerrit ls-projects --has-acl-for "Developers"此选项非常适用于查找某个组在哪些项目上被直接使用。
2.3.6 限制结果数量
使用 --limit 选项分页获取结果，避免一次性输出过多数据：
bash
ssh -p 29418 <用户名>@<服务器> gerrit ls-projects --limit 100三、分支（Branch）管理
Gerrit 原生提供了 create-branch 命令用于创建分支。通过 SSH 执行 gerrit create-branch 可以在服务器端直接创建新的项目分支。
3.1 创建分支
bash
ssh -p 29418 <用户名>@<服务器> gerrit create-branch <项目名> <分支名> [起始提交]- 项目名：必填，指定目标项目
- 分支名：必填，新分支的名称
- 起始提交：选填，指定从哪个提交创建分支，默认为项目 HEAD
3.2 结合 Git 命令管理分支
由于 Gerrit 的底层是 Git 版本控制系统，大多数分支操作可以通过标准的 Git 命令结合 Gerrit 远程仓库完成：
bash
# 查看本地分支
git branch
# 查看所有远程分支
git branch -r
# 查看所有分支（本地+远程）
git branch -a
# 查看本地分支及关联的远程分支
git branch -vv
# 切换分支
git checkout <分支名>
# 创建并切换分支
git checkout -b <新分支名>
# 删除本地分支
git branch -d <分支名>
# 删除远程分支
git push origin --delete <分支名>关于分支操作的更多细节，可参考《Gerrit 相关使用教程》中的分支管理章节。
四、标签（Tag）管理
Gerrit 服务器本身不提供独立的 ls-tags SSH 命令，标签的管理主要通过 Git 标准命令完成。
4.1 创建标签
bash
# 创建带注释的标签（推荐）
git tag -a v1.0.0 -m "Release version 1.0.0"
# 为历史提交创建标签
git tag -a v1.0.0 <commit_id> -m "Tag for historical commit"
# 创建轻量级标签
git tag v1.0.04.2 推送标签到远程仓库
bash
# 推送单个标签
git push origin v1.0.0
# 推送所有本地标签
git push origin --tags4.3 查看与验证标签
bash
# 查看所有标签
git tag
# 查看标签详细信息
git show v1.0.04.4 删除标签
bash
# 删除本地标签
git tag -d v1.0.0
# 删除远程标签
git push origin :refs/tags/v1.0.04.5 效率提示
如果不希望克隆整个仓库，可以使用 git ls-remote 命令远程查看标签信息，该命令比克隆整个仓库快得多且占用带宽更少：
bash
git ls-remote --tags ssh://<用户名>@<服务器>:29418/<项目名>五、提交（Commit）查询
5.1 核心命令：gerrit query
gerrit query 是 Gerrit 命令行中最强大的查询工具，用于查询变更集（Changes）数据库。默认情况下，查询结果按变更的更新时间从近到远排序。
基本用法：
bash
ssh -p 29418 <用户名>@<服务器> gerrit query <查询条件>5.2 常用查询条件
| 查询字段 | 格式 | 说明 |
|---|---|---|
project / p |
project:PROJECT_NAME |
查询指定项目下的变更 |
branch |
branch:BRANCH_NAME |
查询指定分支上的变更 |
commit |
commit:SHA1 |
查询包含该 SHA-1 作为补丁集的变更 |
change |
change:CHANGE_ID |
查询指定的 Change-Id |
owner / o |
owner:USERNAME |
查询指定提交者的变更 |
reviewer / r |
reviewer:USERNAME |
查询指定审核人的变更 |
message |
message:TEXT |
查询提交消息中包含指定文本的变更 |
status |
status:open/merged/abandoned |
按状态筛选 |
label |
label:Verified+1 |
按标签值筛选 |
age |
age:7d |
查询指定天数内的变更 |
时间单位支持 ：s（秒）、m（分钟）、h（小时）、d（天）、w（周）、mon（月）、y（年）。
5.3 常用输出选项
| 选项 | 说明 |
|---|---|
| `--format {TEXT | JSON}` |
--current-patch-set |
仅输出当前补丁集信息 |
--patch-sets |
输出所有补丁集信息 |
--commit-message |
输出完整的提交消息 |
--files |
输出补丁集包含的文件列表 |
--comments |
输出所有评论信息 |
--all-reviewers |
输出所有审核人的姓名和邮箱 |
--start <n> / -S <n> |
跳过前 n 条记录，用于分页 |
limit:<n> |
限制结果数量（可在查询条件中指定） |
5.4 实用查询示例
5.4.1 通过 Commit SHA-1 查询
bash
ssh -p 29418 <用户名>@<服务器> gerrit query commit:4e8ea8d43ab22273e4949348e1e7316f88cd54e3 --current-patch-set --format JSON该命令通过查询接口和提交 ID 来查询 Gerrit 变更，输出包含当前补丁集信息的 JSON 格式数据。
5.4.2 通过 Change-Id 查询
bash
ssh -p 29418 <用户名>@<服务器> gerrit query change:I03369813660369E983B56DCABE4CB48839BE4DE0 --patch-sets5.4.3 多条件组合查询
bash
# 查询某个项目特定分支上状态为 open 的变更，限制 10 条
ssh -p 29418 <用户名>@<服务器> gerrit query project:myproject branch:master status:open limit:10
# 查询 7 天内自己提交的变更
ssh -p 29418 <用户名>@<服务器> gerrit query owner:self age:7d --format JSON5.4.4 分页查询处理大量结果
gerrit query 命令默认最多返回一定数量的记录（通常为 500 条左右）。对于超过默认限制的结果集，可以使用 --start 参数实现分页：
bash
# 获取前 500 条
ssh -p 29418 <用户名>@<服务器> gerrit query status:open
# 获取第 501-1000 条
ssh -p 29418 <用户名>@<服务器> gerrit query status:open --start 500 limit:500最后一条结果中的 moreChanges 字段若为 true，表示还有更多记录。
5.4.5 通过 Change-Id 查询对应的 Git Commit ID
使用 gerrit query --current-patch-set 查询变更，输出结果中会包含当前补丁集的提交 SHA-1（commit ID）：
bash
ssh -p 29418 <用户名>@<服务器> gerrit query change:CHANGE_ID --current-patch-set --format JSON5.5 效率提升建议
- 优先使用 JSON 格式 ：在脚本中使用
--format JSON输出，便于程序解析和处理 - 合理使用 limit 和 start：处理大量结果时务必使用分页，避免内存溢出
- 使用精确查询条件 ：优先使用
commit:、change:等精确字段，避免全库扫描 - 利用 age 字段过滤 ：如果只关心近期变更，使用
age:限制时间范围 - 多条件组合缩小范围 ：
project:+branch:+status:的组合能大幅缩小查询范围
六、综合对比与场景推荐
| 管理对象 | 核心命令 | 辅助工具 | 效率关键点 |
|---|---|---|---|
| 项目 | gerrit ls-projects |
--prefix、--limit、JSON 格式 |
使用前缀筛选和分页 |
| 分支 | git branch / gerrit create-branch |
git checkout、git push |
结合 Git 标准命令 |
| 标签 | git tag / git ls-remote --tags |
git push --tags |
远程查询无需克隆 |
| 提交 | gerrit query |
--format JSON、--start |
精确字段 + 分页 |
七、常见问题与解决方案
Q1：ls-projects 输出结果太多，如何高效筛选？
解决方案 ：使用 --prefix 按项目名前缀筛选，或使用 --limit 限制返回数量。如果使用 HTTP 接口，还可以在 URL 中直接指定前缀，如 /projects/external/。
Q2：query 查询结果不完整怎么办？
解决方案 ：检查返回结果中的 moreChanges 字段。如果为 true，说明还有更多记录，使用 --start 参数继续获取下一页。同时确认查询条件是否过于宽泛。
Q3：如何通过 Change-Id 找到对应的 Git Commit ID？
解决方案 ：使用 gerrit query change:CHANGE_ID --current-patch-set --format JSON，输出结果中的 currentPatchSet → revision 字段即为对应的 commit SHA-1。
Q4：gerrit ls-projects 显示的项目不完整？
解决方案 ：首先确认当前用户是否具有足够的权限------普通用户只能看到被授予 READ 权限的项目，管理员可以看到所有项目。如果确实需要查看自己拥有但无 READ 权限的项目，可以使用 --all 选项。
Q5：查询结果中的分支显示为 40 个减号（---...---）是什么意思？
解决方案：这表示当前用户对该分支没有 READ 权限，或者该分支不存在于该项目中。
八、总结
本文系统梳理了 Gerrit 命令行环境下的项目、分支、标签和提交查询管理方法，核心要点如下：
- 项目管理 ：
gerrit ls-projects配合--prefix、--show-branch、--tree等选项，可以灵活高效地查询项目信息 - 分支管理 ：通过
gerrit create-branch和标准 Git 命令组合完成 - 标签管理 ：使用 Git 标准命令
git tag、git push --tags和git ls-remote --tags进行操作 - 提交查询 ：
gerrit query是核心工具，支持多种查询条件组合、分页和 JSON 格式输出
掌握这些命令和技巧，可以大幅提升日常使用 Gerrit 进行代码审查和服务器管理的效率。建议在实际使用中，多用 --help 查看当前版本命令的具体参数，因为不同 Gerrit 版本之间可能存在细微差异。
关于 SSH 连接参数的补充说明：如果使用非标准 SSH 端口或需要指定密钥文件，可以在
~/.ssh/config中配置，或使用ssh -i <私钥路径>参数指定。配置正确后，所有gerrit命令都将更加流畅。