Gerrit/git-review

git-review is a command-line tool for Git / Gerrit to submit a change or to fetch an existing one.

Note that Wikimedia Gerrit requires git-review version 1.27 or later.

The upstream project is led by OpenStack. Is not to be confused with the unrelated Facebook project.

Installation

See also: Gerrit tutorial

After installing git (1, 2), creating a gerrit user account, setting up an ssh key (3, 4), and cloning a project repository (or example), you are ready to install git-review, a tool for working with Gerrit repositories so you don't have to remember some commands. Follow the instructions below for your operating system, and don't forget to configure it up afterwards!

Linux

Debian/Ubuntu/Mint

Users of Debian or related distributions (e.g., Ubuntu, Mint) on a shared host usually do not have root access. If you cannot get your hosting administrator to install git-review for you, you can try to install it locally. Go to the appropriate section below

Having root access

You can do

sudo apt-get install git-review

or

sudo apt-get install python-pip
sudo easy_install pip
sudo pip install git-review

If you do not have easy_install set up, try

sudo apt-get install python-setuptools

If you don't have apt-get but have python installed, you can use this; see far below for special OS X instructions.

sudo easy_install pip
sudo pip install git-review

If you have Ubuntu 20.04, try

sudo apt-get install python3-pip
sudo pip3 install git-review

Then run:

git review -s

in your cloned copy to setup to work with Gerrit. It will probably ask you for your commit username. Then it will automatically install the commit-msg hook.

If you were set-up before and have Ubuntu 18.04, try upgrade git-review since the packaged version of 1.26.0 will not work.

Without root access

If you are on a shared host and your system does not have git-review, you can install it locally in your user directory.

virtualenv --python=/usr/bin/python2.6 virtualenv
virtualenv/bin/pip install git-review

If this is your first local install, or you have not done that already, extend your PATH to include the local binaries. There are two ways to do that. The more conservative way

PATH=$PATH:~/virtualenv/bin/

lets the system look through all binary directories first, and only looks into the local binary directory if a command was not found elsewhere. If you want software installed locally in your home directory to override system programs, you need the inverse the sort order.

PATH=~/virtualenv/bin/:$PATH

You probably did that earlier already. You may want to add either command to your login sequence to have it run automatically.

If you do not want to alter your PATH variable, you don't have to. In this case, you cannot use the command git review but must remember to use ~/virtualenv/bin/git-review instead.

Finally run:

git review -s

or

~/virtualenv/bin/git-review -s

respectively, in your cloned copy to set it up to work with Gerrit. It will probably ask you for your commit username. Then it will automatically install the commit-msg hook.

Fedora≤21/CentOS

sudo yum install git-review

If, while using git-review, you see ImportError: No module named requests, you'll need to install python-requests:

sudo yum install python-requests

You may find that yum cannot find the git-review package -- in this case you can enable the EPEL repository and try again.

Fedora≥22

sudo dnf install git-review

OpenSUSE

Install (YaST) the python-setuptools, then

easy_install pip
pip install git-review

As of OpenSUSE 13.1, git-review is included in the main repository, so you can use

sudo zypper in git-review

Gentoo

emerge dev-python/git-review

Arch Linux

Arch does not have git-review in the repositories, but does contain a PKGBUILD in the AUR:

git clone https://aur.archlinux.org/git-review.git
cd git-review
makepkg -s
sudo pacman -U <resultingpackage>

NixOS (or any Linux with Nix installed)

git-review is available as a package in the stable and unstable branches of nixpkgs. Try it by starting a shell with git-review available:

Stable

nix run -f channel:nixos-21.05 git-review  # adjust to your release

Unstable

nix run -f channel:nixos-unstable git-review

Installation can be done with your preferred method (home-manager, via system configuration or with nix-env).

Install using pip Python package installer

Note: if you don't have apt-get but have python installed, you can also install the latest version of git-review by using the python package installer. The exact command depends on your distribution, either:

sudo apt-get install python-pip

or

sudo easy_install pip

Once pip is installed, you can use:

sudo pip install git-review

FreeBSD

You can directly install git-review through ports.

cd /usr/ports/devel/git-review
make install

Windows

Python is needed for git-review to function and pip is used for its installation:

Install Python or upgrade to the most current version of Python 2 or Python 3.
Important: Do not install Python in any directory with a space in its path as there is a pip bug (see [1]), use the default, e.g. C:\Python34\
During the Python installation, manually select Add python.exe to Path
Otherwise, add your python scripts directory manually to the system path (Settings, Control panel, System, Advanced system settings, Environment variables, User variables, Path; e.g. C:\Python34\;C:\Python34\Scripts\;). Different directories in path are delimited by a semicolon ";" only - do not add any whitespace to path list.
Python 3.4 has pip already installed. Only if you have an older version, install pip by following the instructions here.
Run Git Bash as Administrator (right click on icon for this option) and install git-review with the following command:

pip install git-review

If you experience problems such as these:

 Retrying (Retry(total=4, connect=None, read=None, redirect=None)) after connection broken by 'ConnectTimeoutError(<pip._vendor.requests.packages.urllib3.connection.VerifiedHTTPSConnection object at 0x03B55750>, 'Connection to pypi.python.org timed out. (connect timeout=15)')': /simple/git-review/

try running:

pip install git-review --proxy=www-proxy-lon.uk.oracle.com:80

the exact proxy to use can be extracted from http://wpad/wpad.dat file.

