If you only want to play with Gerrit and do not want to write a patch for a "real" Wikimedia software project, use our Gerrit test instance instead.

In this tutorial, commands to enter start with a dollar sign in a box, like this: command.
Do not enter the $ prefix.If a command also include a variable which you must to change yourself, then the variable is shown in red: command variable.

What is Gerrit?

Gerrit is a free, web-based collaborative code review tool that integrates with Git.

Basically: You submit your proposed software change (often called "patch", in Gerrit called "changeset") as a new branch.
If the first version ("patchset 1") is not yet perfect, you can make more changes ("amend") in that branch ("patchset 2", etc).
Once a patchset receives a "+2" review, it will get accepted and merged into the main branch of the code repository (usually called "master").
Merging means that your change is included by default when anyone checks out or downloads that code repository.

Configure Git

Now that you have Git installed, it’s time to configure your personal information.
You should have to do this only once. You can also change your personal information at any time by running these commands again.

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.

Enter the two commands below to set your username and email address. Replace gerrituser with your own Gerrit username and replace gerrituser@example.com with your own email address:

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

git config --global user.name "gerrituser"

Note: To see your current configuration variables which control how Git behaves, use git config -l.

Set Up SSH Keys in Gerrit

We use an SSH key to establish a secure connection between your computer and Gerrit. To make sure whether you need to generate a brand new key, let's check if an SSH key already exists on your system. Run this command in a terminal:

ls ~/.ssh

The command will list the files that are in the (hidden) .ssh directory. If the directory already exists on your system and if the output lists a file called id_rsa.pub, then you can go directly to #Copy your SSH Public key.

Generate a new SSH key

To generate a new SSH key, enter the command below and replace gerrituser@example.com with your own email address. We want the default settings so when asked to enter a file in which to save the key, just press enter.

Passwords aren’t very secure. If you use one that’s easy to remember, it’s easier to guess or brute-force. If you use one that’s random it’s hard to remember, so you might write the password down. Both are very bad. This is why you’re using ssh keys. But using an ssh 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. That's why you also add a passphrase. To not enter a long passphrase every time you use the key, there’s a tool called ssh-agent. It can save your passphrase securely. If you use macOS or Linux, then your keys can be saved in the system’s keychain to make your life even easier.

The ssh-keygen command will create 2 files in ~/.ssh directory:

~/.ssh/id_rsa : your private SSH key (for identification)

~/.ssh/id_rsa.pub : your public SSH key

Copy your SSH Public key

Get the content of your public key file (e.g. id_rsa.pub) to copy it to your clipboard:

One option is to open your public key file with your favorite text editor (Notepad, TextEdit, gedit, etc). In the file chooser dialog of your text editor, you may need to turn on “View hidden files” to find the file, because the .ssh directory is hidden. Sometimes the “View hidden files” option is available by right-clicking in the file chooser dialog.

Other options are:

On Linux, run cat ~/.ssh/id_rsa.pub and manually copy the output to the clipboard.

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

On macOS, you can run pbcopy < ~/.ssh/id_rsa.pub to copy the contents of the your public key file to your clipboard.

It’s important you copy your SSH Public 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.

Add SSH Private key to use with Git

