Command Line Interface

hg-review provides a command line interface. Except for initializing the review data, starting the web ui, and possibly some scripting, you’ll probably want to use the web interface for most tasks.

When you enable the hg-review extension Mercurial will gain a new command: review. This command on its own will display review data for a changeset, but it also has several subcommands detailed below.

You can always get help on a given topic right from the command line with hg help review or hg help review-topic.

review

View code review data for a changeset. Usage:

hg review [-r REV] [-U CONTEXT] [--quiet] [FILE]

Diffs of all changed files will be shown with comments inline.

The line numbers printed are the ones that should be used to add line-level comments.

Options:

--unified VALUE

The number of lines of context to show for diffs in this changeset (default: 5).

--rev VALUE

The revision to show (default: .).

--quiet

Do not show diffs – only show review-level comments and signoffs (default: false).

--verbose

Show the short identifier of each comment and signoff, mainly for use with the edit subcommand (default: false).

--debug

Show the full identifier of each comment and signoff, mainly for use with the edit subcommand (default: false).

--init

Initialize code review for a repository. Usage:

hg review --init --remote-path PATH

When run for the first time in a project, it will do two things:

• Create a new repository to hold the review data at .hg/review/.
• Create and hg add a .hgreview file in the current repository. You will need to commit this file yourself with: hg commmit .hgreview -m 'initialize code review data'

The --remote-path option is required and specifies the path where the canonical code review data for this project will live. This is the path that will be cloned when someone else runs hg review --init on the project.

Options:

--remote-path VALUE

The URL to the public code review data repository.

--comment

Add a code review comment for a changeset. Usage:

hg review --comment [-m MESSAGE] [--mdown] [-r REV] [-l LINES] [FILE]

If no files are given the comment will be attached to the changeset as a whole.

If one or more files are given but no lines are given, the comment will be attached to each file as a whole.

If a file is given and lines are given the comment will be attached to those specific lines. Lines should be specified as a comma-separated list of line numbers (as numbered in the output of “hg review”), such as 3 or 2,3.

Options:

--rev VALUE

The revision to add a comment to (default: .).

--lines VALUE

Comment on the given lines (specified as a comma-separated list of line numbers) of the file (default: None).

--message VALUE

Use VALUE as the comment instead of opening an editor (default: None (i.e. “open an editor”)).

--mdown

Use Markdown to format the comment (default: False).

--signoff

Add a code review signoff for a changeset. Usage:

hg review --signoff [-m MESSAGE] [--mdown] [--yes | --no] [-r REV]

The --yes and --no options can be used to indicate whether you think the changeset is “good” or “bad”.

It’s up to the collaborators of each individual project to decide exactly what that means. If neither option is given the signoff will be marked as “neutral”.

Options:

--rev VALUE

The revision to sign off on (default: .).

--yes

Sign off as “yes” for the changeset (default: False (i.e. “neutral”)).

--no

Sign off as “no” for the changeset (default: False (i.e. “neutral”)).

--message VALUE

Use VALUE as the signoff message instead of opening an editor (default: None (i.e. “open an editor”)).

--mdown

Use Markdown to format the signoff message (default: False).

--edit

Edit a comment or signoff. Usage:

hg review --edit IDENTIFIER [--yes | --no] [-m MESSAGE] [-l LINES] [--mdown] [FILE]

Edit the comment or changeset with the given identifier.

You can find the identifier of the item you would like to edit by running hg review --verbose to display identifiers.

Any other options given (such as --message, --yes or filenames) will replace the content of the item you edit.

--message VALUE

Replace the comment or signoff message with VALUE (default: None (i.e. “open an editor”)).

--mdown

Use Markdown to format the comment or signoff message (default: False (i.e. “Use the same formatting the item already has)).

--lines

The line(s) of the file to comment on (default: None (i.e. “use the same line the comment already has)). Returns an error if you’re editing a signoff or a review-level comment.

--yes

Change the signoff to state the the changeset is “good” (default: False). Returns an error if you are not editing a signoff.

--no

Change the signoff to state the the changeset is “bad” (default: False). Returns an error if you are not editing a signoff.

--check

Check the review status of a changeset. Usage:

hg review --check [-r REV] [--no-nos] [--yeses NUM] [--seen]

Check that the given changeset “passes” the given tests of review status. If no tests are given an error is returned.

Tests are checked in the following order:

• --no-nos
• --yeses
• --seen

If any tests fail the command returns a status of 1 with a message describing the failure on stderr, otherwise it returns 0 and prints nothing.

--rev VALUE

The revision to check (default: .).

--no-nos

Ensure this revision does not have any signoffs of “no” (default: False (i.e. “Don’t perform this check”)).

--yeses VALUE

Ensure this revision has at least VALUE signoffs of “yes” (default: None (i.e. “Don’t perform this check”).

--seen

Ensure this revision has at least one comment or signoff (default: False (i.e. “Don’t perform this check”)).

--web

Start the web interface. Usage:

hg review --web [--read-only] [--allow-anon] [--address ADDRESS] [--port PORT]

Visit http://localhost:8080/ (replace the port number if you specified a different port) in a modern browser of your choice to use the web interface.

Use Ctrl+C to stop the interface.

Options:

--read-only

Make the web interface read-only; disallowing comments, signoffs, pushes and pulls (default: False).

--allow-anon

Allow anonymous comments on the web interface and set the username for comments to an anonymous username (default: False (i.e. allow comments and use your Mercurial username)).

--address VALUE

Run the web interface on the specified address (default: 127.0.0.1).

--port VALUE

Run the web interface on the specified port (default: 8080).