git-rvw

git-rvw, or rvw for short, reviews GitLab merge requests and GitHub pull requests from the terminal. You read the diff in vim and write each comment as a line under the code it is about. rvw sends them as inline draft comments. You publish them when you are happy.

An AI agent can write a draft review too. Its comments are tagged [ai], and rvw does not send them before you have kept or deleted each one.

Install

uv tool install -e .

This installs the git-rvw command. git runs it as git rvw, so all commands below start with git rvw. If you want it shorter:

alias rvw='git rvw'

rvw only uses the Python standard library. Nothing comes from PyPI. The tools below are not Python packages, and you have to install them yourself:

• git for all commands
• glab 1.124.0 or newer for an MR on GitLab. Debian has 1.53.0, which is too old, so take a release from https://gitlab.com/gitlab-org/cli/-/releases
• gh and the gh pr-review extension for a PR on GitHub. gh is at https://cli.github.com, and the extension is installed with gh extension install agynio/gh-pr-review
• nvim or vim for git rvw diff and git rvw edit

git rvw issue needs glab or gh, depending on the remote.

Log in once. Over SSH, use --device for glab, because the browser login waits for a callback on localhost:

glab auth login --hostname gitlab.com --device --git-protocol ssh
gh auth login --web --git-protocol ssh

rvw checks for the tools when a command needs them and tells you what is missing.

Editors

You can write the notes in any editor. Only git rvw diff and git rvw edit start vim, and they use nvim if you have it.

git rvw diff opens one tab per changed file. A changed file is a diff against the base, and an added or deleted file is shown alone. The tab line only shows the file you are in, like 12/45 M path. Move with gt and gT. 12gt goes to file 12 and :tabs lists them all.

git rvw edit puts the notes in the quickfix list. <leader>a keeps a note. <leader>d deletes it.

If your vimrc opens a window on VimEnter, that window takes the cursor from the file. NERDTree with if argc() == 0 does this, because -q and -S give no file arguments. Also check that the buffer has no name:

autocmd VimEnter * if argc() == 0 && !exists("s:std_in") && bufname('%') == '' | NERDTree | endif

With nano or emacs you do the same work without git rvw diff and git rvw edit. Read the diff against the base of the review:

git diff $(sed -n 's/^base=//p' "$(git rev-parse --git-path rvw)")

Then use git rvw list to find the [ai] notes. To keep a note, remove [ai] from it. To drop it, delete the line.

git rvw issue opens the text in $EDITOR, or in vim when it is not set. $EDITOR must wait until you close the file, so use emacsclient and not emacsclient -n. Otherwise git rvw issue goes on before you have edited the text.

Notes

A note is a line with RVW: under the line it is about, like on the web page. Blank lines between them are fine. If the file needs a comment marker to stay valid, put it first:

    for i in range(1, len(items)):
    # RVW: this skips items[0], start at 0
        check(items[i])

RVW re ID: is a reply to the thread ID. git rvw threads lists the ids.

Each RVW: line is one comment. rvw refuses to post when a line that is not a note changed, when a note is outside the diff and when a note still has [ai].

A review

git rvw start https://gitlab.com/group/project/-/merge_requests/1
cd ../project-rvw-1
git rvw diff            # read it and add RVW: lines
git rvw list            # path:line: comment
git rvw post            # draft comments, only you see them
git rvw publish         # or git rvw discard
git rvw done            # removes the review worktree

Use git rvw here in a worktree that is already at the MR head, and git rvw local [REF] to review a branch that has no MR or PR yet. The default REF is the default branch of the remote.

With an AI agent

git rvw prompt | claude -p --permission-mode acceptEdits
git rvw verify | claude -p --permission-mode acceptEdits
git rvw edit            # <leader>a keeps a note, <leader>d deletes it

git rvw prompt prints instructions and the diff. The agent writes its comments as RVW: [ai] lines. git rvw verify asks an agent to check those comments again and to delete the ones it can not prove. The instructions point the agent at its own AGENTS.md for the writing style, so rvw has nothing personal in it.

Issues

git rvw issue "Small things in the spec"
git rvw issue -f notes.md "Small things in the spec"

The issue text opens in $EDITOR before anything is sent. In a review with notes the text starts from the notes. With -f it is your own file, and rvw never removes it. Otherwise you get an empty file.

-t TYPE makes something other than a plain issue:

git rvw issue -t task "Fix the schema"

On GitLab it creates a work item with glab work-items create, so TYPE is one of the glab types, like task or epic. glab says the command is experimental. On GitHub it sets the issue type, like Task or Bug, with the GitHub API. The types come from the organization. GitHub drops the type without an error if you have no push access, so rvw checks the new issue and warns when the type is missing.

To see which types the project has:

git rvw issue -t list

On GitLab rvw asks the project, so you only get the work item types it really has. On GitHub you get the issue types of the organization. User repositories have none.

Settings

• RVW_REMOTE is the remote to use, default origin.
• RVW_CHECK is a command that gets each note on stdin. Every line it prints is shown with the note, for example a spell or style check.
• EDITOR is the editor for git rvw issue.

Development

uv run --extra dev make        # tests with coverage, mypy, black and flake8
uv run --extra dev pytest      # only the tests

uv makes a venv in .venv with the dev extra from pyproject.toml. That has the test and style tools and tuxpkg, which the Makefile includes.