git-review is a command-line tool for Git / Gerrit. It makes it easier to configure your Git clone, to submit a change or to fetch an existing one.
- 1 Installation
- 2 Setting up git-review
- 3 Submitting changes with git-review
- 4 Downloading a change with git-review
- 5 Full feature branch workflow with git-review
- 6 Setting up a repository for git-remote
- 7 Troubleshooting
- 8 See also
Installation[edit | edit source]
- See also Gerrit/Tutorial#Installing git-review.
If you can, it is recommended to install version 1.21 - it's buggy, but others seem to have worse bugs, especially if working with many different repositories.
Linux[edit | edit source]
Debian[edit | edit source]
Users of Debian or related distributions (e.g., Ubuntu, Mint) on a shared host usually do not have root access. If you cannot get you hosting administrator to install git-review for you, you can try to install it locally. Go to the appropriate section below
Having root access[edit | edit source]
You can do
sudo apt-get install git-review
sudo apt-get install python-pip sudo easy_install pip sudo pip install git-review==1.21
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 (e.g. on OS X), you can use this:
$ sudo easy_install pip $ sudo pip install git-review==1.21
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.
Without root access[edit | edit source]
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==1.21
If this is your first local install, or you have not done that already, extend your PATH to include the the local binaries. There are two ways to do that. The more convervative way
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.
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
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/CentOS[edit | edit source]
sudo yum install git-review
If, while using git-review, you see
ImportError: No module named requests, you'll need to install
sudo yum install python-requests
You may find that yum cannot find the git-review package -- in this case you can enable the REMI repository and try again.
OpenSUSE[edit | edit source]
Install (YaST) the
easy_install pip pip install git-review==1.21
As of OpenSUSE 13.1, git-review is included in the main repository, so you can use,
sudo zypper in git-review
Gentoo[edit | edit source]
emerge dev-python/pip pip install git-review==1.21
Arch Linux[edit | edit source]
sudo pacman -S git-review
NixOS[edit | edit source]
Install python and pip:
$ nix-env -i -A pythonPackages.pip
Add ~/.local/bin to your path:
$ export PATH=$PATH:~/.local/bin $ echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
$ pip install git-review==1.21 --user $ pip install --upgrade setuptools $ pip install --upgrade distribute
FreeBSD[edit | edit source]
You can directly install git-review through ports.
cd /usr/ports/devel/git-review make install
Windows[edit | edit source]
Python is needed for git-review to function and pip is used for its installation:
- Install Python or upgrade to most current version (either 3.4.2 or 2.7.8 depending on your python installation).
- Important: Do not install Python in any directory with a space in its path as there is a pip bug (see ), use the default, e.g.
- 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
- To use
git review, you have to be in a git clone directory that already contains a (possibly hidden)
.gitreviewconfiguration file, otherwise you will get the error message UnboundLocalError: local variable 'no_git_dir' referenced before assignment
OS X[edit | edit source]
OS X comes with Python (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:
sudo pip install git-review
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.
Setting up git-review[edit | edit source]
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
Troubleshooting for Windows[edit | edit source]
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
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.
Submitting changes with git-review[edit | edit source]
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[edit | edit source]
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
- if you're resubmitting a downloaded change, it will reuse the tag of the original change
- if your commit summary contains a bug number like
bug 12345, the tag will be
- otherwise, the tag will be the name of your local branch
- it rebases your change against the HEAD of the branch you're pushing to (use
-Rto 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
-yto skip this)
- it pushes the change for review
Downloading a change with git-review[edit | edit source]
When downloading a change from gerrit to review it or amend it, git-review offers an easier alternative to copypasting 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:
$ 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.
Full feature branch workflow with git-review[edit | edit source]
you@yourmachine:~/puppet (production)$ git checkout -b mycoolfeature you@yourmachine:~/puppet (mycoolfeature)$ vi foobar you@yourmachine:~/puppet (mycoolfeature)$ git commit -a -m "Committing my cool feature" you@yourmachine:~/puppet (mycoolfeature)$ git review -f you@yourmachine:~/puppet (production)$
-f flag is passed to git-review, it will try to submit the change, and if it succeeds it will switch back to the master branch (production in this case) and delete the feature branch.
Setting up a repository for git-remote[edit | edit source]
To tell git-remote where your repository is and what the name of the master branch is, you need to create a .gitreview file in the root of the repository, and commit it. The format is the following:
[gerrit] host=gerrit.wikimedia.org port=29418 project=operations/puppet.git defaultbranch=production
project fields are mandatory. The other fields are optional:
port defaults to 29418 and
defaultbranch defaults to
Troubleshooting[edit | edit source]
"You have more than one commit that you are about to submit."[edit | edit source]
Even if you only have one new commit, when submitting subsequent commits after the first, some versions of git-review may get confused and think you're trying to submit all of them, regardless of whether or not they're already upstream.
It may look a bit like this, HEAD being what you were actually trying to submit:
$ git review You have more than one commit that you are about to submit. The outstanding commits are: cae7f80 (HEAD) Mobile stuff? a836f74 Move GreyStuffTemplate class into its own file 3d5b6f9 Content style tweaks 57f3a5f Make skin sort of responsive, other random stuff Is this really what you meant to do? Type 'yes' to confirm:
Just say 'yes' unless something looks obviously wrong. Gerrit will figure it out on the other end and only add any new ones that really are new.
"Cannot query patchset information"[edit | edit source]
git-review does not work correctly if git generates non-English output. You will see an error like this:
$ git review -d 62474 Cannot query patchset information The following command failed with exit code 255 "ssh -x -p None gerrit query --format=JSON --current-patch-set change:62474" ----------------------- Bad port ' None' -----------------------
This is due to a bug in git-review.
To work around this on a Linux system, either apply the patch from the bug report above, or set up an alias that forces git to use English output. To do so, put this into your
bashrc or similar setup file:
alias git="LANG=C git"
"Could not parse json query response: u'Verified'"[edit | edit source]
git-review version 1.18 has been reported to have issues when trying to review a change from Gerrit. You will see an error like this:
$ git review -d 76352 Could not parse json query response: u'Verified'
This seams to be due to a bug in git-review v1.18 since v1.12 and v1.21 work correct.
To work around this on a Linux system, use another version like v1.12 on fedora or v1.12, v1.21 on ubuntu (by downgrading or removing v1.18 and installing the suitable rpm). Version 1.22 under fedora works also.
"ConfigParser.NoSectionError: No section: 'updates'"[edit | edit source]
$ git review -s Traceback (most recent call last): File "/usr/local/bin/git-review", line 1196, in <module> main() File "/usr/local/bin/git-review", line 1108, in main needs_update = latest_is_newer() File "/usr/local/bin/git-review", line 179, in latest_is_newer if not configParser.getboolean("updates", "check"): File "/usr/lib/python2.7/ConfigParser.py", line 368, in getboolean v = self.get(section, option) File "/usr/lib/python2.7/ConfigParser.py", line 607, in get raise NoSectionError(section) ConfigParser.NoSectionError: No section: 'updates'
Adding something like this to ".gitreview" fixes the problem: