Gerrit/TortoiseGit tutorial

From MediaWiki.org
Jump to: navigation, search

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

Install software[edit]

  1. Download and Install TortoiseGit
  2. 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)
      • 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[edit]

Create and publish your SSH-Key[edit]

  • 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 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[edit]

  • 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[edit]

  • 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[edit]

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[edit]

  • 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[edit]

  • 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[edit]

  • 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[edit]

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[edit]

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[edit]

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[edit]

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

Create a new Changeset[edit]

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[edit]

  • 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 "/", e.g. refs/for/master/mytopic.
  • Press OK to submit your patch.

Download a patch for review[edit]

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[edit]

Missing Change-Id in commit message[edit]

Install commit-msg hook first, see above.

Git Clone hangs[edit]

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:[edit]