Gerrit/Tutorial

large projects with speed and eciency. Git is easy to

learn and has a tiny footprint with lightning fast performance. It outclasses SCM tools like Subversion, CVS,
Perforce, and ClearCase with features like cheap local
branching, convenient staging areas, and multiple workows.

2 What is Gerrit?
Gerrit is a free, web-based collaborative code review tool
that integrates with Git. It has been developed at Google
by Shawn Pearce (co-author of Git, founder of JGit) for
the development of the Android project.

Git and Gerrit lets us deploy your code faster and makes collaboration easier!

Starting from a set of patches for Rietveld, it became a

fork and evolved into a full blown project when ACL
patches wouldn't be merged into Rietveld by its author,
step-by-step instructions and screenshots for getting Guido van Rossum.
Gerrit access
Originally written in Python like Rietveld, it is now written in Java (Java EE Java Servlet) with SQL since version
setting up Git on your machine
2.
conguring Git

This tutorial helps you with:

installing git-review

3 Why did Wikimedia engineering

move from Subversion to Git

submitting a patch
understanding the MediaWiki code review process

Three major reasons:

For the quick version, see Gerrit/Getting started.
Gerrit/Advanced usage has additional documentation for
power users.

1. To encourage participation: Since Git is distributed, it allows people to contribute with a much
lower barrier to entry. Anyone will be able to clone
the repository and make their own changes to keep
track of them. And if youve got an account in
our code review tool (Gerrit), youll be able to push
changes for the wider community to review.

What is Git?

Git is a distributed version control system (dvcs) written in C originally developed by Linus Torvalds and others to manage the Linux kernel. In the past couple of
years, it has taken o as a very robust and well-supported
code repository. Distributed means that there is no central copy of the repository. With Subversion, Wikimedias servers host the repository and users commit their
changes to it. In contrast, with Git, once youve cloned
the repository, you have a fully functioning copy of the
source code, with all the branches and tagged releases at
your disposal.

2. To x our technical process: Subversion has technical aws that make life dicult for developers.
Notably, the implementation of branching is not
very easy to use, and makes it hard to use feature
branches. Our community is very distributed, with
many parallel eorts and needs to integrate many
dierent feature eorts, so wed like to use feature branches more. Git branches are very easy to
work with and merge between, which should make
things easier for our development community. (Several other large projects, such as Drupal and PostgreSQL, have made the same switch for similar rea-

Git is a free and open source distributed version control

system designed to handle everything from small to very
1

4
sons, and weve done our best to learn from their
experiences.)
3. To get improvements to users faster: With better
branching and a more granular code review workow that suits our needs better, plus our ongoing
improvements to our automated testing infrastructure, we wont have to wait months before deploying
already-written features and bugxes to Wikimedia
sites.

SETTING UP GIT

Fedora: yum install git

archlinux: pacman -S git
openSUSE: zypper install git
Gentoo: emerge --ask --verbose dev-vcs/git
FreeBSD: cd /usr/ports/devel/git; make install
NetBSD: cd /usr/pkgsrc/devel/scmgit/; make install

Setting up Git

These instructions explain how to install Git as a

command-line tool. If you also want a GUI client check
the list maintained by the Git project. For alternate instructions look here, or here.

4.1
4.1.1

Installation

OpenBSD: pkg_add git

Solaris 11 Express:
oper/versioning/git

pkg

install

devel-

Mageia: urpmi git

Now that you have Git installed, its time to congure your
personal info.

Mac OS X

4.2 Congure Git

Install one of the following:
Now that you have Git on your system, youll want to do
Homebrew package manager: brew install git Rec- a few things to customize your Git environment. You
ommended, simple updating and easy installing of should have to do these things only once; theyll stick
around between upgrades. You can also change them at
other packages
any time by running through the commands again.
Standalone: Git for Mac
Git comes with a tool called git cong that lets you get and
set conguration variables that control all aspects of how
4.1.2 Windows
Git looks and operates. To see your current conguration
use the list -l option:
Install Git + MSys (Minimal Bash for Windows) from
git cong -l
msysgit.github.io . This gives you Git, plus a shell that
allows most of the command lines in these instructions to
work on Windows. See also Gerrit/TortoiseGit tutorial.
4.1.3

Linux & UNIX

4.2.1 Set your username and email

Git tracks who makes each commit by checking the users
name and email. In addition, we use this info to associate
your commits with your Gerrit account. To set these, enFor other Linux distributions please check your vendor ter the code below, replacing the name and email with
your own.
documentation.
git cong --global user.email example@example.com
Debian/Ubuntu: sudo apt-get install git
git cong --global user.name example
Installing git on Ubuntu

5.2

Add your SSH key

3
down that random password in a
le on your computer. Anyone who
gains access to your drive has gained
access to every system you use that
key with. This is also a Very Bad
Thing. The solution is obvious:
add a passphrase.
But I dont want to enter a long
passphrase every time I use the
key!

Set Up SSH Keys in Gerrit

Neither do we! Thankfully, theres a

nifty little tool called ssh-agent that
can save your passphrase securely
so you dont have to re-enter it. If
youre on OSX Leopard or later your
keys can be saved in the systems
keychain to make your life even easier.

We use SSH keys to establish a secure connection between your computer and Gerrit. Setting them up is fairly
easy, but does involve a number of steps. Run the follow- Which should give you something like this:
ing commands in a terminal. For alternate instructions
look here, and then here.
To make sure whether you need to generate a brand new
key, you need to check if one already exists. List the les
in your .ssh directory (if you have one):
$ ls ~/.ssh
If you see a le called id_rsa.pub here, you may skip right
to #Add your SSH key.

5.1

Generate a new SSH key

To generate a new SSH key, enter the code below. We

want the default settings so when asked to enter a le in
which to save the key, just press enter.
$ ssh-keygen -t rsa -C your_email@youremail.com
Assign a memorable passphrase and press [enter] (press
the [enter] key twice if you don't want a passphrase*).
* Why do passphrases matter?
Passwords arent very secure, you
already know this. If you use
one thats easy to remember, its
easier to guess or brute-force (try
many options until one works).
If you use one thats random its
hard to remember, and thus youre
more inclined to write the password
down. Both of these are Very Bad
Things. This is why youre using
ssh keys.
But using a key without a passphrase
is basically the same as writing

It will create 2 les in ~/.ssh directory as follows:

~/.ssh/id_rsa :
identication
~/.ssh/id_rsa.pub : public key

(private)

key

5.2 Add your SSH key

Open your public key le, (e.g. id_rsa.pub) with a text editor (Notepad, TextEdit, or gedit will do just ne). You
may need to turn on view hidden les to nd it because
the .ssh directory is hidden. Its important you copy your
SSH key exactly as it is written without adding any newlines or whitespace. Copy the full text, including the sshrsa lead and email address tail.

6 PREPARE TO WORK WITH GERRIT

On a linux system you can use the following:

cat /home/<local-user>/.ssh/id_rsa.pub

Run ssh. (Do be paranoid and check for the matching SSH ngerprint for gerrit.wikimedia.org:29418
when logging in for the rst time.)

Which for local-user preilly, gives this:

$
ssh
-p
29418
NAME>@gerrit.wikimedia.org

<USER-

It should give a Gerrit welcome message and

then abort. If it doesn't, add the -v (verbose)
option to the command to help debug.

5.2.1

Cant view hidden les? Other ways to copy:

5.5 Download the Examples extension using Git

OSX
You can download MediaWiki core using Git, as well
$ pbcopy < ~/.ssh/id_rsa.pub # Copies the contents of the
as the source code of any project repository hosted at
id_rsa.pub le to your clipboard
gerrit.wikimedia.org (the Wikimedia Foundation server
Windows
cluster).
You can open Git GUI, go to Help > Show Key, and then
Lets practice downloading the Examples extension. Simpress Copy To Clipboard to copy your public key to your
ply run the following on the git bash command line:
clipboard.
$ git clone ssh://<USERNAME>@gerrit.wikimedia.org:
Linux
29418/mediawiki/extensions/examples
$ sudo apt-get install xclip # Downloads and installs xclip
$ xclip -sel clip < ~/.ssh/id_rsa.pub

5.3

Add SSH key to your Gerrit account

Create an account at wikitech.wikimedia.org if you do

not yet have one.
Log into the web interface for Gerrit. Click on your username in the top right corner, then choose Settings. On
the left you will see SSH PUBLIC KEYS. Paste your SSH
Public Key into the corresponding eld. Alternately, once
logged in, use these direct links to add your public key to
Gerrit and wikitech.

5.4

Add SSH key to use with Git

Start Git Bash.

Get ssh-agent running using

This will copy the entire history of the Examples extension repository. You will have a working directory of the
extensions main branch, so you can look at the code and
start editing it. If you change into the new directory, you
can see the .git subdirectory. That is where all the project
data is.
By default, Git will create a directory that has the same
name as the project in the URL you give it - basically
whatever is after the last slash of the URL. If you want
something dierent, you can just put it at the end of the
command, after the URL. So, in this example you will
have a examples directory.

$ eval `ssh-agent`
Be sure to use the accent " ` " located under the
tilde " ~ " (or above tab for UK keyboards), not
the single quote " ' ".

6 Prepare to work with Gerrit

Your commit message needs a change ID in

order to work with Gerrit.
You can see these
Add your private key to the agent (use path to your
in the git log for a project and if you browse
private key le)
changes on Gerrit, they look like Change-Id:
Ibd3be19ed1a23c8638144b4a1d32f544ca1b5f97
$ ssh-add .ssh/id_rsa
starting with an I (capital i)). Each time you amend
if the key is in the default location, use $ ssha commit in response to Gerrit feedback git gives it a
add ~/.ssh/id_rsa
new commit ID, but because this change ID stays the
Key should be in OpenSSH format (.ppk keys
same Gerrit will keep track of it as a new patch set
can be exported to this format in PuTTyGen).
addressing the same change.

