Gerrit/TortoiseGit tutorial

Translate this page

This tutorial may help Windows users contributing source code to Gerrit and git.

Install software

Download and Install TortoiseGit and language package
Download and install Git for Windows
1. Select Windows Explorer integration – Simple context menus entries: "Git Bash here" which is recommended.
  - It is optional to select Additional Icons for Desktop and Quick Launch
  - It is optional to select Git GUI here, but we use TortoiseGit as Graphical User Interface.
    On the other hand, stating that GUI does a quick compression cleanup of the local repository if needed.
  - Do not select Advances context menu (git-cheetah plugin) (available with older releases only)
  - You should keep the file associations for *.git and *.sh
  - It is up to you to use TrueType fonts in all console windows
2. Keep the default Start Menu Folder
3. In next step we choose "Run Git from Windows Command Prompt". Otherwise some scripts may not run.
4. Select 3rd item called 'Checkout as-is, commit as-is' for the line ending conversions

Setting up environment

Create and publish your SSH-Key

Start puTTYgen in the Start menu or in C:\Program Files\TortoiseGit\bin\puttygen.exe, create an new SSH key and save the private key it in a .ppk file; also save the public key.
Login to gerrit:, use your labs username and password
Go to Settings > SSH Public Keys and add your public key
Go to Settings > Identities and verify your email address and account (identity)

Clone your working copy

Right.click on windows explorer and select "Git clone" to clone a repository to the given directory. Use the URL from gerrit repository e.g. ssh://<username>@gerrit.wikimedia.org:29418/pywikibot/core for the pywikibot core.
Select the recursive switch.
Be aware: port 29418 is required for SSH access here. The default SSH port 22 does not work! Adjust your router or firewall if required.
You may choose "Load Putty Key" and select your private .ppk file given above. Or you may deselect that button and setting up in the next step.

Setting up TortoiseGit

Right-click on your repository and open TortoiseGit > Settings
Choose Git > Remote and select "origin" remote server. Verify the URL and select your private puTTYkey .ppk file if not done previously.
Choose Git (or Git > Config) and verify that your Name and Email of the User Info is the same as your Gerrit account.
Click on Edit global .gitconfig and again verify your name and email to be the same as in Gerrit.
Choose General > Set Extend Menu Item and deselect Browse References

Git settings

Gerrit is used for the review workflow and Git has to be instructed to push changes to Gerrit, instead of to the official Git repository. There are two ways to do it:

Using TortoiseGit

Again, re-open TortoiseGit > Settings and choose Git (or Git > Config)
Click on Edit global .gitconfig button and add the following sections:

[url "ssh://<username>@gerrit.wikimedia.org:29418"]
	pushInsteadOf = git://git.wikimedia.org
[branch]
	autosetuprebase = remote

Using git bash

Right-click on your repository and start Git Bash Here
Type the following lines:
git config --global url."ssh://<username>@gerrit.wikimedia.org:29418".pushInsteadOf git://git.wikimedia.org

git config --global branch.autosetuprebase remote.

Install commit-msg hook

Download the commit-msg hook script from the repo and install it into the <project name>/.git/hooks folder using Save As...
Note: .git is a hidden folder.
See also Gerrit/Alternatives to git-review for other variants to install the script.

Working with repository

All needed commands of TortoiseGit you'll find in the context menu by right-click on your local repository choosing TortoiseGit. It is not necessary to have Gerrit/git-review installed.

View repository log

There are two ways to show the repository log:

Use the Show log command or
Use Windows Properties in the context menu. Select Git tab and choose Show log button.

Update your repository

For updating you local repository you may do it with the following steps:

Stash your local changes with Stash Save command. You may enter a comment or ignore it. Another way to save your local changes is to commit them to the local repository, which will explained later.
Pull... changes from remote repository. Keep AutoLoad Putty Key checked. You may check Launch Rebase after Fetch to start rebase or start it manually.
Rebase your repository to fast forward local master branch to its remote branch. Either use Rebase... option or check the depending checkbox above. Then click Start (FastFwd) if needed and klick Done when you are finished or Abort.
Stash pop to apply your local changes to the working tree and remove the stash from the stack.

Update externals

Use Submodule Update... for it. This is needed e.g. for i18n messages.

Create a new Changeset

If you want change the code and push it to remote repository, do it by these steps:

Select Create Branch and enter a meaningfull branch name. Enable check box Switch to new branch and click OK. If you haven't enabled this check box you may use the Switch/Checkout... command after that. Creating a new branch is also available from context menu inside repository log.
Make your changes on your local repository and test it.
Commit you changeset to the local repository by Git Commit -> <your local branch name> command; this command is part of the windows context menu not the TortoiseGit context submenu.
Add a descriptive commit message into the message field for your commit. Refer Gerrit/Commit message guidelines.
Click View Patch>> at the bottom of the dialog window to see the patch and verify the changes.
Enable the checkbox Amend Last Commit if this change is a follow-up of an already commited patch of the same branch
Klick Commit
Push... to submit your patch to the remote repository for peer review, otherwise press close

Submit a patch

Either use Push... of the commit dialog or use Push... from context menu.
Local:: Select you local branch to submit. Default is your actual branch
Remote: type refs/for/master for the destination. You may easily add a gerrit topic for your changeset by appending it separated by "%topic=", e.g. refs/for/master%topic=mytopic.
Press OK to submit your patch.

Download a patch for review

You may download a patch form another developers to your local repository to review it by following steps:

First create a new local branch
Choose Fetch.... A new dialog window will be opened.
Select Arbitrary URL.
Enter the repository URL there, e.g. ssh://<username>@gerrit.wikimedia.org:29418/pywikibot/core
Enter the remote branch setting like refs/changes/<index no>/<change no>/<PS no> e.g. refs/changes/32/9332/1, where
- <index no> are the last two digits of <change no>
- <change no> is the gerrit change number
- <PS no> is patch set number of that change
OK to fetch this patch set
Choose Git Bash here from windows context menu
type git cherry-pick FETCH_HEAD in the git window

Problems, issues and workarounds

Missing Change-Id in commit message

Install commit-msg hook first, see above.

Git Clone hangs

If Git Clone... hangs after "Resolving deltas" hits 100% and you are using PuTTY: Open up PuTTY, load Default Settings, and set "Chokes on PuTTY's SSH-2 'winadj' requests" to "On" under Connection->SSH->Bugs. Then select Session, select Default Settings, and Save.