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.
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.

Core Commands

Viewing Changes

Show comprehensive change information:

ger show [change-id]

Displays metadata, diff, and all comments for a change. If no change-id is provided, uses the current branch.

View specific diff:

ger diff [change-id]

Get diffs with various formatting options.

View all comments:

ger comments [change-id]

View all comments on a change with context.

Managing Changes

View your changes:

ger mine

List all changes owned by you.

View incoming changes (review requests):

ger incoming

List changes that need your review.

View open changes:

ger open

List all open changes in the project.

Abandon a change:

ger abandon [change-id]

Mark a change as abandoned.

Pushing Changes

Push changes to Gerrit:

ger push

Push with options:

# Push to specific branch
ger push -b main

# Push with topic
ger push -t my-feature

# Push with reviewers
ger push -r [email protected] -r [email protected]

# Push as work-in-progress (WIP)
ger push --wip

# Mark change as ready for review
ger push --ready

# Combine options
ger push -b main -t feature-auth -r [email protected] --wip

WIP Workflow (Optional):
Work-in-progress changes are useful when you want to push changes that aren't ready for review:

# Push initial work as WIP (won't notify reviewers)
ger push --wip

# Continue updating (stays WIP)
ger push --wip

# Mark ready when done (will notify reviewers)
ger push --ready

Search for WIP changes:

# Find all WIP changes
ger search "is:wip"

# Your WIP changes
ger search "owner:self is:wip"

Commenting on Changes

Post a comment:

ger comment [change-id] -m "Your comment"

Post comment with piped input (useful for AI integration):

echo "Review feedback" | ger comment [change-id]

Post inline comments:

ger comment [change-id] --file path/to/file --line 42 -m "Comment on specific line"

Common Workflows

Reviewing a Change

1. Fetch the change details:
   bash ger show [change-id]

2. Review the diff:
   bash ger diff [change-id]

3. Post your review:
   bash ger comment [change-id] -m "LGTM! Great work on the refactoring."

AI-Assisted Code Review

Use the ger CLI with AI tools for enhanced code review:

1. Get the diff:
   bash ger diff [change-id] > /tmp/review.diff

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]

Work-in-Progress (WIP) Workflow (Optional)

If you need to push changes that aren't ready for review, you can use the WIP flag:

1. Start with WIP:
   ```bash
   # Make changes
   git add .
   git commit -m "feat: add new feature"

# Push as WIP (won't notify reviewers)
ger push --wip
```

1. Continue iterating:
   ```bash
   # Make more changes
   git add .
   git commit --amend

# Push updates (stays WIP)
ger push --wip
```

1. Mark ready when complete:
   ```bash
   # Final polish
   git add .
   git commit --amend

# Mark ready for review (notifies reviewers)
ger push --ready
```

1. Find WIP changes:
   bash # List all your WIP changes ger search "owner:self is:wip"

Best Practices

When Reviewing Code

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

When Managing Changes

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

Troubleshooting

Change not found:
- Ensure you're in the correct repository
- Verify the change-id is correct
- Check your Gerrit authentication

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)

Build failures:
- Use ger build-status to monitor build progress
- Extract build URLs with ger extract-url
- Check build logs for detailed failure information

Additional Resources

For more detailed information, see reference.md for complete command documentation and examples.md for real-world usage examples.

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
• The tool uses local SQLite caching for offline-first functionality
• All output supports internationalization via i18next