Gerrit/Tutorial

This is a tutorial how to use Git and Gerrit for MediaWiki development. It includes explanations. For a very short how-to guide, see Gerrit/Getting started instead.

This tutorial explains how to:

• set up and configure Git on your machine (to check out code repositories)
• set up Gerrit access (for code review)
• install git-review (to propose patches for code review)
• submit a patch (changeset) for review
• understand the MediaWiki code review process (commit, review, merge)

For power users, Gerrit/Advanced usage has additional documentation.

What is Git?

Play media

Git Basics #1: What is a Version Control System (VCS)?

Git is a free and open source distributed version control system. It is written in C originally developed by Linus Torvalds and others to manage the Linux kernel. “Distributed” means that there is no central copy of the repository. With Subversion (which was used by Wikimedia before moving to Git), Wikimedia’s servers host the repository and users commit their changes to it. In contrast, with Git, once you’ve cloned the repository, you have a fully functioning copy of the source code, with all the branches and tagged releases at your disposal.

What is Gerrit?

Gerrit is a free, web-based collaborative code review tool that integrates with Git. It is written in Java (Java EE Java Servlet) and has been developed at Google by Shawn Pearce for the development of the Android project.

Setting up Git

Play media

Git Basics #2: What is Git?

These instructions explain how to install Git as a command-line (terminal window) tool. If you prefer a graphical user interface (GUI) check the list of clients maintained by the Git project. For alternate installation instructions look here, or here.

Installation

Linux & UNIX

Installing git on Ubuntu

Using the graphical software package management tool of your Linux distribution to install Git is recommended.

If you prefer using the command line in a terminal:

• Debian/Ubuntu: sudo apt-get install git
• Fedora: dnf install git (or yum install git on Fedora≤21 and CentOS)
• 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
• OpenBSD: pkg_add git
• Solaris 11 Express: pkg install developer/versioning/git
• Mageia: urpmi git

For other Linux distributions please check your vendor documentation.

Windows

Install Git + MSys (Minimal Bash for Windows) from 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.

OS X

Install one of the following:

• Homebrew package manager: brew install git – Recommended, simple updating and easy installing of other packages
• Standalone: Git for Mac

Configure Git

Play media

Git Basics #3: Get Going

Now that you have Git installed, it’s time to configure your personal information. You should have to do these things only once; they’ll stick around between upgrades. You can also change them at any time by running through the commands again.

Git comes with a tool called git config that lets you get and set configuration variables that control all aspects of how Git looks and behaves. To see your current configuration use the "list" -l option:

git config -l

Example:

