prr
is a tool that brings mailing list style code reviews to Github PRs.
This means offline reviews and inline comments, more or less.
To that end, prr
introduces a new workflow for reviewing PRs:
- Download the PR into a "review file" on your filesystem
- Mark up the review file using your favorite text editor
- Submit the review at your convenience
The tool was born of frustration from using the point-and-click editor text boxes on PRs. I happen to do a lot of code review and tabbing to and from the browser to cross reference code from the changes was driving me nuts.
-
Install
prr
:-
Option 1: Install rust toolchain (if you haven't already): https://rustup.rs/
$ cargo install prr
-
Option 2: Homebrew
$ brew install prr
-
-
Create a Github Personal Access Token (PAT) for
prr
:prr
will need this token so it can make GH API calls on your behalf. Create the token by going toSettings -> Developer settings -> Personal access tokens -> Generate new token
and give the tokenrepo
permissions.Keep the newly generated token handy for the next step.
-
Create a
prr
config file:$ mkdir -p ~/.config/prr $ cat << EOF > ~/.config/prr/config.toml [prr] token = "$YOUR_PAT_FROM_LAST_STEP" workdir = "/home/dxu/dev/review" EOF
where
$YOUR_PAT_FROM_LAST_STEP
is the PAT token from step 3 andworkdir
is the directory you wantprr
to place all your review files. -
Review your first PR:
Feel free to test
prr
out against my test repository, by the way.$ prr get danobi/prr-test-repo/6 /home/dxu/dev/review/danobi/prr-test-repo/6.prr $ vim /home/dxu/dev/review/danobi/prr-test-repo/6.prr $ prr submit danobi/prr-test-repo/6
For details on how to actually mark up the review file, see the next section titled "Features"
Description: PR-level review comment. You only get one of these per review.
Syntax: Non-whitespace, non-quoted text at the beginning of the review file.
Description: File-level comment.
Syntax: Non-whitespace, non-quoted text immediately following the diff --git
header
Description: Inline comment attached to a specific line of the diff.
Syntax: None-whitespace, non-quoted text on a newline immediately following a quoted non-header part of the diff.
Description: Like an inline comment, except it covers a span of lines.
Syntax: To start a span, insert one or more newlines immediately before a quoted, non-header part of the diff. To terminate a span, insert a inline comment.
Description: Meta-directives to give to prr
in review comment. Currently
only supports approving, requesting changes to, and commenting on a PR.
Syntax: @prr approve
, @prr reject
, or @prr comment
.
vim/
directory contains Vim plugin providing syntax coloring, filetype
detection and folding configuration for *.prr
files.
To install it modify &runtimepath
to add this directory or use plugin manager
of your choice to add this plugin.
Plugin 'danobi/prr', {'rtp': 'vim/'}
Copy the provided *.vim
files into their appropriate subdirectories in
~/.vim
.
With default Vim configuration all folds will be closed by default, so if you want them to be opened then you need to do one of these:
- Add
set foldlevel=9999
in your Vim config to open all folds by default - Add
set nofoldenable
to disable folding
Consult :h folding
for more details.
prr
supports various configuration options spread over one or more config
files. The global config file must be located at $XDG_CONFIG_HOME/prr/config.toml
.
This typically expands to $HOME/.config/prr/config.toml
.
prr
also supports local config files. Local config files must be named
.prr.toml
and will be searched for starting from the current working
directory up every parent directory until either the first match or the root
directory is hit. Local config files override values in the global config.
Table specific semantics are documented below.
The [prr]
table controls installation wide settings.
prr.token
: Personal authentication token (required)prr.workdir
: Directory to place review files (optional)prr.url
: URL to github API (optional)
If this table is specified in a local config file, it must be fully specified and will override the global config file.
The [local]
table contains configuration local to a directory and its
sub-directories.
local.repository
: A string in format of${ORG}/${REPO}
(optional)- If specified, you may omit the
${ORG}/${REPO}
from PR string arguments. For example, you may runprr get 6
instead ofprr get danobi/prr/6
.
- If specified, you may omit the
This table may not be specified in both a local config file and the global config file.