Gerrit/git-review

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.

The upstream project is lead by Openstack. Not to be confused with the unrelated Facebook project.

Installation

 * See also Git/Tutorial.

Linux
Install git-review, a tool to simplify working with Gerrit repositories so you don't have to remember some pretty confusing commands.

Debian
Users of Debian or related distros (e.g., Ubuntu, Mint) can do

Note:  Do not install git-review via apt. It looks like it works, but doesn't.

If you do not have easy_install set up, try

Then run:

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 pre-commit hook.

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

OpenSUSE
Install (YaST) the, then

FreeBSD
You can directly install git-review through ports.

Windows

 * Python is required (use version 2.x).
 * Install pip using these instructions :
 * Download and install the latest easy installer for Windows: the .exe at the bottom of http://pypi.python.org/pypi/setuptools (make sure it is the right version for your Python; possibly upgrade Python first)
 * Download and uncompress the latest pip version from here: http://pypi.python.org/pypi/pip#downloads (make sure it is the right version for your Python; possibly upgrade Python first)
 * Go to the uncompressed pip directory and run python setup.py install.
 * Add your c:\Python2x\Scripts to the system path (replacing "X" with the actual python version). Different directories are delimited only by a ";", so do not add whitespace.
 * Run pip install git-review
 * Create git-review.bat in some PATH-accessible directory containing the following line (replacing "X" with the actual python version):
 * Make sure you can connect to gerrit properly via SSH.
 * Start Git Bash.
 * Get ssh-agent running if not done already via eval `ssh-agent`.
 * Add your key to the agent if not done so already via ssh-add path/to/key. Make sure the key is in OpenSSH format (.ppk keys can be exported to this format in PuTTyGen).
 * Run . It should give a Gerrit welcome message and then abort.
 * In Git Bash, go to the directory of the fresh MediaWiki clone and run git-review -s. This should install a git hook called "commit-msg" under .git/hooks. Check that the file is there. From now on, commits will have a change-id appended to the summary, which Gerrit will need in order to accept any commits for review.
 * If you get "permission denied (publickey)" no matter what, you have two options. The first is the run  from within the repo's .git/hooks directory every time you want to run "git-review" on a repo for the first time. The second is to try patching "c:\Python2x\Scripts\git-review" to make git-review work properly:
 * If using Python 3 or git-review 1.18, use "unicode.replace" instead of "str.replace".

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


 * 1) Open Terminal and change to a directory you're comfortable downloading test Git packages to (such as Downloads or Sites)
 * 2) Download and install the OSX Installer for Git
 * 3) Install pip (Note: Already included in some older versions of Mac OS X):
 * 4) Install git-review:
 * 1) Install git-review:

Setting up git-review
To avoid miserable confusion and conflicts between remotes named "gerrit" and "origin", the Gerrit tutorial recommends adding a git-review config file telling git review to use "origin" as its default remote. If you know what you're doing you can disregard that suggestion.

After cloning a repository, you need to set 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. 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 is super easy: $ 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, if pushes to master
 * it figures out what tag to put on the revision (you can set the tag 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, 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  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  to skip this)
 * it pushes the change for review

Downloading a change with git-review
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  (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
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)$ If the  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
To tell git-remote where your repository is and what the name of the master branch is, you need to create a .gitremote file in the root of the repository, and commit it. The format is the following: The  and   fields are mandatory. The other fields are optional:  defaults to 29418 and   defaults to.

"Cannot query patchset information"
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  or similar setup file:

alias git="LANG=C git"