Gerrit/TortoiseGit tutorial

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

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

Create and publish your SSH-Key

 * Start puTTYgen in the Start menu or in, create an new SSH key and save the private key it in a .ppk file; also save the public key.
 * Login to https://gerrit.wikimedia.org, 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.  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 button and add the following sections:

Using git bash

 * Right-click on your repository and start Git Bash Here
 * Type the following lines:

Install commit-msg hook

 * Download the commit-msg hook script from the repo and install it into the   folder using
 * Note:  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 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 if needed and klick  when you are finished or.
 * 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 . 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 ->  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 Ammend Last Commit if this change is a follow-up of an already commited patch of the same branch
 * Klick
 * to submit your patch to the remote repository for peer review, otherwise press

Submit a patch

 * Either use 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 "/", e.g. refs/for/master/mytopic.
 * Press 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:// @gerrit.wikimedia.org:29418/pywikibot/core
 * Enter the remote branch setting like refs/changes/ / / e.g. refs/changes/32/9332/1, where
 *   are the last two digits of  
 *  </tt> is the gerrit change number
 * <PS no></tt> is patch set number of that change
 * to fetch this patch set
 * Choose Git Bash here from windows context menu
 * type git cherry-pick FETCH_HEAD</tt> in the git window

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.

See also:

 * TYPO3 Contribution Walkthrough with TortoiseGit