Metadata-Version: 2.4
Name: git-rvw
Version: 0.3.0
Summary: Review GitLab MRs and GitHub PRs from the terminal
Author-email: Anders Roxell <anders.roxell@linaro.org>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: MIT License
License-File: LICENSE
Requires-Dist: black ; extra == "dev"
Requires-Dist: flake8 ; extra == "dev"
Requires-Dist: flit ; extra == "dev"
Requires-Dist: mypy ; extra == "dev"
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: pytest-cov ; extra == "dev"
Requires-Dist: tuxpkg ; extra == "dev"
Project-URL: Homepage, https://gitlab.com/aroxell/git-rvw
Project-URL: Issues, https://gitlab.com/aroxell/git-rvw/-/issues
Provides-Extra: dev

# 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

```shell
uv tool install git-rvw
```

Or from a checkout, `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:

```shell
alias rvw='git rvw'
```

rvw only uses the Python standard library, so nothing else 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`, or revdiff
  from https://github.com/umputun/revdiff if you want it instead of
  vim. revdiff is optional.

`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:

```shell
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. With `RVW_VIEWER=revdiff`
they start revdiff instead, see below.

`git rvw diff` opens one tab per changed file. You see a diff against
the base. Added and deleted files are shown alone. The tab line only
shows the file you are in, like `12/45  M  path`. Use `gt` and `gT` to
move, `12gt` to go to file 12 and `:tabs` to list 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:

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

### revdiff

```shell
git config --global rvw.viewer revdiff
```

revdiff is a diff viewer in the terminal, without vim. If you use nano
or emacs, use it for `git rvw diff` and `git rvw edit`. The notes stay
`RVW:` lines, so two reviewers can work on one MR, one with vim and one
with revdiff.

`git rvw diff` opens revdiff against the base of the review. Press `a`
on a line to write an annotation. When you quit with `q`, each one
becomes an `RVW:` line under its line. An annotation with more than
one line becomes one note with `RVW+` lines. `Q` quits without notes.
Notes that are in the files already stay as they are. The new notes
have no comment marker, so a file that needs one is not valid until
you add it by hand or `git rvw done` removes the notes.

An annotation on a deleted line, or on the whole file with `A`, has no
line to go under. rvw adds those to a file in the git directory of
the review, warns about each one and prints the path. Send them with
`git rvw issue -f`, or copy them to a line by hand. The file keeps
them all until `git rvw done`, so remove it when you have sent them.

`git rvw edit` opens revdiff with each `[ai]` note as an annotation on
its line. Keep it, change it, or delete it with `d`. When you quit with
`q`, a note that still has its annotation stays, with your text and
without `[ai]`. A note without one is deleted. New annotations become
new notes. Notes without `[ai]` are never changed. If you quit with
`Q`, nothing changes. To delete all `[ai]` notes, delete every
annotation and quit with `q`.

### Without vim or revdiff

You can also do the same work without `git rvw diff` and
`git rvw edit`. Read the diff against the base of the review:

```shell
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 and its `RVW+` lines.

`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:

```python
    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]`.

rvw sends the text as it is, and GitLab and GitHub show it as
Markdown. So put code in backticks:

```python
    if not m or not (ROOT / m[1]).is_file():
    # RVW: use `p.is_relative_to(ROOT)` here, `is_file()` alone lets "/etc/hosts" in
```

A long note can go on under it with `RVW+` lines, with the same
comment marker in front. rvw joins them with a space when it posts the
note, so you can wrap a comment at 80 characters and it is still one
paragraph on the web page. Lines in a ```` ``` ```` fence, empty lines
and list items keep their own line. So use a fence for a code block or
a GitLab suggestion. rvw drops one space after `RVW+` and keeps the
rest, so the code keeps its indent:

````python
    if not m or not (ROOT / m[1]).is_file():
    # RVW: Resolve the path first:
    # RVW+ ```python
    # RVW+ p = (ROOT / m[1]).resolve()
    # RVW+ ```
````

A blank line ends the note. rvw refuses an `RVW+` line that has no
note right above it.

## A review

```shell
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

```shell
git rvw prompt | claude -p --restricted --strict-mcp-config \
  --tools Read,Edit,Grep,Glob --permission-mode acceptEdits \
  --append-system-prompt-file ~/AGENTS.md
git rvw verify | claude -p --restricted --strict-mcp-config \
  --tools Read,Edit,Grep,Glob --permission-mode acceptEdits \
  --append-system-prompt-file ~/AGENTS.md
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 ask the agent to use the writing style from its own
instructions, so rvw has nothing personal in it. Give yours with
`--append-system-prompt-file`, and change `~/AGENTS.md` to where it is.

The default prompt asks for bugs and skips taste and style. Do you want
another kind of review, like one for code that could be simpler? Write
what the agent should look for in a file and give it with
`git rvw prompt -f FILE`. The file replaces the part of the prompt
about what to look for. The rules for the notes stay, so
`git rvw verify` and `git rvw post` work the same.

Do not trust the review worktree. The MR author wrote it. Without
`--restricted`, claude loads `.claude/settings.json` and CLAUDE.md
from the worktree, and `-p` skips the trust dialog. So a hook in the
MR runs as you, with your glab, gh, ssh and gpg access.

