aaronshaf/gerrit-workflow

Gerrit Workflow with ger CLI

This skill helps you work effectively with Gerrit code reviews using the ger CLI tool.

Prerequisites

The ger CLI tool must be installed and accessible in your PATH. It's available globally if installed from ~/github/ger.

Output Formats

Most commands support --json and --xml flags:

• --json — Structured JSON for programmatic consumption
• --xml — XML with CDATA-wrapped content, optimized for LLM/AI consumption
• (default) — Plain text / colored terminal output for humans

These are mutually exclusive; using both is an error.

Core Commands

Viewing Changes

Show comprehensive change information:

ger show [change-id]

Displays metadata, diff, and all comments. Auto-detects from HEAD commit if omitted.

View specific diff:

ger diff [change-id]
ger diff [change-id] --file src/api/client.ts   # specific file

View all comments:

ger comments [change-id]
ger comments [change-id] --unresolved-only

List changed files:

ger files [change-id]
ger files [change-id] --json

List reviewers:

ger reviewers [change-id]
ger reviewers [change-id] --xml

Listing Changes

Your open changes:

ger mine
ger list

Changes needing your review (reviewer OR cc'd):

ger incoming
ger team

Both query reviewer:self OR cc:self status:open. Options:

• --all-verified — Include all verification states (default: open only)
• -f, --filter <query> — Append custom Gerrit query syntax
• --status <status> — Filter by status: open, merged, abandoned
• -n, --limit <n> — Limit number of results (default: 25)
• --detailed — Show detailed info for each change
• --json / --xml

General list with options:

ger list --status merged
ger list --reviewer          # same as incoming
ger list -n 10 --json

Search with custom query:

ger search "owner:self is:wip"
ger search "project:my-project status:open" -n 10 --xml

Posting Comments and Votes

Post a comment:

ger comment [change-id] -m "Your comment"
echo "Review feedback" | ger comment [change-id]   # from stdin
ger comment [change-id] --file src/api/client.ts --line 42 -m "Inline comment"

Vote on a change:

ger vote <change-id> --code-review 2
ger vote <change-id> --verified 1 --message "Looks good"
ger vote <change-id> --label My-Label 1

Managing Changes

Abandon / restore:

ger abandon [change-id] -m "No longer needed"
ger restore [change-id]

Submit a change:

ger submit [change-id]

Set WIP / Ready:

ger set-wip [change-id]
ger set-wip [change-id] -m "Still working on tests"
ger set-ready [change-id]
ger set-ready [change-id] -m "Ready for review"

Topic:

ger topic [change-id]            # get current topic
ger topic [change-id] my-topic   # set topic
ger topic [change-id] --delete   # delete topic

Pushing Changes

Push changes to Gerrit:

ger push
ger push -b main -t my-feature -r [email protected] --wip

Options: -b, -t, -r, --cc, --wip, --ready, --hashtag, --private, --dry-run

Checkout and Cherry-Pick

Checkout a change locally:

ger checkout 12345
ger checkout 12345 --revision 3   # specific patchset

Cherry-pick a change into current branch:

ger cherry 12345
ger cherry 12345/3                # specific patchset
ger cherry 12345 --no-commit      # stage without committing
ger cherry 12345 --no-verify      # skip pre-commit hooks
ger cherry https://gerrit.example.com/c/my-project/+/12345

Rebase

Rebase a change on Gerrit (server-side):

ger rebase [change-id]
ger rebase [change-id] --base <sha-or-change>
ger rebase [change-id] --allow-conflicts   # rebase even with conflicts
ger rebase [change-id] --json

Auto-detects from HEAD commit if no change-id provided.

Retrigger CI

Post a CI retrigger comment:

ger retrigger [change-id]

Auto-detects from HEAD. Saves the retrigger comment to config on first use (or configure via ger setup).

Build Status

Check Jenkins build status:

ger build-status [change-id]
ger build-status --watch --interval 20 --timeout 1800
ger build-status --exit-status   # non-zero exit on failure (for scripting)

Extract build URLs:

ger extract-url "build-summary-report"
ger extract-url "build-summary-report" | tail -1

Canonical CI workflow:

ger build-status --watch --interval 20 --timeout 1800 && \
  ger extract-url "build-summary-report" | tail -1 | jk failures --smart --xml

Analytics

View merged change analytics (year-to-date by default):

ger analyze
ger analyze --start-date 2025-01-01 --end-date 2025-12-31
ger analyze --repo canvas-lms
ger analyze --json
ger analyze --xml
ger analyze --markdown
ger analyze --csv
ger analyze --output report.md   # write to file

Default start date: January 1 of current year.

Update ger to the latest version:

ger update
ger update --skip-pull   # reinstall without version check

View recent failures summary:

ger failures
ger failures --xml

Worktree (tree) Commands

Manage git worktrees for reviewing changes in isolation.

Setup a worktree for a change:

ger tree setup 12345
ger tree setup 12345:3     # specific patchset
ger tree setup 12345 --xml

Creates worktree at <repo-root>/.ger/<change-number>/.

List ger-managed worktrees:

ger trees
ger trees --json

Rebase a worktree (run from inside the worktree):

cd .ger/12345
ger tree rebase
ger tree rebase --onto origin/main
ger tree rebase --interactive   # interactive rebase (-i)

Remove a worktree:

ger tree cleanup 12345

Groups and Reviewers

Add reviewers:

ger add-reviewer [email protected] -c 12345
ger add-reviewer --group project-reviewers -c 12345
ger add-reviewer --cc [email protected] -c 12345
ger add-reviewer --notify none [email protected] -c 12345

Remove reviewers:

ger remove-reviewer [email protected] -c 12345

List groups:

ger groups
ger groups --pattern "^team-.*"
ger groups --project canvas-lms
ger groups --owned

Show group details / members:

ger groups-show administrators
ger groups-members project-reviewers

Configuration and Setup

ger setup          # interactive first-time setup
ger config list    # list all config
ger config get gerrit.url
ger config set gerrit.url https://gerrit.example.com

Auto-Detection

These commands auto-detect the change from the HEAD commit's Change-Id footer when no change-id is provided: show, build-status, topic, rebase, extract-url, diff, comments, vote, retrigger, files, reviewers

Common LLM Workflows

# Review a change
ger show <id> --xml
ger diff <id> --xml
ger comments <id> --xml

# Post a review
ger comment <id> -m "..."
ger vote <id> Code-Review +1

# Manage changes
ger push
ger checkout <id>
ger abandon <id>
ger submit <id>

# WIP toggle
ger set-wip <id>
ger set-ready <id> -m "message"

# Check CI
ger build-status <id> --exit-status

Notes

• Commands run from within a Gerrit repository
• Most commands accept an optional change-id; if omitted, they use the current branch's HEAD Change-Id
• The tool uses local SQLite caching for offline-first functionality
• --xml is preferred over --json for LLM/AI consumption (easier to parse)
• Numeric change numbers (12345) and full Change-IDs (I1234abc...) are both accepted