6.2

Conguring git-review

Theres a git add-on called git-review that adds a ChangeID line to your commits and manages other aspects of
using Gerrit.

6.1

Installing git-review

For more details, please see Gerrit/git-review

First, install the release version of git-review.
In Windows, please see Gerrit/git-review#Windows.
If you're running recent Debian/Ubuntu, git-review has
been packaged, so you can simply run
$ sudo apt-get install git-review
If that worked, skip past the next section.
6.1.1

Install using pip Python package installer

Generally, the easiest way to get the latest version of gitreview is to install it using the python package installer
pip:
$ sudo pip install git-review
If that worked, skip to the next section. If you need to
install pip, then:
In Debian/Ubuntu, to install
$ sudo apt-get install python-pip
On OpenSuse, install via YaST python-setuptools, then On FreeBSD, you directly have a kept up to date
devel/git-review port:
run
$ cd /usr/ports/devel/git-review $ make install
$ sudo easy_install pip
Note: if you don't have apt-get but have python installed,
you can use this:
$ sudo easy_install pip $ sudo pip install git-review
Or, if you already have git-review installed, you can upgrade it using
$ sudo pip install --upgrade git-review

6.2 Conguring git-review

Git is a distributed version control system; its possible to
fetch code from one host, push your changes to another,
and submit them to a third for Gerrit code review. Its a
lot simpler to work with one remote for all three. Since
Gits default remote name is origin and most guides on
the web use that name, lets tell git-review to use this as
well.
$ sudo pip install git-review

$ git cong --global gitreview.remote origin

HOW TO SUBMIT A PATCH

Note: Older versions of git-review used a separate con- git pull origin master
g le:.cong/git-review/git-review.conf (in Windows,
the le is %USERPROFILE%\.cong\git-review\gitreview.conf) and add these two lines:
## Deprecated! [gerrit] defaultremote = origin

6.3

Setting up git-review

However, note that a few repositories use dierent terms

(for example operations/puppet has a production instead of a master branch).

After cloning a repository, you need to set it up for gitreview. This will automatically happen the rst time you 7.2 Create a branch
try to submit a commit, but its generally better to do it
right after cloning. In your projects directory (examFirst, create a local branch for your new change. Give
ples), enter
the branch a short but reasonably descriptive name (e.g.
$ git review -s
T1234, bug/1234, cleanup/some-thing, badtitle-error, ..).
which should give you this:

git checkout -b BRANCHNAME origin/master

krinkle@example:~/dev/mw$ git checkout -b badtitleerror origin/master # Switched to a new branch
'badtitle-error' krinkle@example:~/dev/mw$ git branch
* badtitle-error master
This will create a new branch (BRANCHNAME) from
the latest 'master' and check it out for you. This is equivalent to doing

If you see the authenticity of host gerrit.wikimedia.org

can't be established... Dont worry, this is supposed to git branch BRANCHNAME --track origin/master git
checkout BRANCHNAME
happen the rst time. Type yes.
This may ask you for your git username, if its dierent
from the shell username you're using.

How to submit a patch

For a brief overview see Gerrit/Getting started.

7.3 Make and commit your change

7.3.1 Usual way
Modify your local code in some fashion.
Using your preferred editor, modify the le Example/Example.body.php

The main avenue for submitting changes to MediaWiki

code is to rst join the MediaWiki development commu- Then check the changes you've made, within the le(s)
nity so you can submit changes to Gerrit, our code review and within the directory:
tool. Getting developer access is relatively easy.
git di
Clone the mediawiki core repository or the project
repository which you are interested in. Open git bash and
enter one of the following lines:
$ git clone ssh://USERNAME@gerrit.wikimedia.org:
29418/mediawiki/core.git
$
git
clone
ssh:
//USERNAME@gerrit.wikimedia.org:29418/
mediawiki/extensions/EXTENSION.git
Substitute your Gerrit username and the extension or
project name. You can copy this git command from the
top of the projects home page in Gerrit.

7.1

Update master

Make sure that your master branch (the branch created

when you initially cloned the repository) is up to date:

7.3

Make and commit your change

Without any extra arguments, a simple git di will display in unied di format (a patch) what code or content
you've changed in your project since the last commit that
are not yet staged for the next commit snapshot.
Then check the changes you've made, within the le(s)
and within the directory:
git status