`--restricted` ignores the settings files and CLAUDE.md, and the file
tools can only reach the worktree. It skips your own CLAUDE.md too.
That is why AGENTS.md comes in with `--append-system-prompt-file`.
`--tools` leaves out Bash and the web tools.

rvw runs git in the review worktree too. The MR can add a directory
that looks like a bare repo with any command as `core.fsmonitor` in
its `config`, and if you run rvw in that directory, git runs the
command. So rvw sets `safe.bareRepository=explicit` for every git
command it starts.

Is your clone a bare repo with worktrees? Run rvw in a worktree, since
git now refuses the bare repo itself.

The diff can still try to trick the agent. What can it do then? It can
only edit files in the worktree (and rvw refuses to post when a line
that is not a note changed).

Does the agent need to read docs that are not in the repo, like a
spec? Put copies of them in a directory of their own, and give the
agent read access to it:

```shell
git rvw prompt | claude -p --restricted --strict-mcp-config \
  --tools Read,Edit,Grep,Glob --permission-mode acceptEdits \
  --add-dir ~/docs --disallowedTools "Edit(/$HOME/docs/**)" \
  --append-system-prompt-file ~/AGENTS.md
```

`--add-dir` lets the file tools reach `~/docs`, and the
`--disallowedTools` rule takes away Edit there. Note the `/` in front
of `$HOME`. A rule with an absolute path starts with `//`.

Do not add a directory that has other worktrees or repos in it. The
agent can edit them.

## Issues

```shell
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:

```shell
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:

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

## Replies

```shell
git rvw reply            # list the open issues and ask for a number
git rvw reply 219
```

`git rvw reply` writes the issue to a file and opens it in `$EDITOR`.
The file has the description and then each comment, with a header
line above each one:

```
# #219 Deploy signed releases instead of building from source

## description by rasgra

The schema has no version field.
RVW: Agreed, I'll add one in FP-CR-007.
```

Write an `RVW:` line under each line you reply to, and `RVW+` lines
for a long note, the same as in a review. When you close the editor,
rvw shows the comments it will send and asks before it posts. Each
note quotes the line above it:

```
> The schema has no version field.

Agreed, I'll add one in FP-CR-007.
```

On GitLab, notes on the description become a new comment, and notes on
a comment become a reply in its thread. GitHub has no threads on
issues, so all notes become one new comment. A part that replies to a
comment starts with a link to it.

If you say no, the file stays, and `git rvw reply 219` opens it again.
rvw refuses to post when a line that is not a note changed, and when
the description or a quoted comment changed on the web page since rvw
fetched it. `git rvw reply 219 --fresh` fetches the issue again, and
the old file is kept as `issue.md.old`.

The issue text comes from other people. A quoted `@name` notifies that
person again, so rvw warns about it. GitLab internal notes are left
out, and rvw does not reply to a confidential issue.

An AI agent can write draft replies too. `--prompt` writes the file
and prints the instructions, and `--dir` prints the directory the file
is in. Run the agent there, and give it your checkout to read:

```shell
d=$(git rvw reply 219 --dir)
git rvw reply 219 --prompt | (cd "$d" && claude -p --restricted \
  --strict-mcp-config --tools Read,Edit,Grep,Glob \
  --permission-mode acceptEdits \
  --add-dir ~/src/ot_soc_portal \
  --disallowedTools "Edit(/$HOME/src/ot_soc_portal/**)" \
  --append-system-prompt-file ~/AGENTS.md)
git rvw reply 219 --verify | (cd "$d" && claude -p --restricted \
  --strict-mcp-config --tools Read,Edit,Grep,Glob \
  --permission-mode acceptEdits \
  --add-dir ~/src/ot_soc_portal \
  --disallowedTools "Edit(/$HOME/src/ot_soc_portal/**)" \
  --append-system-prompt-file ~/AGENTS.md)
git rvw reply 219        # keep or delete each [ai] note, then post
```

The agent writes `RVW: [ai]` lines. `--verify` asks another agent to
check them against the issue and the code, and to delete the ones it
can not prove. Keep a note by removing `[ai] `, or delete it. rvw
refuses to post while a note still has `[ai]`.

The directory is under `$XDG_STATE_HOME/git-rvw/reply`, or
`~/.local/state/git-rvw/reply`, and it has only the reply file. rvw
keeps the rest one level up, where the agent can not edit it. Do not
run the agent in your checkout. With `--restricted` it can edit the
directory it runs in, and in a checkout that also means `.git`.

## 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.
- `RVW_VIEWER` is the tool for `git rvw diff` and `git rvw edit`:
  `vim`, the default, or `revdiff`.
- `RVW_PROMPT_FILE` is the file for `git rvw prompt` when there is no
  `-f`, see above. The file must be an absolute path or start with
  `~/`. A relative path would point into the review worktree, and
  the MR author wrote that.
- `EDITOR` is the editor for `git rvw issue`.

You can also set the first four with git config, so you do not need
an export:

```shell
git config --global rvw.viewer revdiff
git config --global rvw.check "aspell list"
git config rvw.remote upstream
git config --global rvw.prompt-file ~/.config/rvw/simplify.txt
```

The environment wins over git config. An empty variable, like
`RVW_CHECK=`, turns off the git config value for one run.

## Bugs and changes

Report bugs at https://gitlab.com/aroxell/git-rvw/-/issues, with the
output of `git rvw version`. CONTRIBUTING.md says what to put in a bug
report, and how to set up git-rvw if you want to work on it.

