@aaronshaf/ger 3.0.2 → 4.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronshaf/ger",
-  "version": "3.0.2",
+  "version": "4.0.1",
   "description": "Gerrit CLI and SDK - A modern CLI tool and TypeScript SDK for Gerrit Code Review, built with Effect-TS",
   "keywords": [
     "gerrit",

package/skills/gerrit-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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, and managing change status.
+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
 ---
 
@@ -12,6 +12,15 @@ This skill helps you work effectively with Gerrit code reviews using the `ger` C
 
 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
@@ -20,228 +29,306 @@ The `ger` CLI tool must be installed and accessible in your PATH. It's available
 ```bash
 ger show [change-id]
 ```
-Displays metadata, diff, and all comments for a change. If no change-id is provided, uses the current branch.
+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
 ```
-Get diffs with various formatting options.
 
 **View all comments:**
 ```bash
 ger comments [change-id]
+ger comments [change-id] --unresolved-only
 ```
-View all comments on a change with context.
 
-### Managing Changes
+**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
+```
 
-**View your changes:**
+### Listing Changes
+
+**Your open changes:**
 ```bash
 ger mine
+ger list
 ```
-List all changes owned by you.
 
-**View incoming changes (review requests):**
+**Changes needing your review (reviewer OR cc'd):**
 ```bash
 ger incoming
+ger team
 ```
-List changes that need your review.
-
-**View open changes:**
+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 open
+ger list --status merged
+ger list --reviewer          # same as incoming
+ger list -n 10 --json
 ```
-List all open changes in the project.
 
-**Abandon a change:**
+**Search with custom query:**
 ```bash
-ger abandon [change-id]
+ger search "owner:self is:wip"
+ger search "project:my-project status:open" -n 10 --xml
 ```
-Mark a change as abandoned.
 
-### Pushing Changes
+### Posting Comments and Votes
 
-**Push changes to Gerrit:**
+**Post a comment:**
 ```bash
-ger push
+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"
 ```
 
-**Push with options:**
+**Vote on a change:**
 ```bash
-# Push to specific branch
-ger push -b main
-
-# Push with topic
-ger push -t my-feature
+ger vote [change-id] Code-Review +2
+ger vote [change-id] Verified -1
+```
 
-# Push with reviewers
-ger push -r alice@example.com -r bob@example.com
+### Managing Changes
 
-# Push as work-in-progress (WIP)
-ger push --wip
+**Abandon / restore:**
+```bash
+ger abandon [change-id] -m "No longer needed"
+ger restore [change-id]
+```
 
-# Mark change as ready for review
-ger push --ready
+**Submit a change:**
+```bash
+ger submit [change-id]
+```
 
-# Combine options
-ger push -b main -t feature-auth -r alice@example.com --wip
+**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"
 ```
 
-**WIP Workflow (Optional):**
-Work-in-progress changes are useful when you want to push changes that aren't ready for review:
+**Topic:**
 ```bash
-# Push initial work as WIP (won't notify reviewers)
-ger push --wip
+ger topic [change-id]            # get current topic
+ger topic [change-id] my-topic   # set topic
+ger topic [change-id] --delete   # delete topic
+```
 
-# Continue updating (stays WIP)
-ger push --wip
+### Pushing Changes
 
-# Mark ready when done (will notify reviewers)
-ger push --ready
+**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`
 
-**Search for WIP changes:**
-```bash
-# Find all WIP changes
-ger search "is:wip"
+### Checkout and Cherry-Pick
 
-# Your WIP changes
-ger search "owner:self is:wip"
+**Checkout a change locally:**
+```bash
+ger checkout 12345
+ger checkout 12345 --revision 3   # specific patchset
 ```
 
-### Commenting on Changes
-
-**Post a comment:**
+**Cherry-pick a change into current branch:**
 ```bash
-ger comment [change-id] -m "Your comment"
+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
 ```
 
-**Post comment with piped input (useful for AI integration):**
+### Rebase
+
+**Rebase a change on Gerrit (server-side):**
 ```bash
-echo "Review feedback" | ger comment [change-id]
+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 inline comments:**
+**Post a CI retrigger comment:**
 ```bash
-ger comment [change-id] --file path/to/file --line 42 -m "Comment on specific line"
+ger retrigger [change-id]
 ```
+Auto-detects from HEAD. Saves the retrigger comment to config on first use (or configure via `ger setup`).
 
-## Common Workflows
+### Build Status
 
-### Reviewing a Change
+**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)
+```
 
-1. **Fetch the change details:**
-   ```bash
-   ger show [change-id]
-   ```
+**Extract build URLs:**
+```bash
+ger extract-url "build-summary-report"
+ger extract-url "build-summary-report" | tail -1
+```
 
-2. **Review the diff:**
-   ```bash
-   ger diff [change-id]
-   ```
+**Canonical CI workflow:**
+```bash
+ger build-status --watch --interval 20 --timeout 1800 && \
+  ger extract-url "build-summary-report" | tail -1 | jk failures --smart --xml
+```
 
-3. **Post your review:**
-   ```bash
-   ger comment [change-id] -m "LGTM! Great work on the refactoring."
-   ```
+### Analytics
 
-### AI-Assisted Code Review
+**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.
 
-Use the ger CLI with AI tools for enhanced code review:
+**Update local cache of merged changes:**
+```bash
+ger update
+ger update --since 2025-01-01
+```
 
-1. **Get the diff:**
-   ```bash
-   ger diff [change-id] > /tmp/review.diff
-   ```
+**View recent failures summary:**
+```bash
+ger failures
+ger failures --xml
+```
 
-2. **Analyze with AI and post comments:**
-   ```bash
-   # AI analyzes the diff and generates feedback
-   ai-tool analyze /tmp/review.diff | ger comment [change-id]
-   ```
+### Worktree (tree) Commands
 
-### Work-in-Progress (WIP) Workflow (Optional)
+Manage git worktrees for reviewing changes in isolation.
 
-If you need to push changes that aren't ready for review, you can use the WIP flag:
+**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>/`.
 
-1. **Start with WIP:**
-   ```bash
-   # Make changes
-   git add .
-   git commit -m "feat: add new feature"
+**List ger-managed worktrees:**
+```bash
+ger trees
+ger trees --json
+```
 
-   # Push as WIP (won't notify reviewers)
-   ger push --wip
-   ```
+**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)
+```
 
-2. **Continue iterating:**
-   ```bash
-   # Make more changes
-   git add .
-   git commit --amend
+**Remove a worktree:**
+```bash
+ger tree cleanup 12345
+```
 
-   # Push updates (stays WIP)
-   ger push --wip
-   ```
+### Groups and Reviewers
 
-3. **Mark ready when complete:**
-   ```bash
-   # Final polish
-   git add .
-   git commit --amend
+**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
+```
 
-   # Mark ready for review (notifies reviewers)
-   ger push --ready
-   ```
+**Remove reviewers:**
+```bash
+ger remove-reviewer user@example.com -c 12345
+```
 
-4. **Find WIP changes:**
-   ```bash
-   # List all your WIP changes
-   ger search "owner:self is:wip"
-   ```
+**List groups:**
+```bash
+ger groups
+ger groups --pattern "^team-.*"
+ger groups --project canvas-lms
+ger groups --owned
+```
 
-## Best Practices
+**Show group details / members:**
+```bash
+ger groups-show administrators
+ger groups-members project-reviewers
+```
 
-### When Reviewing Code
+### Configuration and Setup
 
-1. **Always read the full change context** using `ger show` before commenting
-2. **Check all comments** with `ger comments` to avoid duplicate feedback
-3. **Be specific** in your comments - reference file paths and line numbers
-4. **Use constructive language** - focus on improvements, not criticism
+```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
+```
 
-### When Managing Changes
+## Auto-Detection
 
-1. **Keep changes focused** - one logical change per Gerrit change
-2. **Respond to comments promptly** - address reviewer feedback
-3. **Use meaningful commit messages** - follow conventional commit format
-4. **Test before submitting** - ensure builds pass before requesting review
-5. **Consider WIP flag (optional)** - use `--wip` for changes not ready for review
+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`
 
-## Troubleshooting
+## Common LLM Workflows
 
-**Change not found:**
-- Ensure you're in the correct repository
-- Verify the change-id is correct
-- Check your Gerrit authentication
+```bash
+# Review a change
+ger show <id> --xml
+ger diff <id> --xml
+ger comments <id> --xml
 
-**Permission denied:**
-- Verify your Gerrit credentials are configured
-- Check you have access to the project
-- Ensure you're added as a reviewer (for private changes)
+# Post a review
+ger comment <id> -m "..."
+ger vote <id> Code-Review +1
 
-**Build failures:**
-- Use `ger build-status` to monitor build progress
-- Extract build URLs with `ger extract-url`
-- Check build logs for detailed failure information
+# Manage changes
+ger push
+ger checkout <id>
+ger abandon <id>
+ger submit <id>
 
-## Additional Resources
+# WIP toggle
+ger set-wip <id>
+ger set-ready <id> -m "message"
 
-For more detailed information, see [reference.md](reference.md) for complete command documentation and [examples.md](examples.md) for real-world usage examples.
+# Check CI
+ger build-status <id> --exit-status
+```
 
 ## Notes
 
-- Commands assume you're running from within a Gerrit repository
-- Most commands accept an optional change-id; if omitted, they use the current branch
+- 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
-- All output supports internationalization via i18next
+- `--xml` is preferred over `--json` for LLM/AI consumption (easier to parse)
+- Numeric change numbers (12345) and full Change-IDs (I1234abc...) are both accepted