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.

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:
 * Create a new branch with Switch/Checkout...', select Create New Branch'' and enter a meaningfull branch name.

(* to be continued *)

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