Setting up Gerrit: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
m (Fix netrc path on Windows)
m (Setting up git hooks: use the git hooks from qtrepotools (ensures the hooks are updated automatically with `git pull` in qtrepotools))
 
(61 intermediate revisions by 30 users not shown)
Line 1: Line 1:
[[Category:Developing_Qt::Instructions]]
[[Category:Developing Qt::Instructions]]
[[Category:Tools::Gerrit]]


All projects under the Qt Open Governance umbrella are hosted on our [http://codereview.qt-project.org Gerrit Instance]. There is an [http://code.qt.io official mirror and browser] of these repositories.
All projects under the Qt Open Governance umbrella are hosted on our [http://codereview.qt-project.org Gerrit Instance].
There is an [http://code.qt.io official mirror and browser] of these repositories.


== How to get started - Gerrit registration ==
In order to be able to propose changes to those projects, you have to first setup your Gerrit account and get Qt's sourcecode, following the steps below:


# Create an account in the [https://bugreports.qt.io/ Qt bug tracker] (also known as JIRA)
#[[#How to get started - Gerrit registration|Set up]] a Gerrit account
# Go to https://codereview.qt-project.org and log in with your Qt bug tracker credentials
#Tweak your SSH config as instructed [[#Local Setup|here]]
#* '''Note''': Gerrit usernames are case-sensitive, but JIRA usernames are not. If you attempt to log into Gerrit with different capitalizations, you will end up with multiple accounts.
#Use the recommended Git settings, defined [[#Configuring Git|here]]
# Go to the Settings page: https://codereview.qt-project.org/settings/
#[[#Getting the source code|Get the source code]] of the projects you want to contribute to
# Go to "Settings" -> "Contact Information" and register your email address.
#* You will receive a confirmation email; click on the link inside to finalize your registration.
#** When you use Outlook, manually copy the link ''including any trailing equal signs'' into the browser.
#* '''Note''': Your username and e-mail address will be visible to the public. Use an alias + a custom e-mail address if you want to stay anonymous (this is discouraged)
# Go to "Settings"-> "SSH Public Keys" and upload your [https://help.github.com/articles/generating-ssh-keys public SSH Key]
# If you are behind a firewall that blocks SSH access:
## Go to "Settings" -> "HTTP Password"
## Click "Generate Password"
## Add the following line to your <tt>~/.netrc</tt> (Windows: <tt>​%USERPROFILE%\_netrc</tt>):<pre>machine codereview.qt-project.org login <Gerrit username> password <Generated password></pre>


== Local Setup ==
Moreover, if you did not use the init-repository scripts to get the source code, you will have to manually:


Configure SSH properly (the URLs below rely on this). Add this to your <tt>~/.ssh/config</tt> (Windows: <tt> C:\Users\%USERNAME%\.ssh\config</tt>):
#[[#Setting up git hooks|Set up the git commit hooks]] .
#[[#Setting_up_gerrit_git_remote|Set up]] a Gerrit git remote.
 
Once all the steps above have been completed, you're ready to [[Qt Contribution Guidelines#Creating Changes for Inclusion Into Qt|submit your patch to Qt]]!
 
See also:
 
*[[Git Introduction]]
*[[Gerrit Caveats and Hints]]
 
==How to get started - Gerrit registration==
Before starting make sure you have a working Git installation and OpenSSH installed. ( or the bundled version of SSH that comes with recent Git packages).
 
#Create a [https://login.qt.io/register Qt account], if you don't have one yet.
#*'''Note''': Use an all-lowercase user name. Otherwise, Gerrit will lowercase it for you, and as it is case sensitive, you will have to use mismatched login names.
#Log into https://codereview.qt-project.org with your Qt account.
#Go to [https://codereview.qt-project.org/settings/#Profile "Settings" -> "Profile"], set your real name and register your email address, if it hasn't been automatically registered.
#*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.
#*'''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)
#Review and agree to the Qt Project's contribution license agreement (CLA) in Gerrit. You need to do this only once, unless the license changes.
#*If your company has a corporate contribution agreement, ask the admin of your company's Gerrit user group to add your account to this group.
#*More details about the CLA can be found [https://www.qt.io/contributionagreement/ here].
#Create a public SSH key for your PC, if you don't have one yet (see below under "Local Setup" for instructions)
#Go to "Settings"-> "SSH Public Keys" and upload your public SSH Key.
#If you are behind a firewall that blocks SSH access:
##Go to "Settings" -> "HTTP Password"
##Click "Generate Password"
##Add the following line to your <tt>~/.netrc</tt> (Windows: <tt>​%USERPROFILE%\_netrc</tt>):<pre>machine codereview.qt-project.org login <Gerrit username> password <Generated password></pre>
 
==Local Setup==
'''Proper configuration of SSH for your Gerrit account is necessary for the URLs in the next steps.'''
 
'''Note:''' On Windows, when '''not''' using OpenSSH, the <tt>~/</tt> shorthand used below can be equated with <tt>C:\Users\%USERNAME%\</tt>. Make replacements in the example as necessary.
 
Edit <tt>~/.ssh/config</tt> with host information for Gerrit, as shown below. Do not copy comments marked by #, as they may not be ignored by your SSH client.


<pre>
<pre>
Host codereview.qt-project.org
Host codereview.qt-project.org
Port 29418
    Port 29418
User <Gerrit/Jira username>
    # To avoid no mutual signature algorithm errors
    PubkeyAcceptedKeyTypes +ssh-rsa
    # Use your Gerrit username, not email or your username on your own machine.
    # You can view this from Settings in gerrit when logged in.
    User yourgerritusername
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/id_ed25519
</pre>
</pre>


'''NOTE:''' The following steps need to be applied to every clone:
Next, you will need to ensure that you have an SSH key pair, and make it known to Gerrit.
 
#If you have no key pair on this machine yet, generate one now. On the command line, invoke the following command, replacing "<tt>john-doe-win10-home"</tt> with a comment that uniquely describes the machine you're on:<br><tt>ssh-keygen -t ed25519 -C john-doe-win10-home -f ~/.ssh/id_ed25519</tt><br>'''Note: SSH keys are intended to be unique to each machine. New keys must be created for each additional machine logging in to Gerrit with SSH.'''
#Open the <tt>~/.ssh/id_ed25519.pub</tt> file with a text editor and copy its entire contents into the clipboard.
#Log into https://codereview.qt-project.org and navigate to <tt>Settings</tt> (the gear symbol on the top right) → <tt>SSH Keys</tt>
#Paste the clipboard into the <tt>New SSH key</tt> entry, and hit the <tt>ADD NEW SSH KEY</tt> button.
 
You can verify that the connection works by running:<br><tt>ssh codereview.qt-project.org</tt>
 
If the connection is functional, you should see a welcome message. End the connection by pressing <tt>Ctrl-C</tt>. If not, running <tt>ssh -v codereview.qt-project.org</tt> should give you an error message with details.
 
When making a connection to codereview.qt-project.org using ssh for the first time a prompt will show asking you to verify the authenticity (public key) of the host using it's fingerprint.<syntaxhighlight>
The authenticity of host '[codereview.qt-project.org]:29418 ([54.194.93.196]:29418)' can't be established.
ED25519 key fingerprint is SHA256:DwwqNluQyJVkOk+3bFMK6NwWYIGjMnqGP+R0k59e3CY.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
</syntaxhighlight>This prompt will only show the first time connecting to the host or when the host's public keys are changed. When prompted verify that the fingerprint for your key type is correct then accept the host's public key by typing yes, alternatively you could copy the fingerprint into the terminal for it to compare it to the provided fingerprint.


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
Here is a list of current fingerprints for codereview.qt-project.org<ref>https://lists.qt-project.org/pipermail/development/2022-November/043216.html</ref>:<syntaxhighlight>
ssh_host_ecdsa_384_key
384 SHA256:yMnqjnsJU0y6kfiyQQu8pYNGPFE7av5QxbeLdjTKNmk (ECDSA)


<pre>
ssh_host_ecdsa_521_key
$ scp -p codereview.qt-project.org:hooks/commit-msg .git/hooks
521 SHA256:kytLsqmLdG1KXLO/s3OxOajTYqf1+n7+YqqbOUzNbtE (ECDSA)
</pre>


or by downloading the file via browser: [http://codereview.qt-project.org/tools/hooks/commit-msg commit-msg] and putting it into the <tt>.git/hooks</tt> directory (make sure it is executable).
ssh_host_ecdsa_key
256 SHA256:El3+EYlXAGylCVo/Y/WYzPg7tS4fjejkepO1JVXUkb0 (ECDSA)


It is recommended to install the git_post_commit_hook from the [https://qt.gitorious.org/qt/qtrepotools qtrepotools] repository. This gives you the checks of the [[Early Warning System|Sanity Bot]] locally. To do this, save the script
ssh_host_ed25519_key
<pre>
256 SHA256:DwwqNluQyJVkOk+3bFMK6NwWYIGjMnqGP+R0k59e3CY (ED25519)
#! /bin/sh
exec "<path to git clone>/qtrepotools/git-hooks/git_post_commit_hook" "$@"
</pre>
into each <path to git clone>/.git/hooks/post-commit


'''NOTE:''' Starting with git 1.7.8, if <tt><module name>/.git</tt> contains <tt>gitdir: ../.git/modules/<module name></tt>, you need to put the submodule hooks in <tt>.git/modules/<module name>/hooks</tt> instead of <tt><module name>/.git/hooks</tt>.
ssh_host_rsa_key
4096 SHA256:EPuL0PAbNuXXoye7X93ARF7/XALxA5XNAaE3p6M/L3g (RSA)
</syntaxhighlight>If the fingerprint the host provides is not included in this list, you might face an attempt for a man-in-the-middle attack or the host keys might have changed, if that happens search for the project's latest keys.


== Configuring Git ==
==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
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


<pre>
<pre>
$ git config --global core.autocrlf true
git config --global core.autocrlf true
</pre>
</pre>


Line 59: Line 109:


<pre>
<pre>
$ git config --global core.autocrlf input
git config --global core.autocrlf input
</pre>
</pre>


Line 67: Line 117:


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


Line 74: Line 124:
Gerrit will not accept your commits unless the committer information matches the email address(es) you registered.
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:
To facilitate following the style guide for commit messages, it is recommended to install the Qt commit message [http://code.qt.io/cgit/qt/qt5.git/tree/.commit-template template]:
 
<pre>
$ git config --global commit.template <path to qt5.git or qt.git>/.commit-template
</pre>
 
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 <tt>git stat</tt> and <tt>git commit</tt>, even if this is somewhat slower (especially on Windows):
 
<pre>
$ git config --global status.showuntrackedfiles all
</pre>
 
Pre-2.0 git has a somewhat stupid default that <tt>git push</tt> will push ''all'' branches to the upstream repository, which is almost never what you want. To fix this, use:


<pre>
<pre>
$ git config --global push.default tracking
git config --global commit.template <path to qt5.git or qt.git>/.commit-template
</pre>
</pre>
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:
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:


<pre>
<pre>
$ git config --global rerere.enabled true
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 config --global rerere.autoupdate true # this saves you the git add, but you should verify the result with git diff --staged
</pre>
</pre>


Line 104: Line 140:


<pre>
<pre>
$ git config --global rebase.stat true
git config --global rebase.stat true
</pre>
</pre>


Line 110: Line 146:


<pre>
<pre>
$ git config --global color.ui auto
git config --global color.ui auto
$ git config --global core.pager "less -FRSX"
git config --global core.pager "less -FRSX"
</pre>
</pre>


Line 117: Line 153:


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


=== Using Existing clones ===
==Getting the source code==
 
===Cloning Qt5===
You should clone from the [http://code.qt.io/ official mirror] and track changes from there in order to keep the load on Gerrit down.
 
This [[Building-Qt-5-from-Git|guide]] will show you how to get and build the source code.


Add a <tt>gerrit</tt> remote pointing to codereview.
After getting the source code, if you did not use the init-repository script to clone the source code as described in the guide, or you want to manually clone only a submodule, make sure you also [[#Setting up git hooks|manually set up the git commit hooks]] and [[#Setting up gerrit git remote|set up a git remote that point to Qt's gerrit instance]].
 
===Cloning Qt Creator===


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


If you are behind a SSH-blocking firewall, use the https protocol:
==Setting up git hooks==
 
'''NOTE:''' This is only needed if you did NOT use the init-repository script to get the source code, that automatically configures the git hooks for you.


<pre>
It's recommended to use the git hooks from the [https://code.qt.io/cgit/qt/qtrepotools.git/ qtrepotools] repo, which makes it simpler to fetch any updates to the git hooks by a <tt>git pull</tt>.
$ git remote add gerrit https://codereview.qt-project.org/p/qt/<qt5 or the submodule name you have checked out>
</pre>


For Qt 4.8, use
The git_post_commit_hook from the [https://code.qt.io/cgit/qt/qtrepotools.git/ qtrepotools] repository, gives you the checks of the [[Early Warning System|Sanity Bot]] locally.


This section assumes you have a qtrepotools checkout. <qt module checkout dir> is the path to the Qt repo where you want to set up the git hooks.
* On systems that support symlinks (Unix) the git hooks can be set up by creating symlinks to the scripts in <tt><qtrepotools dir>/git-hooks/</tt>:
<pre>
<pre>
$ git remote add gerrit ssh://codereview.qt-project.org/qt/qt
cd <qt module checkout dir>/.git/hooks
ln -s <path to qtrepotools dir>/git-hooks/gerrit_commit_msg_hook commit-msg
ln -s <path to qtrepotools dir>/git-hooks/git_post_commit_hook post-commit
</pre>
</pre>


If you are behind a SSH-blocking firewall, use the https protocol:
* An alternative, that should work on all platforms:
 
** Create <qt module checkout dir>/.git/hooks/{commit-msg,post-commit} files and add this to them (respectively):
commit-msg:
<pre>
<pre>
$ git remote add gerrit https://codereview.qt-project.org/p/qt/qt
#!/bin/sh
exec "<path to qtrepotools clone>/qtrepotools/git-hooks/gerrit_commit_msg_hook" "$@"
</pre>
</pre>


For Qt Creator, use
post-commit:
 
<pre>
<pre>
$ git remote add gerrit ssh://codereview.qt-project.org/qt-creator/qt-creator
#!/bin/sh
exec "<path to qtrepotools clone>/qtrepotools/git-hooks/git_post_commit_hook" "$@"
</pre>
</pre>
If you are behind a SSH-blocking firewall, use the https protocol:


<pre>
<pre>
$ git remote add gerrit https://codereview.qt-project.org/p/qt-creator/qt-creator
# Make them executable:
chmod u+x "<qt module checkout dir>/.git/hooks/commit-msg"
chmod u+x "<qt module checkout dir>/.git/hooks/post-commit"
</pre>
</pre>


=== Cloning repositories ===
'''NOTE:''' Starting with git 1.7.8, if <qt module checkout dir>/.git is a text file that contains <tt>gitdir: ../.git/modules/<module name></tt>, you need to put the git hooks for each sub-module in <tt><path to git super repo>/.git/modules/<module name>/hooks</tt> instead of <tt><qt module checkout dir>/.git/hooks</tt>.


You should clone from the [http://code.qt.io/ official mirror] and track changes from there in order to keep the load on Gerrit down.
==Setting up gerrit git remote==


==== Cloning Qt5 ====
In order to easily push your changes to Gerrit, we recommend setting a git remote that points to gerrit.
Follow the instructions in one (or more) of the following subsections, depending on which Qt repositories you want to setup Gerrit for.


Qt 5 is modularized into several repositories which are aggregated by the qt5 super repo.
===Qt5 gerrit git remote===
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:


<pre>
If you downloaded the sourcecode of Qt5 (or just one of its modules) using something else than the init-repository script, you will have to manually set up the gerrit git remote.
$ git clone git://code.qt.io/qt/qt5.git
You don't have to do this if you cloned the Qt5 sourcecode using the init-repository script as described in [[#Cloning Qt5]]. That handles it for you.
$ cd qt5
$ ./init-repository -f --no-webkit
</pre>


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:
<pre>
<pre>
[url "git://gitorious.org/qt/"]
git remote add gerrit ssh://codereview.qt-project.org/qt/<qt5 or the submodule name you have checked out>
        insteadOf = git://gitorious.org/~<username>/qt/
</pre>
</pre>


Alternatively, individual Qt5 submodules can be manually cloned as well. Follow '''Using Existing Clones''' above after cloning.
If you are behind a SSH-blocking firewall, use the https protocol:
 
==== Cloning Qt4 ====
 
<pre>
$ git clone git://code.qt.io/qt/qt.git
</pre>
 
Note that Qt4 does not have a <tt>master</tt> branch (since no 4.9 is planned). So, you should push changes to the <tt>4.8</tt> branch.
 
==== Cloning Qt Creator ====


<pre>
<pre>
$ git clone git://code.qt.io/qt-creator/qt-creator.git
git remote add gerrit https://codereview.qt-project.org/a/qt/<qt5 or the submodule name you have checked out>
</pre>
</pre>


Setup the gerrit remote
===QtCreator gerrit git remote===


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


Line 209: Line 242:


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


=== Pushing your local changes to gerrit ===
==Pushing your local changes to gerrit==


See [[Gerrit Introduction]].
See [[Gerrit Introduction]].

Latest revision as of 22:35, 12 February 2024


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

In order to be able to propose changes to those projects, you have to first setup your Gerrit account and get Qt's sourcecode, following the steps below:

  1. Set up a Gerrit account
  2. Tweak your SSH config as instructed here
  3. Use the recommended Git settings, defined here
  4. Get the source code of the projects you want to contribute to

Moreover, if you did not use the init-repository scripts to get the source code, you will have to manually:

  1. Set up the git commit hooks .
  2. Set up a Gerrit git remote.

Once all the steps above have been completed, you're ready to submit your patch to Qt!

See also:

How to get started - Gerrit registration

Before starting make sure you have a working Git installation and OpenSSH installed. ( or the bundled version of SSH that comes with recent Git packages).

  1. Create a Qt account, if you don't have one yet.
    • Note: Use an all-lowercase user name. Otherwise, Gerrit will lowercase it for you, and as it is case sensitive, you will have to use mismatched login names.
  2. Log into https://codereview.qt-project.org with your Qt account.
  3. Go to "Settings" -> "Profile", set your real name and register your email address, if it hasn't been automatically registered.
    • 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.
    • 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)
  4. Review and agree to the Qt Project's contribution license agreement (CLA) in Gerrit. You need to do this only once, unless the license changes.
    • If your company has a corporate contribution agreement, ask the admin of your company's Gerrit user group to add your account to this group.
    • More details about the CLA can be found here.
  5. Create a public SSH key for your PC, if you don't have one yet (see below under "Local Setup" for instructions)
  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

Proper configuration of SSH for your Gerrit account is necessary for the URLs in the next steps.

Note: On Windows, when not using OpenSSH, the ~/ shorthand used below can be equated with C:\Users\%USERNAME%\. Make replacements in the example as necessary.

Edit ~/.ssh/config with host information for Gerrit, as shown below. Do not copy comments marked by #, as they may not be ignored by your SSH client.

Host codereview.qt-project.org
    Port 29418
    # To avoid no mutual signature algorithm errors
    PubkeyAcceptedKeyTypes +ssh-rsa
    # Use your Gerrit username, not email or your username on your own machine.
    # You can view this from Settings in gerrit when logged in.
    User yourgerritusername
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/id_ed25519

Next, you will need to ensure that you have an SSH key pair, and make it known to Gerrit.

  1. If you have no key pair on this machine yet, generate one now. On the command line, invoke the following command, replacing "john-doe-win10-home" with a comment that uniquely describes the machine you're on:
    ssh-keygen -t ed25519 -C john-doe-win10-home -f ~/.ssh/id_ed25519
    Note: SSH keys are intended to be unique to each machine. New keys must be created for each additional machine logging in to Gerrit with SSH.
  2. Open the ~/.ssh/id_ed25519.pub file with a text editor and copy its entire contents into the clipboard.
  3. Log into https://codereview.qt-project.org and navigate to Settings (the gear symbol on the top right) → SSH Keys
  4. Paste the clipboard into the New SSH key entry, and hit the ADD NEW SSH KEY button.

You can verify that the connection works by running:
ssh codereview.qt-project.org

If the connection is functional, you should see a welcome message. End the connection by pressing Ctrl-C. If not, running ssh -v codereview.qt-project.org should give you an error message with details.

When making a connection to codereview.qt-project.org using ssh for the first time a prompt will show asking you to verify the authenticity (public key) of the host using it's fingerprint.

The authenticity of host '[codereview.qt-project.org]:29418 ([54.194.93.196]:29418)' can't be established.
ED25519 key fingerprint is SHA256:DwwqNluQyJVkOk+3bFMK6NwWYIGjMnqGP+R0k59e3CY.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

This prompt will only show the first time connecting to the host or when the host's public keys are changed. When prompted verify that the fingerprint for your key type is correct then accept the host's public key by typing yes, alternatively you could copy the fingerprint into the terminal for it to compare it to the provided fingerprint. Here is a list of current fingerprints for codereview.qt-project.org[1]:

ssh_host_ecdsa_384_key
384 SHA256:yMnqjnsJU0y6kfiyQQu8pYNGPFE7av5QxbeLdjTKNmk (ECDSA)

ssh_host_ecdsa_521_key
521 SHA256:kytLsqmLdG1KXLO/s3OxOajTYqf1+n7+YqqbOUzNbtE (ECDSA)

ssh_host_ecdsa_key
256 SHA256:El3+EYlXAGylCVo/Y/WYzPg7tS4fjejkepO1JVXUkb0 (ECDSA)

ssh_host_ed25519_key
256 SHA256:DwwqNluQyJVkOk+3bFMK6NwWYIGjMnqGP+R0k59e3CY (ED25519)

ssh_host_rsa_key
4096 SHA256:EPuL0PAbNuXXoye7X93ARF7/XALxA5XNAaE3p6M/L3g (RSA)

If the fingerprint the host provides is not included in this list, you might face an attempt for a man-in-the-middle attack or the host keys might have changed, if that happens search for the project's latest keys.

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

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

Getting the source code

Cloning Qt5

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

This guide will show you how to get and build the source code.

After getting the source code, if you did not use the init-repository script to clone the source code as described in the guide, or you want to manually clone only a submodule, make sure you also manually set up the git commit hooks and set up a git remote that point to Qt's gerrit instance.

Cloning Qt Creator

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

Setting up git hooks

NOTE: This is only needed if you did NOT use the init-repository script to get the source code, that automatically configures the git hooks for you.

It's recommended to use the git hooks from the qtrepotools repo, which makes it simpler to fetch any updates to the git hooks by a git pull.

The git_post_commit_hook from the qtrepotools repository, gives you the checks of the Sanity Bot locally.

This section assumes you have a qtrepotools checkout. <qt module checkout dir> is the path to the Qt repo where you want to set up the git hooks.

  • On systems that support symlinks (Unix) the git hooks can be set up by creating symlinks to the scripts in <qtrepotools dir>/git-hooks/:
cd <qt module checkout dir>/.git/hooks
ln -s <path to qtrepotools dir>/git-hooks/gerrit_commit_msg_hook commit-msg 
ln -s <path to qtrepotools dir>/git-hooks/git_post_commit_hook post-commit
  • An alternative, that should work on all platforms:
    • Create <qt module checkout dir>/.git/hooks/{commit-msg,post-commit} files and add this to them (respectively):

commit-msg:

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

post-commit:

#!/bin/sh
exec "<path to qtrepotools clone>/qtrepotools/git-hooks/git_post_commit_hook" "$@"
# Make them executable:
chmod u+x "<qt module checkout dir>/.git/hooks/commit-msg"
chmod u+x "<qt module checkout dir>/.git/hooks/post-commit"

NOTE: Starting with git 1.7.8, if <qt module checkout dir>/.git is a text file that contains gitdir: ../.git/modules/<module name>, you need to put the git hooks for each sub-module in <path to git super repo>/.git/modules/<module name>/hooks instead of <qt module checkout dir>/.git/hooks.

Setting up gerrit git remote

In order to easily push your changes to Gerrit, we recommend setting a git remote that points to gerrit. Follow the instructions in one (or more) of the following subsections, depending on which Qt repositories you want to setup Gerrit for.

Qt5 gerrit git remote

If you downloaded the sourcecode of Qt5 (or just one of its modules) using something else than the init-repository script, you will have to manually set up the gerrit git remote. You don't have to do this if you cloned the Qt5 sourcecode using the init-repository script as described in #Cloning Qt5. That handles it for you.

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/a/qt/<qt5 or the submodule name you have checked out>

QtCreator gerrit git 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/a/qt-creator/qt-creator

Pushing your local changes to gerrit

See Gerrit Introduction.