@aaronshaf/ger

--- name: gerrit-workflow description: Work with Gerrit code reviews using the ger CLI tool. Use when reviewing changes, posting comments, managing patches, or interacting with Gerrit. Covers common workflows like fetching changes, viewing diffs, adding comments, voting, managing change status, cherry-picking, and tree worktrees. allowed-tools: Bash, Read, Write, Edit, Grep, Glob --- # 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:** ```bash ger show [change-id] ``` Displays metadata, diff, and all comments. Auto-detects from HEAD commit if omitted. **View specific diff:** ```bash ger diff [change-id] ger diff [change-id] --file src/api/client.ts # specific file ``` **View all comments:** ```bash ger comments [change-id] ger comments [change-id] --unresolved-only ``` **List changed files:** ```bash ger files [change-id] ger files [change-id] --json ``` **List reviewers:** ```bash ger reviewers [change-id] ger reviewers [change-id] --xml ``` ### Listing Changes **Your open changes:** ```bash ger mine ger list ``` **Changes needing your review (reviewer OR cc'd):** ```bash 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:** ```bash ger list --status merged ger list --reviewer # same as incoming ger list -n 10 --json ``` **Search with custom query:** ```bash ger search "owner:self is:wip" ger search "project:my-project status:open" -n 10 --xml ``` ### Posting Comments and Votes **Post a comment:** ```bash 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:** ```bash ger vote [change-id] Code-Review +2 ger vote [change-id] Verified -1 ``` ### Managing Changes **Abandon / restore:** ```bash ger abandon [change-id] -m "No longer needed" ger restore [change-id] ``` **Submit a change:** ```bash ger submit [change-id] ``` **Set WIP / Ready:** ```bash 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:** ```bash 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:** ```bash ger push ger push -b main -t my-feature -r alice@example.com --wip ``` Options: `-b`, `-t`, `-r`, `--cc`, `--wip`, `--ready`, `--hashtag`, `--private`, `--dry-run` ### Checkout and Cherry-Pick **Checkout a change locally:** ```bash ger checkout 12345 ger checkout 12345 --revision 3 # specific patchset ``` **Cherry-pick a change into current branch:** ```bash 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):** ```bash 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:** ```bash 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:** ```bash 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:** ```bash ger extract-url "build-summary-report" ger extract-url "build-summary-report" | tail -1 ``` **Canonical CI workflow:** ```bash 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):** ```bash 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 local cache of merged changes:** ```bash ger update ger update --since 2025-01-01 ``` **View recent failures summary:** ```bash ger failures ger failures --xml ``` ### Worktree (tree) Commands Manage git worktrees for reviewing changes in isolation. **Setup a worktree for a change:** ```bash 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:** ```bash ger trees ger trees --json ``` **Rebase a worktree (run from inside the worktree):** ```bash cd .ger/12345 ger tree rebase ger tree rebase --onto origin/main ger tree rebase --interactive # interactive rebase (-i) ``` **Remove a worktree:** ```bash ger tree cleanup 12345 ``` ### Groups and Reviewers **Add reviewers:** ```bash ger add-reviewer user@example.com -c 12345 ger add-reviewer --group project-reviewers -c 12345 ger add-reviewer --cc user@example.com -c 12345 ger add-reviewer --notify none user@example.com -c 12345 ``` **Remove reviewers:** ```bash ger remove-reviewer user@example.com -c 12345 ``` **List groups:** ```bash ger groups ger groups --pattern "^team-.*" ger groups --project canvas-lms ger groups --owned ``` **Show group details / members:** ```bash ger groups-show administrators ger groups-members project-reviewers ``` ### Configuration and Setup ```bash 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 ```bash # 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