Setting up Gerrit

All projects under the Qt Open Governance umbrella are hosted on our Gerrit Instance. There is an official mirror and browser of these repositories.

How to get started - Gerrit registration

1. Create a Qt account, if you don't yet have one.
   • Note: The email address you use to contribute to the Qt Project will be publicly visible in the Git history. Use an alias + a custom e-mail address if you want to stay anonymous (this is discouraged)
2. Log into https://codereview.qt-project.org with your Qt account.
3. Go to the Settings page: https://codereview.qt-project.org/settings/
4. Go to "Settings" -> "Contact Information" and register your email address, if it hasn't been automatically registered.
5. You will receive a confirmation email; click on the link inside to finalize your registration.
   • If you use Outlook, manually copy the link including any trailing equal signs into the browser.
6. Go to "Settings"-> "SSH Public Keys" and upload your public SSH Key
7. If you are behind a firewall that blocks SSH access:
   1. Go to "Settings" -> "HTTP Password"
   2. Click "Generate Password"
   3. Add the following line to your ~/.netrc (Windows: ​%USERPROFILE%\_netrc):

      machine codereview.qt-project.org login <Gerrit username> password <Generated password>

Local Setup

Configure SSH properly (the URLs below rely on this). Add this to your ~/.ssh/config (Windows: C:\Users\%USERNAME%\.ssh\config):

Host codereview.qt-project.org
Port 29418
User <Gerrit/Jira username>

Configuring Git

We are developing in a heterogeneous environment with both Unix and Windows machines. Therefore it is imperative to have all files in the repository in the canonical LF-only format. Therefore, Windows users must run

$ git config --global core.autocrlf true

to automatically get CRLF line endings which are suitable for the native tools, and Unix users should use

$ git config --global core.autocrlf input

(this is a safety measure for the case where files with CRLF line endings get into the file system- this can happen when archives are unpacked, attachments saved, etc.).

To be able to create commits which can be pushed to the server, you need to set up your committer information correctly:

$ git config --global user.name "Your Name"
$ git config --global user.email "me@example.com"

Please do not use nicknames or pseudonyms instead of the real name unless you have really good reasons. Gerrit will not accept your commits unless the committer information matches the email address(es) you registered.

To facilitate following the style guide for commit messages, it is recommended to install the Qt commit message template:

$ git config --global commit.template <path to qt5.git or qt.git>/.commit-template

A common mistake is forgetting to add new files to a commit. Therefore it is recommended to set up git to always show them in git stat and git commit, even if this is somewhat slower (especially on Windows):

$ git config --global status.showuntrackedfiles all

Pre-2.0 git has a somewhat stupid default that git push will push all branches to the upstream repository, which is almost never what you want. To fix this, use:

$ git config --global push.default tracking

This is not relevant for mainline branches under Gerrit control, as all pushing happens with refs anyway, but it may be important for your private clones.

Sometimes it is necessary to resolve the same conflicts multiple times. Git has the ability to record and replay conflict resolutions automatically, but - surprise surprise - it is not enabled by default. To fix it, run:

$ git config --global rerere.enabled true
$ git config --global rerere.autoupdate true # this saves you the git add, but you should verify the result with git diff --staged

git pull will show a nice diffstat, so you get an overview of the changes from upstream. git pull --rebase does not do that by default. But you want it:

$ git config --global rebase.stat true

To get nicely colored patches (from git diff, git log -p, git show, etc.), use this:

$ git config --global color.ui auto
$ git config --global core.pager "less -FRSX"

Git supports aliases which you can use to save yourself some typing. For example, these (any similarity with subversion command aliases is purely accidental ;)):

$ git config --global alias.di diff
$ git config --global alias.ci commit
$ git config --global alias.co checkout
$ git config --global alias.ann blame
$ git config --global alias.st status

Using Existing clones

Add a gerrit remote pointing to codereview.

$ git remote add gerrit ssh://codereview.qt-project.org/qt/<qt5 or the submodule name you have checked out>

If you are behind a SSH-blocking firewall, use the https protocol:

$ git remote add gerrit https://codereview.qt-project.org/p/qt/<qt5 or the submodule name you have checked out>

For Qt 4.8, use

$ git remote add gerrit ssh://codereview.qt-project.org/qt/qt

If you are behind a SSH-blocking firewall, use the https protocol:

$ git remote add gerrit https://codereview.qt-project.org/p/qt/qt

For Qt Creator, use

$ git remote add gerrit ssh://codereview.qt-project.org/qt-creator/qt-creator

If you are behind a SSH-blocking firewall, use the https protocol:

$ git remote add gerrit https://codereview.qt-project.org/p/qt-creator/qt-creator

Cloning repositories

You should clone from the official mirror and track changes from there in order to keep the load on Gerrit down.

Cloning Qt5

Qt 5 is modularized into several repositories which are aggregated by the qt5 super repo. The canonical way to obtain a Qt 5 clone is cloning the super repo from a mirror, and running the init-repository script in qt5 to set up the gerrit remote(s) pointing to codereview, and to clone the submodules:

$ git clone git://code.qt.io/qt/qt5.git
$ cd qt5
$ ./init-repository -f --no-webkit

Note that Qt 5 submodules have been changed from absolute to relative URLs (like "../qtbase.git") in the .gitmodules file. If you make a clone of git://gitorious.org/qt/qt5 in gitorious as git://gitorious.org/~<username>/qt/<cloned-repository-name>.git the init-repository script will not work. A URL rewrite rule has to be added to the .gitconfig file to make it work:

[url "git://gitorious.org/qt/"]
        insteadOf = git://gitorious.org/~<username>/qt/

Alternatively, individual Qt5 submodules can be manually cloned as well. Follow Using Existing Clones above after cloning.

NOTE: If you don't use the init-repository script, you may need to copy the Git hooks manually for every clone. To do this, install the hook generating Commit-Id files into your top level project directory, as well as all sub-repositories (e.g. qtbase.git) either through

$ scp -p codereview.qt-project.org:hooks/commit-msg .git/hooks

or by downloading the file via browser: commit-msg and putting it into the .git/hooks directory (make sure it is executable).

It is recommended to install the git_post_commit_hook from the qtrepotools repository. This gives you the checks of the Sanity Bot locally. To do this, save the script

#! /bin/sh
exec "<path to git clone>/qtrepotools/git-hooks/git_post_commit_hook" "$@"

into each <path to git clone>/.git/hooks/post-commit

NOTE: Starting with git 1.7.8, if <module name>/.git contains gitdir: ../.git/modules/<module name>, you need to put the submodule hooks in .git/modules/<module name>/hooks instead of <module name>/.git/hooks.

Cloning Qt4

$ git clone git://code.qt.io/qt/qt.git

Note that Qt4 does not have a master branch (since no 4.9 is planned). So, you should push changes to the 4.8 branch.

Cloning Qt Creator

$ git clone git://code.qt.io/qt-creator/qt-creator.git

Setup the gerrit remote

$ git remote add gerrit ssh://codereview.qt-project.org/qt-creator/qt-creator

If you are behind a SSH-blocking firewall, use the https protocol:

$ git remote add gerrit https://codereview.qt-project.org/p/qt-creator/qt-creator

Pushing your local changes to gerrit

See Gerrit Introduction.