Gerrit/Advanced usage

The basic instructions to set up and operate with Git and Gerrit are described at the Tutorial (see also its shortest version).

Warning
This page mostly documents how to do things "the hard way" in gerrit. The  tool continues to improve, and now contains built-in mechanisms to push to a branch, upload a set of dependent patches, etc. You should probably review  before deciding that you need to proceed further here.

Setup SSH shortcut (optional)
It's easier to access the repository if you don't have to specify the full yourusername@gerrit.wikimedia.org:29418 every time. You can edit your  file and add Host gerrit Hostname gerrit.wikimedia.org Port 29418 User yourusername

Then you can use "gerrit" instead.
 * '' adds a   remote to git which should make this step unnecessary. Cscott (talk)

Setting up a repository for git-remote
Most repositories should already have information for git-remote where your repository is and what the name of the master branch is. The information is stored in a  file in the root of the repository. If this file does not exist yet, you need to create and commit it. The format is the following: The  and   fields are mandatory. The other fields are optional:  defaults to 29418 and   defaults to.

Howto - Merging your amend back into your branch
''This section is optional. It's offered as a convenience way to offer your a solution to a common problem. At this stage, your new changeset is already in Gerrit.''

After you have amended your change, you may want to merge it back into your local branch.

You can do this by going to the Gerrit change in question.

Here is an example:

https://gerrit.wikimedia.org/r/#/c/7669/4

Go to the Download section and copy cherry pick.

We will select patch set 4.

Switch back to your branch. You will be in your review branch where you just made your change.

Note: use the branch relevant to your change number.

Paste in the cherry pick and merge any conflicts.

Perform a git add on the modified files.

Do not forget to check your status and run a diff.

You should see there are no differences:

Then commit the changes:

Submitting a change to a branch for review ("backporting")

 * See also Backporting fixes, which discusses backporting changes to MediaWiki core (coordinate with the MediaWiki Release Manager, handling in Phabricator, etc.)

In this example, we'll backport from   to. The basic idea is to use  to apply the changes from the commit to master to a different branch. (Note that this can also be done via the Gerrit web interface, with the 'Cherry Pick' button.)

Before you start, look up the git commit hash of the commit that was merged into master. This can be found on the Gerrit change page. Scroll down to the last Patch Set, and the git commit hash is between "Patch Set NN" and "(gitweb)" (not to be confused with the Gerrit Change id which starts with a capital 'I'). Make sure that this commit was indeed merged into the master branch. If it wasn't then wait until it has been reviewed and merged in master &mdash; the commit may still be amended and we don't want to merge an old version).


 * Is there any need to use complicated  instead of   here? -- S Page (WMF) (talk) 02:28, 17 May 2013 (UTC)
 * The only reason would be so that you can give it a new topic. So alternatively, after the  check, look up the topic name first (or think of a new topic) and do   then followed by regular   (instead of git push); as of git-review version 1.23, it will reuse the original topic.
 * works too if you want to push to a remote branch from a review branch.

As a result:
 * https://gerrit.wikimedia.org/r/25756 is created for review.
 * shows both the original and the merge changes

Acting on remote branches
By default, your local clone will only have a local master branch set up to track the remote master branch. Tracking means that whenever you fetch objects from the remote repository, git status or git branch will be able to tell you how up-to-date is your local branch, which is very useful. So, whenever you want to regularly act on a remote branch (lets says REMOTE_BRANCH, you want to setup a one locally (REMOTE_BRANCH too to easily remember about it) that track it (with -t).

will give the full details:

Pushing having used automatic setup
git-review accepts, as an optional argument, the branch name to interact with. When that argument is not specified, it falls back to look for the  parameter in a   file at the root of the repository.

Every branch should have a .gitreview having a correct defaultbranch value. For, else people will have to use something like:.

Pushing having used manual (Windows) setup
To change where you push to for review having performed a manual setup, run  to create the local alias, then use   as per usual.

Committing to non master
To make a change to the 1.17 branch, create a branch and tag, and push both:

Partial revert of previous commit
Can be found in gerrit patch view in small letters next to text Patch Set N. Then push for review normally.

Unlink bogus dependencies (rebase changes)
Example for Gerrit 5154

git fetch --all # To make sure we have latest changes git review -d Ie6e3c9be git rebase -i gerrit/master # Delete the commits you want to get rid of git commit --amend # Add a note git review -f # -f deletes the branch after submit

Create a dependency
If you are about to create a patch that depends on another (unmerged) patch, or if you already submitted a patch but need to fix the dependency (i.e. currently it is based on master and would break if merged without the dependency, or maybe you squashed your change on top of the dependency). Then this is the section you're looking for. If you want to fix the patch to have the right dependency rather than to create a new patch with a dependency, then make sure your working copy is clean (no uncommitted changes).

git fetch --all # Make sure we have latest info from the repository git review -d 1234 # Gerrit change number of the change you want as dependency ("parent")

Now we need to make sure the patch has the correct git-parent. Depending on whether you are creating a new patch or fixing an existing patch, there is two different ways to do this. If you are starting fresh: git checkout -b bug/1234 # Creates a new branch, with the current branch (the dependency) as parent git add someFile.php some/other/file.js git commit # Commit your patch
 * 1) Edit files: make your changes

