docs/cli.rst @ 8308374acdb2 initial-docs

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 :doc:`web interface </webui>` 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``.

.. _c-review:

``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 :ref:`edit <c-edit>` subcommand (default: ``false``).

``--debug``
    Show the full identifier of each comment and signoff, mainly for use with
    the :ref:`edit <c-edit>` subcommand (default: ``false``).

.. _c-init:

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


.. _c-comment:

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


.. _c-signoff:

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


.. _c-edit:

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


.. _c-check:

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


.. _c-web:

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