Gerrit Workbench在 VS Code 中完成 Gerrit 连接、提交、代码评审、评论、回复、评分和变更管理。常用功能通过侧边栏、编辑器按钮和右键菜单操作,无需 Ctrl+Shift+P。 自动恢复登录网页登录密码(HTTP 反向代理)模式使用已保存的凭据自动重新登录,无需为会话过期手动重新连接。身份检查返回 403、旧 CSRF 令牌被拒绝或令牌缺失时,也会清除旧会话、重新登录并重试原请求一次,并发请求共用一次重登。重新登录后仍被拒绝才显示具体权限 / 凭据错误;日志记录自动重登过程,不记录凭据。超时、网络断开和服务器 5xx 不会自动重发操作。外部浏览器登录由服务器管理;密码变更需更新保存的凭据。 评审阅读与评论状态差异视图会异步加载此前 PS 的代码评论,并在每条评论及线程标题中标注原 PS。未改动的行会映射到当前代码;原行已修改、删除或无法准确映射时保留为文件级评论,注明原位置,可从“本文件评论”跳回原 PS。回复仍发送到评论原来的 PS、文件和行号。比较两个 PS 时,两侧各自显示本版评论,其余较早评论集中在较新一侧,避免重复。 点击检索结果卡片直接打开评审讨论,复用现有讨论标签;工作台仍保留版本比较,返回时不重跑检索。 “发布评审”和“当前评分”放在同一个右侧居中浮窗中,宽窄窗口的位置一致,内部独立滚动。点“收起”可临时缩成标题条,展开后保留尚未发送的评论和评分选择。 Code-Review / Verified 只显示实际分值按钮,移除“不修改评分”。默认高亮当前账号已有评分,无评分时显示 0;点击当前分数不取消、不产生变更。选择不同分数后,点击“发布评审”才发送;与已有评分相同的项不重复提交。 讨论页用橙色区分未解决线程、绿色区分已解决线程。已解决默认折叠、未解决默认展开,全局评论默认展开;可手动收起或展开,解决状态改变后采用对应的新默认值。代码页用不同颜色的行号旁图标、行尾数量和滚动条标记区分状态,原生评论标签也显示已解决 / 未解决。删除“默认展开代码评论”设置,其他设置仍保留。 工作台和对比差异的代码评论数采用 未解决(已解决) 格式,例如 2(5) 表示 2 个未解决、5 个已解决的代码讨论线程。按线程最后一条评论的状态统计,回复不重复计数,全局评论不计入代码讨论数。 冲突提交链接使用链接蓝色和下划线。详情页编号旁的状态文字也按问题状态显示颜色:Open 蓝、WIP 棕、可合入粉、已合入绿、已废弃红;负分另以橙色提示,不改变服务器的可合入判断。 讨论页内操作与状态颜色自己的 Open / WIP 提交在评审讨论的“评审人员”框内直接输入姓名、邮箱或组名,选择下方候选即可添加人员或整组成员;点击已有人员旁的 × 删除。支持键盘切换候选;请求过期后不会误加其他人员,工作台和讨论页的候选相互隔离。人员管理只更新对应区域,不打断正在输入的评审评论。 评分直接点击允许的分值按钮,默认显示当前账号评分;Code-Review / Verified 不再显示“不修改评分”,重复点击当前分值不改变评分。发布评审与当前评分统一放入右侧居中的组合浮窗,宽窄窗口一致,可收起并在内部滚动。 工作台的版本对比可选择 Edit(已保存草稿),与任意 PS 或 Base 双向对比;也可点“查看 Edit 改动”直接对比草稿与其原 PS。需先保存本地 Edit,比较不会生成 PS。Edit 快照不提供代码评论,发布后可对新 PS 评论。“废弃 Edit”删除整份服务器草稿,不影响已发布的 PS;未保存内容存在时先停止废弃,请先保存或在编辑器中撤销改动。废弃后可在同一 PS 开始新的 Edit。 自己的 Open / WIP 最新 PS 固定显示 Rebase 入口;不再因服务器遗漏动作标记而隐藏。选择 Base 后由服务器校验权限和操作是否可行,历史 PS 需先切回最新 PS。
色条优先级:已合入 / 已废弃 → 负分 → WIP → 可合入 → 普通 Open。颜色仅用于提醒,是否“可合入”严格使用服务器 submittable;有负分但服务器允许合入时,显示橙色色条及“可合入”文字,不自行禁用合入。具体色调随 VS Code 主题变化。 Edit、发布与 Rebase打开自己的 Open / WIP 提交的最新 PS 文本 diff,点击编辑器右上角 Edit。左侧 Base / 已选 PS 始终只读,只有右侧 Edit 可修改。使用右上角“保存 Edit 草稿”或 Ctrl+S 保存到 Gerrit 私有草稿,不依赖本地仓库,也不会直接改目标分支。 同一提交的所有文件共用一份 Edit 草稿。 可以依次编辑多个文件,保存不会生成 PS。修改全部完成后点“发布 Edit 为新 PS”,插件先保存该提交所有已打开且有修改的 Edit 文件,再把整份草稿发布为一笔新 PS;不会逐文件发布。某个文件保存失败或仍有未保存改动时停止发布,内容保留在编辑器中。最新 PS 或服务器草稿被其他窗口更新时拒绝覆盖,需先处理变动后重开。保存过的草稿可在 Gerrit Web 继续处理;未保存内容应在关闭窗口前保存。 工作台和评审讨论都提供当前权限允许的“发布为待评审”(WIP → 评审)、Rebase、“合入分支”及 Edit 发布入口。Rebase 可自动沿用依赖关系、直接基于目标分支,或输入 Gerrit 号 / SHA / ref。旧 Edit 需要先 Rebase Edit 到最新 PS,再发布。操作使用服务器权限校验;不提供绕过权限或强制合入。 推送、发布、合入、废弃和人员管理不再弹出额外确认告警。仍保留目标分支、上传方式、Rebase 目标等必要输入,以及失败时的错误提示。 Commit 信息、关系链分别记住工作台和评审讨论中的展开 / 收起状态,跨变更和重启保留;不再提供默认展开设置。关系链只显示有 Gerrit 编号的关联节点,移除重复父 SHA 行;非最新 PS 显示旧版本标记,Commit 信息中的父提交导航仍保留。 冲突检查在后台运行,区分与目标分支的合并冲突及与其他未合入提交的冲突;点击冲突提交可进入详情。若服务器不支持相关接口,明确显示检查不可用。评论导航改为带上下箭头的评论气泡,区别于更改导航。 上传分支与评审人员上传时读取所选 Git remote 的真实分支。同名远端分支存在时默认填入本地分支,否则留空;输入时忽略大小写筛选候选。选择后仍会检查待推送提交和 Change-Id,通过后上传。 自己的 Open / WIP 提交仅在评审讨论中提供“评审人员 · Code-Review / Verified”折叠栏,在框内按姓名、邮箱或组名搜索并添加,点已有人员旁的 × 删除。组展开为成员,按服务器协议自动确认组添加。移除人员同时移除其已有评分;实际操作受服务器权限控制。历史 PS 需切回最新 PS 再管理。 Gerrit 的评审人员属于整笔变更,不按 Code-Review、Verified 独立分配;添加人员不会授予打分权限。标签权限由服务器项目配置控制,评分仍按标签显示。 Excel 原文件对照插件保留二进制原字节和扩展名,交给 VS Code 在左右两个编辑器组打开旧、新文件,使用临时预览标签,不实现表格渲染或单元格 diff。 请另行安装 Office Viewer(xls / xlsx / xlsm)或 Excel Viewer(xlsx / xlsm)。若仍显示二进制提示,在文件标签右键“重新打开编辑器的方式…”选择查看器并设为默认。插件遵循 VS Code 编辑器关联,不强制更改其他类型的关联。复杂公式、图表和宏的显示取决于查看扩展,超过响应大小限制的文件仍不可打开。 安装与连接在扩展面板 从旧版 在扩展设置的 Language / 语言 中选择 认证方式每次连接二选一,不同时使用,密码与 Key 不可混用。默认选择网页登录密码;已有连接保留上次选择。服务器可能只支持其中一种:
密码仅保存在 VS Code SecretStorage;Cookie 和会话令牌保存在内存。需要跨站浏览器交互的 SSO / OAuth 尚不支持。HTTPS 保留证书校验;当前不提供独立的代理配置。 操作入口
行评论与回复绑定实际所在的 PS / Base。整体评审与评分针对页面注明的最新 PS。评论、回复、评分立即发布;整体评审和线程回复保留本地输入草稿,不自动发布服务器已有的其他草稿。可在讨论页为当前查看的 PS 发布全局评论,默认勾选「标记为已解决」,发布前可取消勾选。普通代码评论默认未解决。只有发起讨论的账号能用 Done 将线程标记为已解决。 “我已评审”使用 Gerrit 的 Message 的评论包含匹配由插件补充:Gerrit 原生评论索引没有同等的正则包含语义,因此会先按状态、Repo、Branch、Owner 限定范围,再跨分页读取 Commit / 评审记录和必要的行内评论,最多并发四个评论请求。范围较大时可先填 Repo / Branch 缩小搜索。查询采用已登录账号的可见范围,不进行代码正文或文件内容全文检索。 原文件缓存保留字节、扩展名及旧 / 新 / PS 目录标识,位于系统临时目录,不写进代码仓库。插件退出时尝试清理缓存;不内置 PDF、Excel 等格式的阅读器,也不安装文件查看扩展。 SSH 下载与上传下载读取 Gerrit 提供的 SSH URL(包括用户名、端口和项目路径),使用本机 OpenSSH 的配置、SSH key / agent,以 BatchMode 执行,避免后台等待密码。需要预先在 Gerrit 中添加 SSH 公钥,并在本机建立对应的 known_hosts 信任;插件不自动接受主机指纹,也不下载或保存私钥。 先在 VS Code 打开对应项目的本地 Git 仓库(remote 路径须匹配 Gerrit 项目)。评审页“代码与下载”选择 PS 后,后台执行 下载前和 checkout 前检查未提交文件、未保存编辑器和已有分支。已有同名分支时会提示先重命名或删除,不自动覆盖、stash 或强制切换。同一仓库的插件下载 / 上传不会并发执行;其他浏览和评审操作可继续使用。下载阶段、结果及失败原因显示在代码页和输出频道,完成通知无需关闭即可继续使用插件。SSH 下载不使用 HTTP 密码或 HTTP Key。 上传入口为侧边栏“上传本地提交”或源代码管理的云上传按钮。可提交已暂存内容后上传,也可只上传已有 HEAD;不自动暂存、不强推、不自动修改已有提交。先 fetch 目标分支、检查整组待上传 commit 的 Change-Id,再使用选定的 remote 和分支推送,不再弹出确认告警。上传使用 初次使用 Gerrit 的仓库请按服务器的 Clone with commit-msg hook 说明安装 hook。缺少 Change-Id 时,安装后通过终端 amend 对应 commit,再上传。 内置浏览器网页入口使用 VS Code 集成浏览器。为解决反向代理 HTTP Basic 登录的 401,插件在 桥接拒绝未认证、伪造 Host 和跨站请求;写操作保留 Gerrit 的 XSRF 验证。切换账号、断开连接或插件退出时关闭桥接。HTTP Key 模式下网页若需要网页登录密码,会单独询问,不替换已保存的 HTTP Key。 需要提供集成浏览器命令的新版 VS Code。旧版 Simple Browser 的 iframe 对认证和 Cookie 存在限制,因此不再回退到它;旧版 VS Code 仍可使用原生代码与评审功能。 扩展设置与输出点击侧边栏右上角齿轮打开本扩展设置:
评论标记颜色可通过 VS Code 右上角输出按钮打开 输出 → Gerrit Workbench。日志记录请求方法、路径、状态、耗时和 Git 操作结果,不记录认证头、Cookie、请求 / 响应正文;已知凭据和常见敏感字段脱敏。日志仍包含服务器和项目路径,分享前可自行隐藏。 活动栏使用独立的评审气泡勾选图标,扩展列表显示彩色插件图标。 开发、打包与提交要求 VS Code 1.95+ 和 Git;内置网页需要支持集成浏览器的较新版本。核心使用 CommonJS 和 Node 内置库;Markdown 库离线打包,无需 npm install。打开本项目按 F5 可启动 Extension Development Host。
也可使用独立 Node.js 执行 打包脚本先生成并校验新包,再清理本项目旧版本 VSIX,工作区仅保留一版安装包。每批完成的修改创建一笔本地 Git commit,不自动推送;详见 AGENTS.md。 测试覆盖认证会话、CSRF、浏览器桥接和跨站防护、版本比较、历史评论位置、完整 Patch 读取、SSH 下载引用与 SHA 校验、本地修改和已有分支保护、后台任务完成与重试、Windows 长路径、评论导航、时间排序、输入草稿和日志脱敏。内网已验证网页与脚本资源返回 200、Patch 改动文件及任意路径搜索,以及 SSH 分支读取与指定 PS 克隆 / fetch / checkout。真实 Extension Host 检查侧栏脚本渲染,以及评审页讨论 / 代码页签、文件与下载入口、底部修改文件视图、评分区滚动不重叠和草稿保留;服务器写入操作仍需实际账号验收。 评审标记与关系链依据:Gerrit 3.8.5 REVIEWED、Related Changes。 API 依据:Gerrit Changes REST API、上传评审、VS Code API。 Markdown 渲染使用离线打包的 markdown-it 15.0.3(MIT),许可证位于 media/vendor/markdown-it.LICENSE。 EnglishConnect, upload commits, review changes, comment on code, reply and vote from VS Code. Normal workflows use the sidebar, editor buttons and file panel without opening the Command Palette. Automatic session recoveryWebsite-password (HTTP reverse proxy) mode automatically signs in with saved credentials; expired sessions do not require manual reconnection. Identity checks returning 403 and rejected, missing or malformed CSRF tokens also trigger one fresh login and one retry, shared by concurrent requests. A rejection after that retry reports a specific permission or credential error. Logs describe recovery without credentials. Timeouts, dropped connections and server 5xx responses never replay operations. External-browser sign-in remains server-managed; update saved credentials if the password changes. Review reading and comment statesDiff views load earlier PS code comments in the background and label each comment and thread with its original PS. Unchanged lines map to the displayed code. Comments on changed, deleted or unmappable lines remain file-level threads with their original location; use File comments to jump to the original PS. Replies retain the original PS, file and line. When comparing two PS versions, each side shows its own comments, with other earlier comments on the newer side to avoid duplicates. Clicking a search-result card opens the review discussion directly and reuses the existing discussion tab. Comparisons remain in the workbench; returning does not repeat the search. Post review and current votes share one floating window centred on the right at every viewport width. It scrolls internally. Collapse reduces it to a title bar; expanding retains unsent comments and score choices. Code-Review / Verified show score buttons without an unchanged-score option. The current account's existing vote is preselected, or 0 when there is no vote. Clicking the selected score leaves it unchanged. Different scores are sent only by Post review; unchanged votes are omitted from the request. Discussion threads use orange for unresolved and green for resolved. Resolved threads start collapsed, unresolved threads expanded, and global comments expanded. Manual folding is retained until the resolution state changes. Code views distinguish states through coloured gutter icons, inline counts and overview-ruler markers; native thread labels also name the state. The default-expand-comments setting was removed; other settings remain. Workbench and comparison code-comment counts use unresolved(resolved), such as 2(5) for two unresolved and five resolved code discussion threads. The latest comment determines each thread's state. Replies are not counted again and global comments are excluded from code-thread counts. Conflicting-change links use link blue and underlines. Status text beside the change number uses blue for Open, brown for WIP, pink for ready to submit, green for merged and red for abandoned. Negative votes retain a separate orange indicator without overriding server eligibility. In-page review controls and state colorsOn your own Open / WIP changes, type a name, email or group name directly in the discussion's Reviewers box. Select a suggestion to add a person or group; use × next to an existing reviewer to remove them. Keyboard navigation is supported. Stale suggestions cannot add a different person, and sidebar/discussion suggestions are isolated. Reviewer updates preserve the review comment being edited. Score buttons preselect your current vote. Code-Review / Verified have no unchanged-score button; clicking the selected value does nothing. Post review and current votes share one collapsible right-centred window at every viewport width, with internal scrolling. The workbench comparison selectors include Edit (saved draft) for comparison against any PS or Base in either direction. Compare saved edit compares the draft to its original PS. Save local edits first; comparisons create no PS. Code comments require publishing the Edit as a PS. Discard edit deletes the whole private draft without changing published PS revisions. Dirty local buffers block discard until saved or undone. You can start a fresh Edit on the same PS afterwards. Your own Open / WIP latest PS always exposes Rebase, even when the server omitted action metadata. The server checks permission and feasibility after the Base is selected. Historical views must first switch to the latest PS.
Stripe priority: merged / abandoned, then negative votes, WIP, ready to submit and ordinary Open. Color is a warning, while eligibility uses the server's submittable flag. A negative-voted change that the server permits can show an orange stripe and Ready to submit together; the extension does not invent a submission block. Exact tones follow the VS Code theme. Edit, publish and rebaseOpen a text diff of the latest PS of your own Open / WIP change and choose Edit in the editor toolbar. The left Base / selected PS stays read-only; only the right Edit side is writable. Use Save Gerrit edit or Ctrl+S to save a private server-side draft, without a local repository or target-branch changes. All files in one change share one Edit draft. Edit and save multiple files; saving does not create a PS. When finished, choose Publish edit as new PS. It saves every open dirty Edit file for that change, then publishes the whole draft as one new PS. Files are never published individually. A failed save or remaining dirty buffer stops publication and retains editor content. Newer patch sets or edits changed in another window are not overwritten. Reconcile them and reopen the edit. Saved drafts can be continued in Gerrit Web; save unsaved content before closing the window. The workbench and discussion expose permitted actions: publish WIP for review, Rebase, submit and publish an Edit. Rebase can preserve dependencies automatically, use the target branch tip, or use an entered change number / SHA / ref. An old Edit must be rebased onto the latest PS before publication. All writes remain subject to server permissions. Uploads, publishing, submission, abandonment and reviewer changes no longer show extra confirmation warnings. Necessary target/mode/rebase inputs and failure messages remain. Commit and relation panels remember expansion separately for the workbench and discussion, across changes and restarts. The default-expansion settings were removed. Compact related changes show numbered Gerrit nodes, mark outdated patch sets and omit repeated parent-SHA rows. Parent navigation remains in commit metadata. Background conflict checks distinguish target-branch merge conflicts from conflicts with unmerged changes; conflicting changes link to details. Unsupported checks are explicitly marked unavailable. Comment navigation uses directional comment-bubble icons distinct from diff-change navigation. Upload branches and reviewersUploads read live branches from the selected Git remote. Prefill the local branch only when it exists remotely; otherwise start empty. Type to filter suggestions case-insensitively. Outgoing commits and Change-Ids are still checked before pushing, without a confirmation warning. Your own Open / WIP changes show a Reviewers · Code-Review / Verified section in the discussion page only. Type a name, email or group name in the box and select a suggestion; use × next to a reviewer to remove them. Groups expand into members; server-required group confirmation is handled automatically. Removing reviewers also removes their votes and remains subject to server permissions. Switch historical views to the latest PS before managing reviewers. Gerrit assigns reviewers to a whole change, not separately to Code-Review and Verified. Adding reviewers does not grant voting rights; server project configuration controls label permissions. Votes remain displayed per label. Excel original-file comparisonBinary snapshots retain their exact bytes and filename extension. VS Code opens the old and new copies in separate editor groups as preview tabs. Gerrit Workbench does not render spreadsheets or calculate cell differences. Install Office Viewer for xls / xlsx / xlsm or Excel Viewer for xlsx / xlsm separately. If a binary warning remains, right-click the tab, choose Reopen Editor With..., select the viewer and make it the default. The extension follows VS Code editor associations without overriding other formats. Rendering of complex formulas, charts and macros depends on the viewer. Files exceeding the response limit remain unavailable. Install and connectInstall Choose one authentication method per connection:
The methods are not combined; a server may support either or both. Existing connections keep the last choice. Passwords are stored in VS Code SecretStorage. Cookies and session tokens stay in memory. Interactive SSO/OAuth is not supported. HTTPS certificate verification remains enabled. LanguageIf you used Set Gerrit → Language to Main workflows
File reads are local progress markers, separate from Gerrit's reviewed-by-me state. That state means you commented or voted after the author's last update. Opening a file does not publish a Gerrit review. Overall reviews and votes target the latest PS. Historical PS pages require explicitly opening the latest PS before overall review or change-management actions. Inline replies retain the original revision. Use the discussion form to post a change-level comment on the patch set shown. By default, Mark as resolved is selected for change-level comments. Clear it to post an unresolved comment. New code comments start unresolved. Only the person who started a thread can mark it resolved with Done. Reviews publish immediately; drafts are never automatically published. SSH downloads and uploadsDownloads use the Gerrit-advertised SSH URL and your local OpenSSH key/agent and known_hosts. Password prompts and automatic host-key acceptance are disabled. No private keys are managed by the extension. Open a local Git repository whose remote project matches the change. The extension fetches the selected change ref, verifies FETCH_HEAD against its SHA, then creates Upload staged changes or the existing HEAD through the sidebar or Source Control upload button. The destination is Settings
Toolbar settings and output buttons open extension settings and the Gerrit Workbench output channel. Known secrets and authentication headers are redacted; request bodies and response bodies are not logged. Output can contain server/project paths. Development and local deliveryRun The source is available on GitHub. Download the VSIX from GitHub Releases. See release checks. MIT license; bundled markdown-it license is documented in third-party notices. |