git-review
==========

A git command for submitting branches to Gerrit

git-review is a tool that helps submitting git branches to gerrit for
review.

Setup
-----

By default, git-review will look for a remote named 'gerrit' for working
with Gerrit. If the remote exists, git-review will submit the current
branch to HEAD:refs/for/master at that remote.

If the Gerrit remote does not exist, git-review looks for a file
called .gitreview at the root of the repository with information about
the gerrit remote.  Assuming that file is present, git-review should
be able to automatically configure your repository the first time it
is run.

The name of the Gerrit remote is configurable; see the configuration
section below.

Usage
-----

Hack on some code, then::

    git review

If you want to submit that code to a branch other than "master", then::

    git review branchname

If you want to submit to a different remote::

    git review -r my-remote

If you want to supply a review topic::

    git review -t topic/awesome-feature

If you want to submit a branch for review and then remove the local branch::

    git review -f

If you want to skip the automatic "git rebase -i" step::

    git review -R

If you want to download change 781 from gerrit to review it::

    git review -d 781

If you want to download patchset 4 for change 781 from gerrit to review it::

    git review -d 781,4

If you want to compare patchset 4 with patchset 10 of change 781 from gerrit::

    git review -m 781,4-10

If you just want to do the commit message and remote setup steps::

    git review -s

.gitreview file format
----------------------

Example .gitreview file (used to upload for git-review itself)::

    [gerrit]
    host=review.openstack.org
    port=29418
    project=openstack-infra/git-review.git
    defaultbranch=master

Required values: host, project

Optional values: port (default: 29418), defaultbranch (default: master),
defaultremote (default: gerrit).

**Notes**

* Username is not required because it is requested on first run

* Unlike git config files, there cannot be any whitespace before the name
  of the variable.

* Upon first run, git-review will create a remote for working with Gerrit,
  if it does not already exist. By default, the remote name is 'gerrit',
  but this can be overridden with the 'defaultremote' configuration
  option.

* You can specify different values to be used as defaults in
  ~/.config/git-review/git-review.conf or /etc/git-review/git-review.conf.

Hooks
-----

git-review has a custom hook mechanism to run a script before certain
actions. This is done in the same spirit as the classic hooks in git.

There are two types of hooks, a global one which is stored in
~/.config/git-review/hooks/ and one local to the repository stored in
.git/hooks/ with the other git hook scripts.

**The script needs be executable before getting executed**

The name of the script is $action-review where action can be
:

* pre - run at first before doing anything.

* post - run at the end after the review was sent.

* draft - run when in draft mode.

if the script returns with an exit status different than zero,
git-review will exit with the a custom shell exit code 71.

Installation
------------

Install with pip install git-review

For installation from source simply add git-review to your $PATH
after installing the dependencies listed in requirements.txt

Running tests
-------------

Running tests for git-review means running a local copy of Gerrit to
check that git-review interacts correctly with it. This requires the
following
:

* a Java Runtime Environment on the machine to run tests on

* Internet access to download the gerrit.war file, or a locally
  cached copy (it needs to be located in a .gerrit directory at the
  top level of the git-review project)

To run git-review integration tests the following commands may by run::

    tox -e py27
    tox -e py26
    tox -e py32
    tox -e py33

depending on what Python interpreter would you like to use.

Contributing
------------

To get the latest code, see: https://git.openstack.org/cgit/openstack-infra/git-review

Bugs are handled at: https://launchpad.net/git-review

There is a mailing list at: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra

Code reviews, as you might expect, are handled by gerrit at: https://review.openstack.org

Use ``git review`` to submit patches (after creating a gerrit account that links to your launchpad account). Example::

    # Do your commits
    git review
    # Enter your username if prompted