Be sure to use the accent `, not the single quote '. (You could copy and paste from this page if you cannot easily enter this special character.)

Add your private key to the agent.[1] If you followed the steps above and your key has the default name id_rsa, then the command is:

ssh-add .ssh/id_rsa

Connect to the Gerrit server via ssh to check if everything works as expected. Replace gerrituser by your username as shown in your Gerrit settings:

ssh -p 29418 gerrituser@gerrit.wikimedia.org

Be paranoid and compare that the "RSA key fingerprint" is the same as the SSH fingerprint for gerrit.wikimedia.org:29418. If it is the same, answer "Yes" to "Are you sure you want to continue connecting?". Then enter the passphrase for your key.

You should get a message "Welcome to Gerrit Code Review". The last line should show "Connection to gerrit.wikimedia.org closed."

If you run into problems, use ssh -p 29418 -v gerrituser@gerrit.wikimedia.org (replace gerrituser by your username). The -v will provide verbose output to help find problems. Then read Gerrit/Troubleshooting.

Download code using Git

Let's practice by downloading (also called "cloning") the repository called "sandbox". Run the following on the Git Bash command line:

git clone ssh://gerrituser@gerrit.wikimedia.org:29418/sandbox

(Replace gerrituser 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 "sandbox" extension repository onto your machine. You will have a working directory of the extension's main branch (usually also called "git master"). Enter the new directory (via the command cd sandbox). Now you can look at the code and start editing it.

Note: Cloning the Sandbox repository 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.) See Download from Git how to download MediaWiki Core, extensions, skins, or any other project repository hosted at gerrit.wikimedia.org from Git.

Prepare to work with Gerrit

Gerrit requires that your commit message must have a "change ID". They look like Change-Id: Ibd3be19ed1a23c8638144b4a1d32f544ca1b5f97 starting with an I (capital i).
Each time you amend a commit to improve an existing patch in Gerrit, this change ID stays the same, so Gerrit understands it as a new "patch set" to address the same code change.

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

macOS

Configuring git-review

Git's default remote host name is "origin". This name is also used by Wikimedia projects. We need to tell git-review to use that host. Replace gerrituser with your Gerrit username:

git config --global gitreview.remote origin

git config --global gitreview.username gerrituser

Setting up git-review

After downloading ("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 run this command:

Submit a patch

Make sure that you are in the directory of the code repository (the command pwd tells you where exactly you are).

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

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

Create a branch

First, create a local branch for your new change. Replace BRANCHNAME below by a short but reasonably descriptive name (e.g. T1234 if a corresponding Phabricator task exists for your changes, cleanup/some-thing, or badtitle-error). Other people will also use this name to identify your branch.

git diff displays your changes in unified diff format: Removed lines have a minus (-) prefix and added lines have a plus (+) prefix. These changes are not yet "staged" (via git add) for the next commit.

Stage your changes for a commit

Run git status to decide which of your changes should become part of your commit. It will display a list of all file(s) that you have changed within the directory. At this point, the output will display "no changes added to commit" as the last line.

Use git add to make your changed file(s) become part of your next commit. In the example above we modified the file README.md, so the command would be:

git add README.md

Any files you've changed that you have not passed to git add will be ignored when running git commit in the next step.

Note: At any time you can always review the changes already staged by running git status. After you ran git add, git status will not show the line "no changes added to commit" anymore.

Note: You can also use git diff --cached to see which changes are staged and will go into the next commit. The output will look the same as for the git diff command above.

Commit your staged changes

Once you are happy with the list of changes added via git add, you can turn these changes into a commit in your local repository by using

git commit

sandbox/.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: T999999
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch mentionWikimedia
# Your branch is up to date with 'origin/master'.
#
# Changes to be committed:
# modified: README.md

You will then be asked in your text editor to add a descriptive summary for your commit. You must follow the Commit message guidelines. This is what other people will see when looking at the history of changes in the code repository.

Save the commit message and close your text editor. A summary (the commit ID, your subject line, the files and lines changed) will be displayed.

Note: 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. 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.

Prepare to push your commit to Gerrit

Synchronize your changeset with any changes that may have occurred in the master branch while you've been working ("rebasing"). From within your branch, run:

Note:git pull --rebase origin master 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.

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: Gerrit's diff algorithm (jGit) is slightly different from git's default diff algorithm. The differences displayed by Gerrit might not look like the differences displayed by Git on your machine.

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.

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

Sometimes, you might need to amend a submitted change. You can amend a change as long as the change hasn't been merged yet.

You can amend your own changes. To amend changes submitted by someone else, you need to be a member of Gerrit's Trusted-Contributors group. To become a member of Trusted-Contributors, find someone who is a member and ask them to add you. The group is viral in that members can add new members, use your powers responsibly.

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.

Hard reset and checkout the change with this command: (BEWARE:git review -d performs a hard reset that destroys all local changes. Stash or commit changes first which you wish to preserve!)

git review -d changenumber For example: git review -d 9332

Note, if you already have the change in a branch on your local repository, you can just check it out instead:

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

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.

Push to a branch different than master

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 create code changes directly within the web interface. This can be useful for making small patches, or for non-developers to contribute small fixes.

Who can review? Gerrit project owners

After creating a Developer account, anyone can comment on commits and express criticism 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".

Assignee. An optional field to make a single person responsible for handling reviewing the changeset. This should only be set if the assignee has agreed.

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.

The Add" button on the right of Reviewers:. 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.

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 list to review, 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.

If you merged a commit that references a task in Phabricator and that commit is supposed to fix that task completely, please go to that task and change its status to "Resolved" (via the Add Action… 🡒 Change Status dropdown). Also reference the merge ID if gerritbot has not already posted it in that task.