Metadata-Version: 2.4
Name: git-rvw
Version: 0.2.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`

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

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

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:

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

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

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

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

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

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