preilly@vumi:/mw/core$ git config -l
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
remote.origin.url=https://gerrit.wikimedia.org/r/p/mediawiki/core.git
branch.master.remote=origin
branch.master.merge=refs/heads/master
remote.gerrit.url=ssh://preilly@gerrit.wikimedia.org:29418/mediawiki/core.git
remote.gerrit.fetch=+refs/heads/*:refs/remotes/gerrit/*
preilly@vumi:/mw/core$

Set your username and email

Git tracks who makes each commit by checking the user’s name and email. In addition, this info is used to associate your commits with your Gerrit account. To set these, enter the two commands below by replacing the name and email address with your own.

 git config --global user.email "example@example.com"
 git config --global user.name "example"

Example:

preilly@vumi:/mw/core$ git config --global user.email "preilly@wikimedia.org"
preilly@vumi:/mw/core$ git config --global user.name "preilly"
preilly@vumi:/mw/core$ git config -l
user.email=preilly@wikimedia.org
user.name=preilly
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
remote.origin.url=https://gerrit.wikimedia.org/r/p/mediawiki/core.git
branch.master.remote=origin
branch.master.merge=refs/heads/master
remote.gerrit.url=ssh://preilly@gerrit.wikimedia.org:29418/mediawiki/core.git
remote.gerrit.fetch=+refs/heads/*:refs/remotes/gerrit/*
preilly@vumi:/mw/core$

Set Up SSH Keys in Gerrit

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 following commands in a terminal. For alternate instructions, see 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 files in your .ssh directory (if you have one):

ls ~/.ssh

If you see a file called id_rsa.pub here, you may skip right to #Add your SSH key.

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 file in which to save the key, just press enter.

Output of the ssh-keygen command

ssh-keygen -t rsa -C "your_email@youremail.com"

Assign a memorable passphrase and press [enter].

Why do passphrases matter?

Passwords aren’t very secure. If you use one that’s easy to remember, it’s easier to guess or brute-force (try many options until one works). If you use one that’s random it’s hard to remember, and thus you’re more inclined to write the password down. Both of these are Very Bad Things™. This is why you’re using ssh keys.

But using a key without a passphrase is basically the same as writing down that random password in a file 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 don’t want to enter a long passphrase every time I use the key!

Neither do we! Thankfully, there’s a tool called ssh-agent that can save your passphrase securely so you don’t have to re-enter it. If you’re on Mac OS X Leopard or later or recent Linux distributions your keys can be saved in the system’s keychain to make your life even easier.

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

~/.ssh/id_rsa : identification (private) key
~/.ssh/id_rsa.pub : public key

Add your SSH key

Open your public key file, (e.g. id_rsa.pub) with a text editor (Notepad, TextEdit, or gedit will do just fine). You may need to turn on “View hidden files” to find it because the .ssh directory is hidden. It’s important you copy your SSH key exactly as it is written without adding any newlines or whitespace. Copy the full text, including the "ssh-rsa" prefix, the key itself, and the email address suffix.

On a Linux system you can use the following:

cat ~/.ssh/id_rsa.pub

If you cannot view hidden files, there are other ways to copy:

Linux:

sudo apt-get install xclip # Downloads and installs xclip
xclip -sel clip < ~/.ssh/id_rsa.pub

Windows:
You can open Git GUI, go to Help > Show Key, and then press Copy To Clipboard to copy your public key to your clipboard.

Mac OS X:

pbcopy < ~/.ssh/id_rsa.pub # Copies the contents of the id_rsa.pub file to your clipboard

Add SSH key to your Gerrit account

• Create a Wikimedia developer account at wikitech.wikimedia.org if you do not yet have one. Your account's username and password will be the same for Gerrit.
• Log into the web interface for Gerrit.
• Click on your username in the top right corner, then choose "Settings".
• Click "SSH Public keys" in the menu on the left.
• Paste your SSH Public Key into the corresponding field.

Alternately, once logged in, use these direct links to add your public key to Gerrit and wikitech.

Add SSH key to use with Git

Start Git Bash.

• Get ssh-agent running using

eval `ssh-agent`

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

• Add your private key to the agent (use path to your private key file)

ssh-add .ssh/id_rsa

if the key is in the default location, use ssh-add ~/.ssh/id_rsa

Key should be in OpenSSH format (.ppk keys can be exported to this format in PuTTyGen).

• Run ssh. (Do be paranoid and check for the matching SSH fingerprint for gerrit.wikimedia.org:29418 when logging in for the first time.). In addition, <USERNAME> should also match what is on your gerrit settings in order not to get "Permission denied (publickey)" error when you've configured everything correctly.

NOTE: Make sure to double check the <USERNAME> from your Gerrit settings. If this persist, see Gerrit/Troubleshooting to further check what could be wrong.

ssh -p 29418 <USERNAME>@gerrit.wikimedia.org

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. An example Gerrit SSH connection success message would look like:

Example:

preilly@vumi:/mw/core$ ssh -p 29418 preilly@gerrit.wikimedia.org -4
The authenticity of host '[gerrit.wikimedia.org]:29418 ([208.80.154.85]:29418)' can't be established.
RSA key fingerprint is dc:e9:68:7b:99:1b:27:d0:f9:fd:ce:6a:2e:bf:92:e1.
Are you sure you want to continue connecting (yes/no)? yes
Warning permanently added '[gerrit.wikimedia.org]:29418 ([208.80.154.85]:29418)' (RSA) to the list of known hosts.
Enter passphrase for key '/home/preilly/.ssh/id_rsa':

  ****    Welcome to Gerrit Code Review    ****

  Hi preilly, you have successfully connected over SSH.

  Unfortunately, interactive shells are disabled.
  To clone a hosted Git repository, use:

  git clone ssh://preilly@gerrit.wikimedia.org:29418/REPOSITORY_NAME.git

Connection to gerrit.wikimedia.org closed.

preilly@vumi:/mw/core$

Download code using Git

Let's practice downloading the Examples extension. Run the following on the Git Bash command line:

git clone ssh://<USERNAME>@gerrit.wikimedia.org:29418/mediawiki/extensions/examples

(Substitute <USERNAME> by your Gerrit username. And make sure the URL begins with ssh: and not https:).

This will copy the entire history and the code base of the "Examples" extension repository onto your machine. You will have a working directory of the extension's main branch. If you enter the new directory, you can look at the code and start editing it.

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 different, you can just put it at the end of the command, after the URL.

Obviously, just cloning the Examples extension will not give you a development environment setup or a running MediaWiki installation. (Running will require MediaWiki Core and placing the code you checked out in a location expected by your web server.)

You can download MediaWiki Core using Git, as well as the source code of any project repository hosted at gerrit.wikimedia.org (the Wikimedia Foundation server cluster).

For example, to clone the mediawiki-core repository or the repository of an extension which you are interested in:

git clone ssh://<USERNAME>@gerrit.wikimedia.org:29418/mediawiki/core.git

git clone ssh://<USERNAME>@gerrit.wikimedia.org:29418/mediawiki/extensions/<EXTENSION>.git

(Substitute <USERNAME> by your Gerrit username and <EXTENSION> by the extension name.)

You can also copy this git command from the top of the project's home page in Gerrit.

Even after executing these commands, you may experience later errors in installing the Vagrant virtual machine, for which these instructions must be followed to download the additional MediaWiki dependencies using composer, a PHP package management system, for MediaWiki versions ≥ 1.25.

Prepare to work with Gerrit

Main article: Gerrit/git-review

Your commit message needs a "change ID" in order to work with Gerrit. You can see these in the git log for a project and if you browse changes on Gerrit, they look like Change-Id: Ibd3be19ed1a23c8638144b4a1d32f544ca1b5f97 starting with an I (capital i)). Each time you amend a commit in response to Gerrit feedback git gives it a new commit ID, but because this change ID stays the same Gerrit will keep track of it as a new "patch set" addressing the same change.

There's a git add-on called git-review that adds a Change-ID line to your commits and manages other aspects of using Gerrit. Using git-review is recommended as makes it easier to configure your Git clone, to submit a change or to fetch an existing one.

Installing git-review

For more details, please see Gerrit/git-review#Installation.

Linux & UNIX

Using the graphical software package management tool of your Linux distribution to install git-review is recommended.

If git-review has not been packaged by your distribution, check Gerrit/git-review#Linux for other options such as installing git-review by using the pip Python package installer.

On FreeBSD, install git-review through ports.

Windows

In Windows, please see Gerrit/git-review#Windows.

OS X

For OS X 10.11 El Capitan, follow Gerrit/git-review#Method 2.

On versions of OS X prior to 10.11, use the pip Python package installer by following Gerrit/git-review#Method 1.

Configuring git-review

Git is a distributed version control system; it's possible to fetch code from one host, push your changes to another, and submit them to a third for Gerrit code review. It's a lot simpler to work with one "remote" for all three. Since Git's default remote name is "origin" and most guides on the web use that name, let's tell git-review to use this as well. Replace myusername with the name next to 'Username' at https://gerrit.wikimedia.org/r/#/settings/ .

git config --global gitreview.remote origin
git config --global gitreview.username myusername

Note: Older versions of git-review used a separate config file:.config/git-review/git-review.conf (in Windows, the file is %USERPROFILE%\.config\git-review\git-review.conf) and add these two lines:

## Deprecated!
[gerrit]
defaultremote = origin

Setting up git-review

After cloning a repository, you need to set it up for 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. Make sure that you are in the directory of the project that you cloned (otherwise you will get an error "fatal: Not a git repository"). Then enter

git review -s

which should give you this:

Example:

preilly@vumi:/mw/core$ git review -s
The authenticity of host '[gerrit.wikimedia.org]:29418 ([208.80.154.85]:29418)' can't be established.
RSA key fingerprint is dc:e9:68:7b:99:1b:27:d0:f9:fd:ce:6a:2e:bf:92:e1.
Are you sure you want to continue connecting (yes/no)? yes
Creating a git remote called "gerrit" that maps to:
  ssh://preilly@gerrit.wikimedia.org:29418/mediawiki/core.git
preilly@vumi:/mw/core$

If you see "the authenticity of host gerrit.wikimedia.org can't be established..." Don’t worry, this is supposed to happen the first time. Type "yes".

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

How to submit a patch

For a brief overview see Gerrit/Getting started.

The main avenue for submitting changes to MediaWiki code is to first join the MediaWiki development community so you can submit changes to Gerrit, our code review tool.

Make sure that you cloned the code repository that you are interested in (see #Download code using Git) and that you are in that directory.

 Note: You will have to probably clone mediawiki-core to your development server's DocumentRoot directory, which is set to /var/www/html/ in most Apache web server installations. This can vary according to your web server software and version. Cloning directly to your DocumentRoot might not be permitted if you are a non-privileged user. You can create a directory inside your DocumentRoot and make it writeable by using the chmod command in Linux. Badly configured permissions can expose your development server to potential security risks.

Update master

Make sure that your master branch (the branch created when you initially cloned the repository) is up to date:

git pull origin master

Example:

preilly@vumi:/mw/examples$ git pull origin master
From https://gerrit.wikimedia.org/r/p/test/mediawiki/extensions/examples
 * branch            master     -> FETCH_HEAD
Already up-to-date.
preilly@vumi:/mw/examples$

However, note that a few repositories use different terms (for example operations/puppet has a "production" instead of a "master" branch).

Create a branch

First, create a local branch for your new change. Give the branch a short but reasonably descriptive name (e.g. T1234, bug/1234, cleanup/some-thing, or badtitle-error). Keep in mind that other people will also use this name to identify your branch when they're reviewing your patch.

git checkout -b BRANCHNAME origin/master

Example:

user@example:~/dev/mw$ git checkout -b badtitle-error origin/master
# Switched to a new branch 'badtitle-error'
user@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

git branch BRANCHNAME --track origin/master
git checkout BRANCHNAME

Make and commit your change

Usual way

Play media

"git diff" - Git Foundations

Modify your local code in some fashion. Using your preferred editor, modify the file Example/Example.body.php

Then check the changes you've made, within the file(s) and within the directory:

git diff

Without any extra arguments, a simple git diff will display in unified diff 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 file(s) and within the directory:

git status

You run git status to see if anything has been modified and/or staged since your last commit so you can decide if you want to commit a new snapshot and what will be recorded in it.

This will show all modified files. To prepare submitting a file, you should add your changes to the index (the staging 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 pass a file to git add when you want the changes you made to it to be included in your next commit.

Any files you've changed that are not staged by you doing git add will be left alone - this means you can craft your commits with a bit more precision.

At any time you can always review the changes already added to the staging area by running git status, and look at the diff with git diff --cached:

The git diff --cached command will show you what contents have been staged. That is, this will show you the changes that will currently go into the next commit snapshot.

Once you are happy with the change list, you can add them to your local repository by using

git commit

ExampleExtension/.git/COMMIT_EDITMSG:

Short subject line

More details. The blank line between the subject and body is
mandatory. The subject line is used to represent the commit in
code-review e-mails, search results, git-rebase, and more.

Bug: T54321
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date:      Sun Aug 14 17:51:50 2016 +0530
#
# On branch review/yourname/shiftToContentHandler
# Changes to be committed:
#       modified:   Newsletter.hooks.php
#       modified:   extension.json
#       modified:   includes/Newsletter.php
#       modified:   includes/NewsletterDb.php
#       modified:   includes/NewsletterEditPage.php
#       modified:   includes/NewsletterStore.php
#       new file:   includes/content/NewsletterContent.php
#       new file:   includes/content/NewsletterContentHandler.php

You will then be prompted in an editor to add a descriptive message for this commit message, following Commit message guidelines. This is what other people will see when you will later push that commit to another repository.

 Note: Normally, you do not manually add a Change-Id and it will be added in automatically once you exit the commit screen. Please see that you give the bug id correctly with the single spacing in between Bug: <id_here> as given in the above example.

Example:

preilly@vumi:/mw/examples$ git commit
[2012/bug12345 3048aa4] Added get version method to extension
 1 files changed, 7 insertions(+), 0 deletions(-)
preilly@vumi:/mw/examples$

You can repeat this step over and over until you have a set of changes that you want to have pushed to the master branch. One of the cool things about git is that when you git commit, you are committing to your local copy. This means you can commit as often as you like without potentially screwing things up for another developer on the project, unlike in SVN where you would want to be very careful that the changes you commit would not cause things to break.

Hence the workflow is something like:

 # Add change:
 git add <some file>
 # Verify list of files added to the staging area
 git status
 # Review diff of changes staged:
 git diff --cached
 # repeat until you are happy with your changes
 git commit
 <edit commit message>
 git show
 # check what would be pushed to Gerrit

Ensure that your commit message follow the guidelines mentioned at Gerrit/Commit message guidelines.

Prepare to push your change set to Gerrit

Before your changes can be merged into master, they must undergo review in Gerrit.

But first, it's a good idea to synchronize your change set with any changes that may have occurred in master while you've been working ("rebasing"). From within the branch you've been working on, execute the following command:

git pull --rebase origin master

Example:

preilly@vumi:/mw/examples$ git pull origin master
From https://gerrit.wikimedia.org/r/p/test/mediawiki/extensions/examples
 * branch            master     -> FETCH_HEAD
Already up-to-date.
preilly@vumi:/mw/examples$ git rebase master
Current branch 2012/bug12345 is up to date.
preilly@vumi:/mw/examples$

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 conflicts. Plus, it gives you an opportunity to test your changes against the latest code in master.

Once you are satisfied with your change set and you've rebased against master, you are ready to push your code to Gerrit for review. If you made several related commits, consider merging them into one single commit for review.

Push your change set to Gerrit

It is recommended to use git-review to submit patches for review. If you do not have installed git-review and do not want to do so, you can use the Gerrit patch uploader to submit your patch.

If you installed git-review and you ran git review -s to set it up for this repository, the command to push changes to Gerrit is very simple:

git review -R

The -R option tells git-review not to perform a rebase before submitting the change to Gerrit.

Example:

preilly@vumi:/mw/examples$ git review -R
remote: Resolving deltas: 100% (3/3)
remote:
remote: New Changes:
remote:   https://gerrit.wikimedia.org/r/9332
remote:
To ssh://preilly@gerrit.wikimedia.org:29418/test/mediawiki/extensions/examples.git
 * [new branch]      HEAD -> refs/publish/master/2012/bug12345
preilly@vumi:/mw/examples$

Upon success, you'll get a confirmation and a link to the changeset in Gerrit.

New patchset: preilly; "Added get version method to extension" [test/mediawiki/extensions/examples] (master) - https://gerrit.wikimedia.org/r/9332

View the Change / Next Steps

You can view this change in the Gerrit Web UI:

If you want to see your changed files in their context then click on the (diffusion) link (you then will see).

If your commit addresses a ticket in Phabricator, a comment will be automatically added in the Phabricator task if you followed the Commit message guidelines. If you did not, you could manually add a comment on that Phabricator ticket by linking to its changeset in Gerrit.

Note that Gerrit's diff algorithm (jGit) is slightly different from git's default diff algorithm. Hence the differences displayed by Gerrit might not look like the differences displayed by Git on your machine.

Other common situations

Also see Gerrit/Advanced usage if your situation is not covered here.

Squash several commits into one single commit via rebase

If you made several related commits to your local repository prior to wanting to submit for review, you should squash (merge) those commits into one single commit.

The --interactive or -i option allows you to change (rewrite) your commit history. For each commit, you can modify and change the commit message, add or remove files, or perform other modifications.

First you need to tell git how far back you want to pull. To get a list of all changes in your branch:

git rebase -i origin/master

You can also limit the displayed list of recent changes. HEAD~3 means pull the last three commits:

git rebase -i HEAD~3

After you type this command, your text editor will display your commits in reverse order and a list of available commands:

Example:

pick aa8cf1d Adding method customFilterFunctionGetRiskyCountryCodeScore() to GatewayAdapter.
pick 38828e2 Adding $wgDonationInterfaceCustomFiltersFunctionsRiskyCountries to donationinterface.php
pick be33007 Fix a typo

# Rebase 95ccd28..be33007 onto 95ccd28
#
# Commands:
#  p, pick = use commit
#  r, reword = use commit, but edit the commit message
#  e, edit = use commit, but stop for amending
#  s, squash = use commit, but meld into previous commit
#  f, fixup = like "squash", but discard this commit's log message
#  x, exec = run command (the rest of the line) using shell
#
# If you remove a line here THAT COMMIT WILL BE LOST.
# However, if you remove everything, the rebase will be aborted.
#

Since we only want to send one commit to review, we will squash the last two commits into the first. Hence change all but the first "pick" to "squash":

pick aa8cf1d Adding method customFilterFunctionGetRiskyCountryCodeScore() to GatewayAdapter.
squash 38828e2 Adding $wgDonationInterfaceCustomFiltersFunctionsRiskyCountries to donationinterface.php
squash be33007 Fix a typo

When you finished picking and squashing and saved the file, another file will open in your text editor to allow you get to edit and merge your commit messages. Be careful to only keep one of the Change-Id lines and have it be at bottom of the message after one empty line.

Your messages from your previous commits will automatically be placed in this message:

Example:

# This is a combination of 3 commits.
# The first commit's message is:
(mingle-fr-2012-69) Adding a custom filter for risky countries.

Adding method customFilterFunctionGetRiskyCountryCodeScore() to GatewayAdapter.

# This is the 2nd commit message:

Adding $wgDonationInterfaceCustomFiltersFunctionsRiskyCountries to donationinterface.php

# This is the 3rd commit message:

Fix a typo

Change-Id: I33e44ec0d93628d9a53c15e08eb89f352b7d5fe0

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# Not currently on any branch.
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   donationinterface.php
#       modified:   gateway_common/gateway.adapter.php
#

Remember to put your (updated) summary message in the commit. In this case the new summary message will be:

(mingle-fr-2012-69) Adding a custom filter for risky countries.

 Note: In regards to which Change-Id you want to use, squashing a commit into an existing commit (one that's already in Gerrit), you need to pick the Change-Id that belongs to the one you meant to submit a new patchset for (the surviving commit). If your commits are new and are not in Gerrit, it does not matter which Change-Id you choose.

If all goes well, you should see a successful rebase message:

Example:

[detached HEAD 02f5e63] (mingle-fr-2012-69) Adding a custom filter for risky countries.
 2 files changed, 92 insertions(+), 3 deletions(-)
Successfully rebased and updated refs/heads/mingle-fr-2012-69.

Afterwards, submit your patch for review:

git review

You should see a message like this showing your git review went to Gerrit (in this example, to https://gerrit.wikimedia.org/r/7187 ):

Example:

remote: Resolving deltas: 100% (4/4)
remote: (W) 02f5e63: commit message lines >70 characters; manually wrap lines
remote: 
remote: New Changes:
remote:   https://gerrit.wikimedia.org/r/7187
remote: 
To ssh://jpostlethwaite@gerrit.wikimedia.org:29418/mediawiki/extensions/DonationInterface.git
 * [new branch]      HEAD -> refs/for/master/mingle-fr-2012-69

Amending a change (your own or someone else's)

BEWARE: git review -d performs a hard reset that destroys all local changes. Stash or commit changes you wish to preserve first.

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. It's 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 Gerrit's 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:

git checkout <branch name>

For example:

git review -d 9332

Example:

preilly@vumi:/mw/examples$ git review -d 9332
Downloading refs/changes/32/9332/1 from gerrit into review/preilly/2012/bug12345
Switched to branch 'review/preilly/2012/bug12345'
preilly@vumi:/mw/examples$

Or, if you already have the branch,

git checkout review/preilly/2012/bug12345

Should accomplish the same thing.

Making changes in the "vim" text editor

Next, make some changes.

vim Example/Example.body.php

git add the files as needed, then commit the change (ensuring you are amending the commit):

git add Example/Example.body.php
git commit --amend --all

Example:

preilly@vumi:/mw/examples$ git add Example/Example.body.php
preilly@vumi:/mw/examples$ git commit --amend
[review/preilly/2012/bug12345 7b7840b] Added get version method to extension
 1 files changed, 7 insertions(+), 0 deletions(-)
preilly@vumi:/mw/examples$

NOTE: DO NOT use the -m flag to specify a commit summary: that will override the previous summary and regenerate the Change-Id. Instead, use your text editor to change the commit summary (in the file .git/COMMIT_EDITMSG if needed, and keep the Change-Id line intact.

Push the change

git review -R

The -R is important here. It tells git-review to not rebase your change against master, which clutters diffs between patch set 1 and 2.

Example:

preilly@vumi:/mw/core$ git review -R
remote: Resolving deltas: 100% (3/3)
To ssh://preilly@gerrit.wikimedia.org:29418/test/mediawiki/extensions/examples.git
 * [new branch]      HEAD -> refs/publish/master/2012/bug12345
preilly@vumi:/mw/examples$

New patchset: preilly; "Added get version method to extension" [test/mediawiki/extensions/examples] (master) - https://gerrit.wikimedia.org/r/9332

Push to a branch different than master

In the screenshots above, the commit was pushed to the master branch. The branch name only appeared as the topic of the commit in the Gerrit UI. If you really want to push to a different branch than master, you have to push via git review <branch name>.

Editing via the web-interface

If you're logged in to Gerrit, you can also edit within the web-interface. This can be useful for making small patches, or for non-developers to contribute small fixes.

1. Go to https://gerrit.wikimedia.org/r/#/admin/projects/foo (e.g. https://gerrit.wikimedia.org/r/#/admin/projects/mediawiki/extensions/Echo )
   • (perhaps via the mw:Extension:Foo page, using the "code review" link in the infobox, and then the click the project name in the list of past patches, and then "General" in the toolbar.
2. Click "Create Change"
3. Set branch to "master" (if you don't want to use master branch you can use the other branches available for that project)
4. Set the topic to something of your choosing (e.g. "copy-edit" - must be all-one-string) (optional)
5. Write a description ("commit summary") in the big text field, with:
   1. a one-line summary (This will be the commit title. It should be self-explanatory giving full context for the change, like a good edit-summary. It should Not end with a fullstop.)
   2. a blank line
   3. a more detailed paragraph (optional, if desired)
   4. "Bug: Txxxx" (Must be a capital "B" and with space after the colon)
   • See example
6. Click "Edit"
7. Click "Add"
8. Type the folder/file path for the file you wish to edit (e.g. i18n/en.json)
9. Find the line(s) you want to change, and change them.
10. Click "Save"
11. Click "Close"
12. Click "Publish edit"
13. Click "Publish"

Done!

If you need to change the commit summary, you can use these steps:

1. Click "Commit Message"
2. Press "e"
3. Fix things.
4. Click "Save"
5. Click "Close"
6. Click "Publish edit"

How code is reviewed in Gerrit

Code review is an essential part of our contribution workflow. 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.

Review before merge

It's important to us to have a review-before-merge workflow for MediaWiki core and also for any extension we deploy. We will also offer 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.

Who can review? Gerrit project owners

After creating a Gerrit account, anyone can comment on commits and signal their criticisms and approvals. Anyone can give a nonbinding "+1" to any commit. However, for any given repository ("Gerrit project"), only a small group of people will have the ability to approve code within Gerrit and merge it into the repository. This superapproval is a "+2" even though that's a misleading name, because two +1 approvals DO NOT add up to a +2. These people are "Gerrit project owners". Learn about becoming a Gerrit project owner.

Even within a Gerrit project, we can also specify particular branches that only specific people can pull into.

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

A freshly uploaded sample changeset

Side-by-side diff

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 preserving.

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 #mediawiki^connect for someone to help.
• Log in to Gerrit. If you know the changeset you want to look at (URL will look like https://gerrit.wikimedia.org/r/#/c/23939/ ), go to that. Otherwise, use the search box and try searching. You can search by author ("Owner"), Gerrit project, branch, changesets you've starred, etc. The Gerrit search documentation covers all of the different search operators you can use.
• The changeset has a few important fields, links and buttons:
  • Reviewers. 'jenkins-bot' is the autoreviewer that auto-verifies anything that passes the Jenkins tests. It will report a red or green mark depending on whether the build passes.
  • Reviewers: Add…. Manually pings someone to request their review. It'll show up in their Gerrit dashboard.
  • Files: Open All. Opens the diff (each file in a separate browser tab). You can double-click on a line and then press C to comment on that line, then save a draft comment! Then, click the green "Up to change" arrow to go back to the changeset, and click "Reply…" to publish your comment.
  • Reply… ("Add comment"). Publish your thoughts on the commit, including an overall comment and/or inline comments you added (see above).
    • If, upon code review, you approve, use "+1" under "Reply…"; otherwise, use "-1" to disapprove. These numbers are nonbinding, won't cause merges or rejections, and have no formal effect on the code review.
  • Abandon (you'll see this if you wrote this diff). This action removes the diff from the merge queue, but leaves it in Gerrit for archival purposes.

Comparing patch sets

Every time you amend your commit and submit it for review, a new patch set is created. You can compare the different patch sets like this:

• Under Files, select either Open All or choose a specific file listed to open that file.
• On the left side under Patch Set, Base is preselected. On the right of the screen under Patch Set, the latest patch set is preselected. Adjust the selected patch sets to your needs.

Formally reviewing and merging or rejecting code

If you are one of the Gerrit project owners, you'll also see:

• Abandon button
• under Reply, additional Code-Review options to +2 (approve) or -2 (veto) a diff, and a Post button (publish your comment and merge diff into the branch, in 1 step)
• Submit button (merge -- only useful if you or someone else has already given a +2 approval to the diff, but not merged it)

And once you've merged something into the example Gerrit project you'll see it in https://gerrit.wikimedia.org/r/gitweb?p=test/mediawiki/extensions/examples.git;a=summary .

If you merged a commit that references a ticket in Phabricator, please go to that task and change its status to "Resolved" (and reference the merge ID if gerritbot has not already posted it).

Troubleshooting

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

See also

Also useful are these pages:

• Download from Git
• wikitech:Help:Getting Started
• Gerrit
  • Gerrit/git-review
  • Gerrit/Getting started
  • Gerrit/TortoiseGit tutorial
• Wikimedia Gerrit Patch Uploader
• MediaWiki Git Guide (MGG) - selection of relevant Git pages in the MediaWiki Virtual Library
• Official Gerrit documentation
• Git and Gerrit FAQ

Third party guides to Git

• An intro-to-git "training mission"
• Try Git (interactive demo)
• 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.)
• Git's website with documentation
  • Pro Git book
• Git video tutorials on Wikimedia Commons
• Another useful OpenStack Git guide (if you subtract away GitHub stuff)
• Understanding the Git Workflow by Benjamin Sandofsky
• Using Git in Eclipse
• Why to fetch/merge instead of pull by Mark Longair

Historical documents

• An introduction to git-svn for Subversion/SVK users by Sam Vilain
• Git for Subversion users by IBM
• 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 Vibber's presentation

If as a Ubuntu user you have a "Permission denied (publickey)" message, please check on this help page