To use git review, you have to be in a git clone directory that already contains a (possibly hidden) .gitreview configuration file (see Setting up a repository for git-remote)

Mac OS X

Method 1 (Homebrew)

Works on OS X 10.11 El Capitan and later (verified on High Sierra 10.13.5):

Install Homebrew
Install git-review with brew install git-review

Method 2 (Package Installer for Python “pip”)

Mac OS X comes with Python 2.7 (for now) but not the installation programs supported by Git and git-review.

Open Terminal and change to a directory you're comfortable downloading test Git packages to (such as Downloads)
Download and install the OS X Installer for Git (for OS X 10.8 and earlier only, OS X 10.9 ships with Git pre-installed)
Install pip (Note: Already included in some older versions of OS X):
```
sudo easy_install pip
```
Update pip/setuptools (for OS X 10.7 and earlier only):
```
sudo pip install -U setuptools
```
Install git-review. OS X as of version "El Capitan" protects locations in the filesystem including /System/Library/Frameworks/Python.framework/Versions/2.7/share so typical install method will fail using sudo. Instead install git-review locally to your home folder like this:
```
pip install --user git-review
```
Update your PATH shell variable to include the location of git-review which should be in $HOME/Library/Python/2.7/bin

If you get the error pkg_resources.DistributionNotFound: git-review, you may want to try nuking the pre-installed Python (/Library/Python/), installing Python via homebrew (brew install python), and re-installing setuptools and git-review.

If you get a git command not found after a seemingly successful installation, do not reinstall over the existing installation, but uninstall git-review and redo sudo pip install -U setuptools

Setting up git-review

Follow the instructions in the Gerrit tutorial to configure git-review so that it uses "origin" as its default remote. This avoids confusion and conflicts between remotes named "gerrit" and "origin".

After cloning a repository, you need to set it up for using git-review. This will automatically happen the first time you try to submit a commit, but it's generally better to do it right after cloning.

cd MyNewProj
git review -s

This may ask you for your git username, if it's different from the shell username you're using.

Internally, this does the following:

checks whether accessing the remote repository works
if it doesn't, asks for a username and tries again
creates a remote called 'gerrit' that points to gerrit
installs the commit-msg hook

Submitting changes with git-review

Submitting changes with git review does not involve a lot of commands:

git checkout -b mycoolfeature
[change files]
git commit -a
git review

What happens when you submit a change

When you submit a change, git review does the following things:

it looks up which branch to push to (production or whatever) in the .gitreview file. If it can't find this information, it pushes to master
it figures out what "topic" to put on the revision (you can set the topic manually with -t)
- if you're resubmitting a downloaded change, it will reuse the topic of the original change
- if your commit summary contains a bug number like bug 12345, the topic will be bug/12345
- otherwise, the topic will be the name of your local branch
it rebases your change against the HEAD of the branch you're pushing to (use -R to skip this)
if you are submitting more than one change at once, or submitting a change that's based on another unmerged change, it will ask you whether you really meant to do that (use -y to skip this)
it pushes the change for review

Work in progress changes

If you want to share an unfinished change (for example to ask help on how to solve a problem), you can use the --work-in-progressoption to mark the patch as WIP (you can filter out such patches in Gerrit searches using -is:wip):

git review --work-in-progress

It's best practice to also prefix the commit summary with [WIP] when doing that.

Downloading a change with git-review

When downloading a change from gerrit to review it or amend it, git-review offers an alternative to copy-pasting a magic incantation from the Gerrit web UI. All you need is the sequence number of the change in Gerrit, which you can find in the URL: https://gerrit.wikimedia.org/r/2033.

git review -d 2033

This will download the change, put it in a branch called review/AUTHOR/TAG (if the change has no tag, the sequence number will be used instead), and switch to that branch.

After that, you can amend the downloaded change to improve it.

Alternatively, you can use git review -x 2033 to download (cherry-pick) the patch into the current branch.

Troubleshooting

For problems and how to solve them, see Gerrit/Troubleshooting.

Troubleshooting for Windows

If this fails, you have a couple of options. The first is the use scp (secure copy) from within your local repository's directory, for each repository, before committing edits to it:

scp -P 29418 USERNAME@gerrit.wikimedia.org:hooks/commit-msg .git/hooks/commit-msg

The second is to try patching c:\Python27\Scripts\git-review to make git-review work properly:

--- /c/Python27/Scripts/git-review-old  Tue May 28 20:51:50 2013
+++ /c/Python27/Scripts/git-review      Tue May 28 20:48:03 2013
@@ -952,6 +952,9 @@
     config = get_config(os.path.join(top_dir, ".gitreview"))
     hook_file = os.path.join(git_dir, "hooks", "commit-msg")

+    # msysgit hacks to work around scp.exe (--aaron)
+    hook_file = unicode.replace( ".\%s" % os.path.relpath( hook_file ), "\\", "/" )
+
     defaultrebase = convert_bool(
         git_config_get_value("gitreview", "rebase",
                              default=str(config['defaultrebase'])))

If using Python 2.x and git-review 1.17 or earlier, use str.replace instead of unicode.replace.

Another error encountered on Windows is:

    ...
    (top_dir, git_dir) = git_directories()
ValueError: too many values to unpack (expected 2)

One solution to this is to change the return line of git_directories() to use splitlines rather than its normal split function. Split looks for any whitespace and will produce this error when the path to your source code directory contains a space. Splitlines looks for newline characters and will not produce this same error.

     return out.splitlines()