git log -n5 --decorate --pretty=oneline # Verify that the last 5 entries of the log now start with:
 * 1) * (HEAD, bug/1234) your change
 * 2) * (review/john/700) the dependency
 * 3) * (gerrit/master)

git push gerrit HEAD:refs/for/master # or git review If you need to amend your patch to have the correct dependency: git branch # Take note of the review/* branch that was created for this, it has an "*" in front of it git checkout bug/1234 # Check out the local topic branch of your change git rebase review/john/7000 # The branch name of the gerrit change we checked out earlier


 * 1) Resolve conflicts if needed,
 * 2) - use "git status" to see the files that need resolution
 * 3) - after fixing it in your editor, "git add filename" for each of the fixed files

git rebase --continue

git log -n5 --decorate --pretty=oneline # Verify that the last 5 entries of the log now start with:
 * 1) * (HEAD, bug/1234) your change
 * 2) * (review/john/700) the dependency
 * 3) * (gerrit/master)

git push gerrit HEAD:refs/for/master # or git review

Cross-project dependencies
You can also use cross-project dependencies (e.g. an extension that requires a change in core before it can be merged). You can accomplish this by adding e.g. in the footer of a commit message. Use the full Change-ID (‘I’ + 40 characters). See https://docs.openstack.org/infra/zuul/feature/zuulv3/user/gating.html#cross-project-dependencies for more details.

Examples: 539718, 534888

Splitting a commit into smaller ones
Explained in detail at Gerrit/split a submitted change.

Removing your local branch after submitting your change into Gerrit
you@yourmachine:~/puppet (production)$ git checkout -b mycoolfeature you@yourmachine:~/puppet (mycoolfeature)$ vi foobar you@yourmachine:~/puppet (mycoolfeature)$ git commit -a -m "Committing my cool feature" you@yourmachine:~/puppet (mycoolfeature)$ git review -f you@yourmachine:~/puppet (production)$ If the  flag is passed to git-review, it will try to submit the change, and if it succeeds it will switch back to the master branch (production in this case) and delete the feature branch.

Merging a submodule into a parent project
See Gerrit/merge submodule.

Using a personal sandbox for personal branches
Gerrit allows the creation of "personal sandboxes" where users can stash code that they're working on in a personal branch that doesn't require admin intervention for pushes. See Gerrit/personal sandbox.

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

Working on an existing change set
Sometimes you want to work on a change set started by some else and then upload your changes as a new patch set. NOTE: DO NOT use the  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 if needed, and keep the Change-Id line intact. (See : )

Viewing and commenting on code
The basic functionality is explained in the Git and Gerrit tutorial.

Some extra bits:


 * Diff Against dropdown menu. This menu will allow you to change what changes you're reviewing. This is helpful if you reviewed a past changeset, and want to make sure your changes were taken into account. Rather than reading through the entire changeset diff'd against the base commit, you can read only the differences between the current changeset and the changeset you reviewed. There's a bonus, too: You can see your comments on the left hand side of the If there was a rebase commit, there will be garbage in the diffs, but you can read things one changeset at a time and it will still be faster.
 * Open All button:
 * Opens the diff(s) in a new tab. 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.
 * For commits that contain whitespace changes (i.e. indent a block that was changed), it is best to set the diff-preferences appropriately to make it easier to review. When viewing a diff, on top there is a link "Preferences". Then there is two important settings to focus on. "Ignore Whitespace" and "Intraline Difference". The last one (Intraline Difference) is especially useful if a block of code was indented, as this setting will show the added tabs themselves allowing other changes to be recognizable without having to compare every word in your mind (see screenshot).

How to comment on, review, and merge code in Eclipse
As an alternative to Gerrit's web interface, you can also review code from Eclipse using the Mylyn task-management framework. To get started, download and install Eclipse, and then install Mylyn from the Install New Software menu (as of Oct 5th, 2013 you need the snapshots update site to use the Wikimedia Gerrit installation). When you next launch Eclipse, you'll be prompted to add a task for Mylyn. From there, you'll need to install the connector for Gerrit, specify  as the server URL, and add your username and password.

How to review and merge code via command line
Using dippy-bird you can easily do command line review and merging. The query parameter is the change you want to deal with.

You can therefore use that to approve a range of commits:

Mass-approving changes across repositories
We might sometimes have to generates a ton of changes, for example when doing a similar change on all our repositories. In the past, this happened after the MediaWiki extensions got migrated to Git since we had to add a  file to each repository.

First, you can query gerrit for a list of change using the CLI! A useful alias:

alias gerrit='ssh -p 29418 gerrit.wikimedia.org gerrit'

Then use that to execute a query such as all open changes on topic dotgitreview: gerrit query 'status:open topic:dotgitreview'