The git di --cached command will show you what conYou run git status to see if anything has been modied tents have been staged. That is, this will show you the
and/or staged since your last commit so you can decide changes that will currently go into the next commit snapif you want to commit a new snapshot and what will be shot.
recorded in it.
Once you are happy with the change list, you can add
This will show all modied les. To prepare submitting a them to your local repository by using
le, you should add your changes to the index (the staging git commit
area between your working copy and your local repository), which is done by using the git add command.
git add Example/Example.body.php

You will then be prompted in your favorite editor to add

a descriptive message for this commit. This is what other
people will see when you will later push that commit to
another repository. If you do not manually add a ChangeID line to your commit message, it will be automatically
generated and added for you.

You pass a le to git add when you want the changes you
You can repeat this step over and over until you have a
made to it to be included in your next commit.
set of changes that you want to have pushed to the masAny les you've changed that are not staged by you doing ter branch. One of the cool things about git is that when
git add will be left alone - this means you can craft your you git commit, you are committing to your local copy.
commits with a bit more precision.
This means you can commit as often as you like without
At any time you can always review the changes already potentially screwing things up for another developer on
added to the staging area by running git status, and look the project, unlike in SVN where you would want to be
very careful that the changes you commit would not cause
at the di with git di --cached:
things to break.
Hence the workow is something like:
# Add change: $ git add <some le> # Verify list of
les added to the staging area $ git status # Review di

HOW TO SUBMIT A PATCH

of changes staged: $ git di --cached # repeat until you some code squash be33007 Fixed my bug in that le
are happy with your changes $ git commit <edit commit Save the le. Another le will open in your text editor
message>
which will allow you to edit the combined commit message. Be careful to only keep one of the Change-Id lines
and have it be at bottom of the message after one empty
line.

7.4

Prepare to push your change set to

Gerrit

7.6 Push your change set to Gerrit

Before your changes can be merged into master, they

It is recommended to use git-review to submit patches for
must undergo review in Gerrit.
review. If you do not have installed git-review and do not
But rst, its a good idea to synchronize your change set
want to do so, you can use the Gerrit patch uploader to
with any changes that may have occurred in master while
submit your patch.
you've been working. From within the branch you've
If you installed git-review and you ran git review -s to set
been working on, execute the following command:
it up for this repository, the command to push changes to
git pull --rebase origin master
Gerrit is very simple:
git review -R
The -R option tells git-review not to perform a rebase before submitting the change to Gerrit.

This command will fetch new commits from the remote

and then rebase your local commits on top of them. It will
temporarily set aside the changes you've made in your
branch, apply all of the changes that have happened in
master to your working branch, then merge (recommit)
all of the changes you've made back into the branch. Doing this will help avoid future merge conicts. Plus, it Upon success, you'll get a conrmation and a link to the
gives you an opportunity to test your changes against the changeset in Gerrit.
latest code in master.
New patchset: preilly; Added get version method to exOnce you are satised with your change set and you've tension [test/mediawiki/extensions/examples] (master) rebased against master, you are ready to push your code https://gerrit.wikimedia.org/r/9332
to Gerrit for review.
Note: It is recommended to use git-review to submit 7.6.1 Problems
patches for review. If you do not have installed git-review
and do not want to do so, you can use the Gerrit patch up- If you forgot to run git review -s, remote will complain
loader to submit your patch.
about missing Change-id in commit message.

7.5

Squash into single commit

But it will also suggest a commit message with a ChangeId: INNNXXXNNN... line.
Either:

If you make several related commits to your local repository prior to wanting to submit for review, you should
squash those commits into a single commit. If you've followed everything above, you can perform this action by
doing:
git rebase -i origin/master
This will bring up your text editor with text like:
pick 749a62a Added a le pick ec9295b Changed some
code pick be33007 Fixed my bug in that le

Copy that line starting with Change-Id, run git

commit --amend, and paste the Change-Id line under your commit message in the text editor that
opens up.
Or it will suggest a hook x:
gitdir=$(git rev-parse --git-dir); scp -p P
29418
freephile@gerrit.wikimedia.org:
hooks/commit-msg ${gitdir}/hooks/

Change all but the rst pick to squash":