With some shell magic, you can get a list of change number:

gerrit query 'status:open topic:dotgitreview' \ | egrep '^ number' | cut -d\  -f4- > CHANGES_NUMBERS

Then loop on them and remotely approve the changes: for i in `cat CHANGES_NUMBERS`; do gerrit review --verified=+1 --code-review=+2 --submit "$i,1"; done

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

How to create a repository ("Gerrit project")
See "Request a new Git repository". There's a form to fill out. It should get processed very quickly (within a couple of days).

Gerrit project dashboard
Each Gerrit repository has one or more dashboards that can be customised. The default dashboard is shown when you click on a project link anywhere in Gerrit. For example, clicking "mediawiki/core" on a commit page related to MediaWiki core will take you to https://gerrit.wikimedia.org/r/#/projects/mediawiki/core,dashboards/default.

In Gerrit, dashboards are created in groups. Every repository inherits the "default" dashboard group from the "All-Projects" meta project. By default a project's default dashboard defaults to "default:recent". You can change what dashboard is used by default in the  file in the   branch of a repository. Detailed instructions are below; you can look at existing examples.

It is recommended to add the following aliases to your  file. See Git/aliases for more information.

Create a new dashboard group

 * 1) Make sure you have push access to   on the repository in question. For Wikimedia Foundation teams, use the parent repo , which all ldap/wmf users can write to.
 * 2) Clone the repository if you haven't already.
 * 3) Create a new orphan branch locally, for example.
 * 4) Create your first dashboard's configuration file (can be named anything, e.g.  ).
 * 5) Stage your changes and make a commit.
 * 6) Push the initial commit:

This will create the new branch and add the first dashboard as starting point.

It can be viewed at the following url: https://gerrit.wikimedia.org/r/#/projects/wikimedia,dashboards/MY_BRANCH:MY_FILE In the above example, this would be.

For subsequent edits, do not use the above git-push command as this will bypass Gerrit, and makes the commits not visible for others to find in searches, notifications, and activity dashboards. You are free to self-merge these changes, but make sure they are first submitted to Gerrit by using the  command instead of pushing directly. See the next section for how that works.

Change an existing dashboard
Example: https://gerrit.wikimedia.org/r/#/c/305601/
 * 1) Clone the repository if you haven't already. For Wikimedia Foundation teams, use the parent repo
 * 2) Check out the dashboard group's configuration branch.
 * 3) Change the dashboard's configuration file to your liking. See Project Dashboards in Gerrit Documentation for the syntax.
 * 4) Be sure to test any changed queries by manually entering them in the Gerrit through your browser.
 * 5) Stage your changes and make a commit.
 * 6) Push the commit for review:
 * 7) Merge the change in Gerrit, and confirm that the change is applied via , such as.

Set the default dashboard
Make sure you have the following aliases in your  file. See Git/aliases for more information.


 * 1) Clone the repository if you haven't already.
 * 2) Check out the repo configuration branch:
 * 3) Set the   field in a   section, like so:
 * 4) Stage your changes and make a commit.
 * 5) Push the commit for review:
 * 6) The change is now up for review to be merged.

Add navigation links
Since Gerrit 2.12 it is possible to customise the navigation links in the "My" menu (or "Your" menu in polygerrit) along the top of the web interface. By default these contain "Changes", "Draft Comments", "Starred Changes" and more. They can be changed from the preference settings at https://gerrit.wikimedia.org/r/#/settings/preferences (or in polygerrit at https://gerrit.wikimedia.org/r/settings/#Menu ).

For example, to add a link to the Performance Team's dashboard:
 * 1) Open https://gerrit.wikimedia.org/r/#/settings/preferences
 * 2) Add an entry with URL   and name "Perf Team" or some such.
 * 3) Save changes!

Module:Gerrit dashboard can help with generating complex links (personal dashboards).


 * Suggested searches that other people use:
 * https://gerrit.wikimedia.org/r/q/is:open+(reviewer:self+OR+assignee:self)+-is:wip+(-age:2w+OR+is:starred)
 * This will give you "open non-WIP things for which I'm a reviewer/assignee, and which either I've starred or have been touched within the past two weeks"
 * ... (please add yours!)

Code Review links
Links to old SVN Code Review revisions are stored in commit notes. They may be fetched for display in the git log using the following command:

Note this must be done separately for each git repository.

Gerrit review scores
As above, code review metadata is stored in commit notes and may be fetched using:

To retrieve them regularly, add to your git config.

To display them in  (similar syntaxes work for related tools):

ssh proxy to gerrit
If gerrit is being slow, when it comes to uploading patches, it might be a network issue. (especially if you are in Europe, at certain times of the day) If you have a server / vm in the US or other proxy that you can use, then you can access gerrit via that.

In your ~/.ssh/config add something like:

Then connect to the proxy (e.g. via ssh, with the "-D 8081" option). Then it should work to access gerrit to upload / download patches and may be faster.