pick 749a62a Added a le squash ec9295b Changed You should be able to use either method (but the hook

7.9

Amending a change (your own or someone elses)

didn't work for me), then repeat git review -R and it 7.9
should complete.

7.7

Amending a change (your own or

someone elses)

View the Change / Next Steps

You can view this change in the Gerrit Web UI:

BEWARE: git review -d performs a hard reset that destroys all local changes. Stash or commit changes you
wish to preserve rst.
Sometimes, you might need to amend a submitted
change. You can amend your own changes as well as
changes submitted by someone else, as long as the change
hasn't been merged yet.
Rebase to bring your local branch up to date with the remote. Its best to make rebase updates a separate patch, so
that your code reviewers have an easy time seeing what
changes you've made. Assuming you are using Gerrit,
you can do this by clicking the Rebase Change button
when viewing your patch in Gerrits web interface.
If you have git-review, hard reset and checkout the change
with this command:
git review -d <change number>
Note, if you already have the change in a branch on your
local repository, you can just check it out instead:

If you want to see your changed les in their context then

click on the (gitweb) links and the tree link (you then will git checkout <branch name>
see).
For example:
If your commit addresses a ticket in Phabricator, please git review -d 9332
comment on that ticket to note that the commit is in the
merge queue, and link to its changeset in Gerrit.

7.8

Push to a branch

Or, if you already have the branch,

git checkout review/preilly/2012/bug12345

As you can see in the screenshot above, the commit was Should accomplish the same thing.
pushed to master. The branch name only appeared as
the topic of the commit. If you really want to push to a Next, make some changes.
branch, you have to push via git review <branch name>. vim Example/Example.body.php

10

HOW TO SUBMIT A PATCH

not rebase your change against master, which

clutters dis between patch set 1 and 2.

New patchset: preilly; Added get version method

to extension [test/mediawiki/extensions/examples]
(master)
https://gerrit.wikimedia.org/r/9332

git add the les as needed, then commit the change (ensuring you are amending the commit):
git add Example/Example.body.php git commit --amend
--all

7.9.1 git-review complains about multiple commits

NOTE: DO NOT use the -m ag to specify a commit
summary: that will override the previous summary and If git review asks you if you really want to submit multiple
regenerate the Change-Id. Instead, use your text editor commits, and lists a bunch of unrelated commits from
to change the commit summary if needed, and keep the dierent branches, try either of these:
Change-Id line intact.
git fetch --all git remote update
Push the change
Both commands do exactly the same thing, they fetch obgit review -R
jects from all remote repositories set. So just pick the
command you remember easily and forget about the other
The -R is important here. It tells git-review to
one.

7.10

Push using HTTPS

11

If, after git review jenkins-bot emails This change was

unable to be automatically merged with the current state
of the repository. Please rebase your change and upload a new patchset. This might mean that server master
branch now has merge conicts with your patch. Check
advanced Gerrit usage to see how to x them.

Username for 'https://gerrit.wikimedia.org': xxxxxx

Password for 'https://xxxxxx@gerrit.wikimedia.org':
Counting objects: 25, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 448 bytes | 0 bytes/s, done.
Total 4 (delta 3), reused 0 (delta 0)
remote: Resolving deltas: 100% (3/3)
remote: Processing changes: refs: 1, done
remote: ERROR: missing Change-Id in commit message
footer
remote: Suggestion for commit message:
remote: Commit message appears here
remote:
remote: Change-Id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
remote:
remote: Hint: To automatically insert Change-Id, install
the hook:
remote: gitdir=$(git rev-parse --git-dir); scp -p -P 29418
xxxxxx@gerrit.wikimedia.org:hooks/commit-msg
${gitdir}/hooks/
remote:
remote:
To
https://gerrit.wikimedia.org/r/p/mediawiki/
extensions/Test
! [remote rejected] HEAD -> refs/for/master (missing
Change-Id in commit message footer)
error: failed to push some refs to

7.10 Push using HTTPS

Now copy the change ID and amend your commit. Always add Change-ID as the last line of your commit message.

7.9.2

git complains you are in the middle of a

merge -- cannot amend

When after rebasing and merging your

git commit --amend
results in
message: fatal: You are in the middle of a merge -- cannot
amend.
apply these steps and reapply your changes
git stash git reset --hard git checkout master git review -d
<change number> git stash pop git commit -a --amend

This method is helpful for submitting to changes to Gerrit git commit --amend
when SSH is not functional.
This will open an editor to change the commit message.
For this the user needs the HTTP Password which can be Paste the Change-Id as the last line of the message and
generated in the Account Settings of Gerrit under the tab save it. See example:
of HTTP Password. After generating the password the Your commit summary
developer should commit all the changes for one patch Your commit message
under one single commit and use
Bug: Txxxxx
git push https://gerrit.wikimedia.org/r/p/mediawiki/core Change-Id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
HEAD:refs/for/master
Now you can successfully push to Gerrit.
The authentication credentials need to be entered to successfully submit the changes. The syntax given above
Automatically adding commit Hook To obtain the
is for Mediawiki core and will vary for extensions accommit-msg script:
cordingly. For example if one is pushing to Extention:
scp -p -P 29418 USERNAME@gerrit.wikimedia.org:
LiquidThreads then
hooks/commit-msg <local path to your git>/.git/hooks/
git push https://gerrit.wikimedia.org/r/p/mediawiki/
See
https://gerrit.wikimedia.org/r/Documentation/
extensions/LiquidThreads HEAD:refs/for/master
cmd-hook-commit-msg.html for details.
7.10.1

Commit Hook and Change-ID

7.10.2 Proxy servers

A major problem that arises when using HTTPS for submitting changes is that commit hook is not automatically This section is untested; please update this section with
attached. A hack for this approach is to make one fail updated information if issues arise
attempt to push. On doing so, the error message will automatically highlight the Change-Id, see below example: If you are behind a proxy server, you also need to

12

HOW WE REVIEW CODE

clone over HTTPS. Make sure the environment variable 8.2 Who can review? Gerrit project ownHTTPS_PROXY is set correctly. To debug issues, try
ers
running with GIT_CURL_VERBOSE=1, e.g.
GIT_CURL_VERBOSE=1
git
clone
https: Who has the ability to do code review?
//gerrit.wikimedia.org/r/pywikibot/core.git
We use gerrit.wikimedia.org to manage code review.
Anyone can ask for a Gerrit account get one!. Within
In case of issues, try providing HTTPS_PROXY directly, Gerrit, anyone can comment on commits and signal their
criticisms and approvals. Anyone can give a nonbinding
e.g.
"+1 to any commit. However, for any given repository
HTTPS_PROXY=proxy_server
(Gerrit project), only a small group of people will have
GIT_CURL_VERBOSE=1
git
clone
https: the ability to approve code within Gerrit and merge it into
//gerrit.wikimedia.org/r/mediawiki/core.git
the repository. This superapproval is a "+2" even though
thats a misleading name, because two +1 approvals DO
NOT add up to a +2. These people are Gerrit project
or use gits options directly:
owners. Learn about becoming a Gerrit project owner.
GIT_CURL_VERBOSE=1
git
-c
http.proxy="proxy_server
clone
https://gerrit. Even within a Gerrit project, we can also specify particular branches that only specic people can pull into.
wikimedia.org/r/mediawiki/core.git
This last option should also work for SOCKS proxy
8.3
servers, using
GIT_CURL_VERBOSE=1 git -c http.proxy="socks5:
//socks_server" clone https://gerrit.wikimedia.org/r/
mediawiki/core.git

How to comment on, review, and merge

code in Gerrit

7.11 Di algorithm
Gerrit uses jGits di , which uses a slightly dierent di
algorithm from gits default di algorithm.
To see roughly what a patch will look like in Gerrit, run
jgit show -w.
If jgit isnt available in your packaging system, download jgit.sh from https://eclipse.org/jgit/download/ and
A sample changeset, with annotations
use jgit.sh instead of jgit.

How we review code

Code review is an essential part of our contribution workow. The principle is basic: any patch must be reviewed
by others before being merged.
This means that your code will need reviewers. Check
our advice for getting reviews.

8.1

Review before merge

Its important to us to have a review-before-merge workow for MediaWiki core and also for any extension we
deploy. We will also oer that option to any extension author who wants it for their extension. The one exception is
localisation and internationalisation commits, which will
be able to be pushed without review.

Side-by-side di

Anyone can comment on code in Gerrit.

Gerrit comments may disappear in the future: you
may prefer keeping your comments/discussions on
Phabricator or a wiki instead, if you think they're worth

8.3

How to comment on, review, and merge code in Gerrit

13
nonbinding, won't cause merges or rejections, and have no formal eect on the
code review.
Abandon change (you'll see this if you wrote
this di). This action removes the di from
the merge queue, but leaves it in Gerrit for
archival purposes.
8.3.2 Comparing patch sets
Every time you amend your commit and submit it for review, a new patch set is created. You can compare the
dierent patch sets like this:

Review screen

preserving.

8.3.1

Select the older patch set in the Old Version History list.

Viewing and commenting on code

Make sure you have a https://gerrit.wikimedia.org

login (Get an account!). If you don't know, try logging in at https://wikitech.wikimedia.org; the username and password should be the same. If you can't,
ask in #mediawikiconnect for someone to help.

Expand the newer patch set details by clicking the

arrow near it.
Click Side-by-Side. Note that in Gerrit 2.3 this only
works if you open the di in the same tab, so don't
open it in a new tab.

8.3.3 Formally reviewing and merging or rejecting

code
Log in to Gerrit. If you know the changeset you
want to look at (URL will look like https://gerrit.
wikimedia.org/r/#change,8939 ), go to that. Other- If you are one of the Gerrit project owners, you'll also see:
wise, use the search box and try searching. There is
no fulltext search in Gerrit, but you can search by author (Owner), Gerrit project, branch, changesets
you've starred, etc. The Gerrit search documentation covers all of the dierent search operators you
can use.
The changeset has a few important elds, links and
buttons:
Reviewers. 'jenkins-bot' is the autoreviewer
that auto-veries anything that passes the
Jenkins tests. It will report a red or green mark
depending on whether the build passes.
Add reviewer. Manually pings someone to re- A Gerrit review screen with approval and veto options
quest their review. It'll show up in their Gerrit
dashboard.
Abandon Change button
Side-by-side di. Opens the di. You can
double-click on a line and comment on that
line, then save a draft comment! Then, click
Up to change to go back to the changeset,
proceed to .

on the Review page, additional Code

Review options to +2 (approve) or 2
(veto) a di, and a Publish And Submit button (publish your comment and
merge di into the branch, in 1 step)

Review (Add comment). Publish your

thoughts on the commit, including an overall
comment and/or inline comments you added
(see above).

Submit Patch Set 1 button (merge -only useful if you or someone else has already given a +2 approval to the di, but
not merged it)

If, upon code review, you approve, use

"+1 under Code Review; otherwise, use And once you've merged something into the
"1 to disapprove. These numbers are example Gerrit project you'll see it in https:

14

10

//gerrit.wikimedia.org/r/gitweb?p=test/mediawiki/
extensions/examples.git;a=summary .
If you merge a commit that references a ticket in Phabricator, please go to that ticket and mark it RESOLVED
and reference the merge ID.

SEE ALSO

Gits website with documentation

Pro Git book
MediaWiki Git Guide (MGG) - selection of relevant
Git pages in the MW Virtual Library
A very useful Git guide

Troubleshooting

Also useful (if you subtract away GitHub stu)

9.1

Problems
encountered
commit-msg hook

installing

If you encounter this error when trying to push changes

using git-review, you are not working with a repository
that was cloned via ssh. You must clone repositories using
ssh, not http or https, to succesfully push changes using
git-review.

9.2

Unable to negotiate with [IP]: no

matching key exchange method found.
Their oer: die-hellman-group1sha1

This message will appear if you are using openssh >= 7.0.
For more information, see task T112025.

10

See also

Also useful are these pages:

Git and gerrit in Wikimedia labs
An intro-to-git training mission
An introduction to git-svn for Subversion/SVK users
by Sam Vilain
GitMagic A git guide with translations
A git branching model
Git: the simple guide
Git Community Book will take you gently into Git
internals. (It is hard to get git until knowing something about how it works internally. After this, everything become simple, just hidden without convoluted and anti-productive user interface.)
How we're going to use Git slides by Brion Vibber,
as presented autumn 2011
Audio from Git presentation by Brion
Vibber, autumn 2011
Notes from Brion Vibbers presentation

https://gerrit.wikimedia.org/r/#q,status:open,n,z wikimedia bug list

Download from Git
labsconsole:Help:Access
Gerrit
Gerrit/git-review
Gerrit/Getting started
Gerrit/TortoiseGit tutorial
Wikimedia Gerrit Patch Uploader

15

11
11.1

Text and image sources, contributors, and licenses

Text

Gerrit/Tutorial Source: https://www.mediawiki.org/wiki/Gerrit/Tutorial?oldid=2057060 Contributors: Hashar, Wikinaut, Elvey, Skierpage, Purodha, Rogerhc, Turnstep, John Vandenberg, Mattaschen, Amire80, Cacycle, FunPika, Waldir, ^demon, Saper, Dereckson,
Wargo, GrafZahl, Peachey88, Valhallasw, Kaldari, He7d3r, Multichill, Matj Grabovsk, Aude, DrTrigon, Nemo bis, Whym, Xqt, GregRundlett, Giftpanze, Krinkle, Wizardist, *devunt, Ijon, Varnent, Awjrichards, RobLa-WMF, Steven (WMF), Niedzielski, Daniel Kinzler
(WMDE), Petrb, Sumanah, Yuvipanda, Qgil-WMF, Preilly, Van de Bugger, Wctaiwan, Base, , Shirayuki, Jamesmontalvo3, Krenair, MarkTraceur, Danielle Benoit, Leucosticte, KevinCole, SPage (WMF), UltrasonicNXT, Malyacko, Mattsmith321, Sharihareswara
(WMF), Florianschmidtwelzow, Bcharles, Cblair91, AKlapper (WMF), Suriyaa Kudo, Ckoerner, Glaisher, Wmdv, 01tonythomas, 5xbe,
Xue Fuqiao, Adi.iiita, Guymontag~mediawikiwiki, Tedsa, Firebus, Nuwanga82, Snailtsunami, Jonas.keutel, VEckl (WMF), MHolloway
(WMF), TJones (WMF), Dwlocks, JadeMaveric, Dhshzj and Anonymous: 27

11.2

Images

File:Apt-get_install_python-pip.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/a/a8/Apt-get_install_python-pip.png

License: CC-BY-SA-2.5 Contributors: ? Original artist: ?
File:Cat_id_rsa.pub.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/7/7e/Cat_id_rsa.pub.png License: PD Contributors:
? Original artist: ?
File:Chrome_diff_9332.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/0/0b/Chrome_diff_9332.png License: CC-BYSA-2.5 Contributors: ? Original artist: ?
File:Chrome_gerrit_9332.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/e/e5/Chrome_gerrit_9332.png License: CCBY-SA-2.5 Contributors: ? Original artist: ?
File:Chrome_gerrit_9332_2.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/9/94/Chrome_gerrit_9332_2.png License:
CC-BY-SA-2.5 Contributors: ? Original artist: ?
File:Chrome_review_9332.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/3/38/Chrome_review_9332.png License:
CC-BY-SA-2.5 Contributors: ? Original artist: ?
File:Gerrit.svg Source: https://upload.wikimedia.org/wikipedia/mediawiki/a/a7/Gerrit.svg License: PD Contributors: ? Original artist: ?
File:Git_clone.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/d/d0/Git_clone.png License: PD Contributors: ? Original
artist: ?
File:Git_commit.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/d/d9/Git_commit.png License: PD Contributors: ?
Original artist: ?
File:Git_commit_amend.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/8/82/Git_commit_amend.png License: PD
Contributors: ? Original artist: ?
File:Git_commit_vim.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/f/f6/Git_commit_vim.png License: PD Contributors: ? Original artist: ?
File:Git_config_-l.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/d/de/Git_config_-l.png License: CC-BY-SA-2.5
Contributors: ? Original artist: ?
File:Git_config_email_and_username.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/0/0c/Git_config_email_and_
username.png License: CC-BY-SA-2.5 Contributors: ? Original artist: ?
File:Git_diff.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/b/b2/Git_diff.png License: ? Contributors: ? Original artist:
?
File:Git_diff_--cached.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/c/c0/Git_diff_--cached.png License: ? Contributors: ? Original artist: ?
File:Git_pull_origin_master.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/4/43/Git_pull_origin_master.png License:
PD Contributors: ? Original artist: ?
File:Git_rebase_master.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/9/9a/Git_rebase_master.png License: PD Contributors: ? Original artist: ?
File:Git_remote_update.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/f/f6/Git_remote_update.png License: PD Contributors: ? Original artist: ?
File:Git_review_-R.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/9/95/Git_review_-R.png License: PD Contributors:
? Original artist: ?
File:Git_review_-R_2.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/b/b4/Git_review_-R_2.png License: PD Contributors: ? Original artist: ?
File:Git_review_-d_9332.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/9/99/Git_review_-d_9332.png License: PD
Contributors: ? Original artist: ?
File:Git_review_-s.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/2/26/Git_review_-s.png License: CC-BY-SA-2.5
Contributors: ? Original artist: ?
File:Git_status.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/d/de/Git_status.png License: PD Contributors: ? Original
artist: ?
File:Git_status_2.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/8/8f/Git_status_2.png License: PD Contributors: ?
Original artist: ?

16

11

TEXT AND IMAGE SOURCES, CONTRIBUTORS, AND LICENSES

File:Maitre_du_feu.jpg Source: https://upload.wikimedia.org/wikipedia/commons/9/95/Maitre_du_feu.jpg License: CC BY-SA 2.5

Contributors: No machine-readable source provided. Own work assumed (based on copyright claims). Original artist: No machine-readable
author provided. Jrpac~commonswiki assumed (based on copyright claims).
File:Pip_install_git-review.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/b/b4/Pip_install_git-review.png License:
CC-BY-SA-2.5 Contributors: ? Original artist: ?
File:Screen_Shot_2012-05-25_at_10.39.36_AM.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/b/b1/Sudo_apt-get_
install_git-core.png License: PD Contributors: ? Original artist: ?
File:Ssh-keygen_-t_rsa_-C_\char"0022\relax{}your_email@youremail.com.png Source: https://upload.wikimedia.org/wikipedia/
mediawiki/a/a8/Ssh-keygen_-t_rsa_-C_%22your_email%40youremail.com%22.png License: PD Contributors: ? Original artist: ?
File:Vim_example.body_file.png Source:
cense: ? Contributors: ? Original artist: ?

https://upload.wikimedia.org/wikipedia/mediawiki/2/28/Vim_example.body_file.png Li-

File:Vim_git_commit_amend.png Source: https://upload.wikimedia.org/wikipedia/mediawiki/3/3c/Vim_git_commit_amend.png License: PD Contributors: ? Original artist: ?

11.3

Content license

Creative Commons Attribution-Share Alike 3.0