Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Gerrit"
(→Using Gerrit with EGit:) |
(→Gerrit setup: The /p was confusing, since unlike /r it was a placeholder. Expanded the placeholder and rendered it with underline.) |
||
(61 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | + | This wiki page desribes how to contribute to the Eclipse project via Gerrit hosted at https://git.eclipse.org/r | |
− | + | Gerrit is a web based code review system, facilitating online code reviews for projects using the Git version control system. For more information about Gerrit, please see http://code.google.com/p/gerrit/. | |
− | + | ||
− | * File [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=Git&short_desc=Enable%20Gerrit%20for% | + | == Enabling Gerrit for your Eclipse.org Project == |
+ | |||
+ | * File [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=Git&short_desc=Enable%20Gerrit%20for%20%3Cmy%20project%3E a bug] and specify for which project you'd like to enable Gerrit | ||
* Ask your Project Lead to +1 the request | * Ask your Project Lead to +1 the request | ||
+ | * Select a date for project committers to update their repo URLs | ||
* Choose one of the two options: | * Choose one of the two options: | ||
** I want project committers use Gerrit code review exclusively for my project. Everything must be reviewed -- no direct access to the main repo should be available. | ** I want project committers use Gerrit code review exclusively for my project. Everything must be reviewed -- no direct access to the main repo should be available. | ||
− | ** I want project committers to be able to bypass the Gerrit code review system and push changes directly to the git repo. | + | ** I want project committers to be able to bypass the Gerrit code review system and push changes directly to the git repo. '''Please note that this will have to be done via the 'new' Gerrit URLs(SSH and HTTPS). The original dev.eclipse.org SSH URLs will become inactive once Gerrit is enabled.''' |
− | = | + | :<font size="-1">(see {{bug|413753}} for a third option -- Eclipse Platform projects keep direct access to the Git repo)</font> |
− | + | ||
− | + | ||
− | + | *'''Note''': If you're adding all of your code repos to Gerrit, you will lose control of the 'container' for your project(/gitroot/projectname), as Webmaster will give the container to the Gerrit user. This means that you will not be able to create new repos via the initrepo command, instead you will have to contact Webmaster(via a bug). | |
− | + | == User Account == | |
− | + | * In order to contribute you need an [https://dev.eclipse.org/site_login/createaccount.php Eclipse user account] and agree to the Contributor License Agreement (CLA). If you are an Eclipse committer you already have one. | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | === SSH | + | To sign the 'CLA Log into the Eclipse projects [[Forges|forge]] (you will need to create an account with the Eclipse Foundation if you have not already done so); click on "Eclipse CLA" (on the top-right of [https://projects.eclipse.org this page]); and Complete the form. Be sure to use the same email address when you register for the account that you intend to use on Git commit records. |
+ | |||
+ | == Gerrit setup == | ||
+ | |||
+ | ===Gerrit Web UI=== | ||
+ | Logon to the Gerrit Web UI (see links below) using the email address you registered with your Eclipse Foundation account and password. | ||
+ | |||
+ | * Eclipse projects: [https://git.eclipse.org/r/ <code>https://git.eclipse.org/r/</code>] | ||
+ | * LocationTech projects: [https://git.locationtech.org/r/ <code>https://git.locationtech.org/r/</code>] | ||
+ | * PolarSys projects: [https://git.polarsys.org/r/ <code>https://git.polarsys.org/r/</code>] | ||
+ | |||
+ | ===Git over SSH=== | ||
+ | When accessing Gerrit over SSH from git or EGit use the username displayed in your user settings (e.g [https://git.eclipse.org/r/#/settings/ eclipse.org Gerrit]) and upload your public SSH key to Gerrit. | ||
+ | |||
+ | Upload keys for: | ||
+ | * [https://git.eclipse.org/r/#/settings/ssh-keys Eclipse projects] | ||
+ | * [https://git.locationtech.org/r/#/settings/ssh-keys LocationTech projects] | ||
+ | * [https://git.polarsys.org/r/#/settings/ssh-keys PolarsSys projects] | ||
+ | |||
+ | === SSH Keys === | ||
* Add one or more public SSH keys to [https://git.eclipse.org/r/#/settings/ssh-keys Gerrit here]. | * Add one or more public SSH keys to [https://git.eclipse.org/r/#/settings/ssh-keys Gerrit here]. | ||
* If you are '''absolutely certain''' you do not have keys already, you must create a public and private pair of SSH keys. It is strongly recommended that you [http://help.github.com/working-with-key-passphrases use a passphrase.] | * If you are '''absolutely certain''' you do not have keys already, you must create a public and private pair of SSH keys. It is strongly recommended that you [http://help.github.com/working-with-key-passphrases use a passphrase.] | ||
Line 33: | Line 49: | ||
* [http://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration Generating SSH key pair in Eclipse] | * [http://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration Generating SSH key pair in Eclipse] | ||
− | === Using Gerrit with the git command line | + | ===Gerrit push URL === |
− | *Upload your patch from Git to the target project: | + | |
+ | Gerrit SSH URl: <div style="width: 60em; font-size: 13px;"> | ||
+ | ssh://<u>username</u>@git.eclipse.org:29418/<u>path/to/repository</u>.git | ||
+ | </div> | ||
+ | |||
+ | {{Note|Gerrit SSH service versus SSH shell access| Gerrit's SSH service listens on port 29418 and isn't linked to the public keys on git.eclipse.org used for SSH shell access on port 22}} | ||
+ | |||
+ | ===Git over HTTPS=== | ||
+ | When accessing Gerrit over HTTPS from git or EGit use username and HTTP password displayed [https://git.eclipse.org/r/#/settings/http-password here] | ||
+ | Note: By default the password field is blank, be sure to generate a password using the "Generate Password" button. | ||
+ | |||
+ | Gerrit HTTPS URl: <div style="width: 60em; font-size: 13px;"> | ||
+ | https://git.eclipse.org/r/<u>path/to/repository</u>.git | ||
+ | </div> | ||
+ | |||
+ | === Be notified of upcoming changes === | ||
+ | |||
+ | Enabling Gerrit notifications is as important as enabling Bugzilla's ones when you are contributor on a project. Here is the place where you can subscribe to Gerrit notifications: https://git.eclipse.org/r/#/settings/projects | ||
+ | |||
+ | == Doing Code Reviews with Gerrit == | ||
+ | |||
+ | After someone pushed a change you can start reviewing the changes. | ||
+ | |||
+ | *Visit the [https://git.eclipse.org/r/ Eclipse Gerrit Code Review instance] to start reviewing. | ||
+ | *Use [https://git.eclipse.org/r/Documentation/user-search.html Gerrit queries] to filter the review list for changes you are interested in. | ||
+ | *[https://git.eclipse.org/r/#/settings/projects Register to watch projects] if you want to be notified by email on new or updated changes pushed for review. | ||
+ | *Adjust your [https://git.eclipse.org/r/#/settings/preferences Gerrit preferences] to customize it to your needs. | ||
+ | *See the [https://git.eclipse.org/r/Documentation/index.html#_user_guide Gerrit user guide] for more information about using Gerrit. | ||
+ | *The [http://wiki.eclipse.org/EGit/User_Guide#EGit_Tutorial_.28EclipseCon_Europe_Nov_2011.29 EGit tutorial] walks you through the basic steps of working with Gerrit and EGit. | ||
+ | * [http://www.vogella.com/articles/Gerrit/article.html Gerrit tutorial] by Lars Vogel | ||
+ | |||
+ | === Using Gerrit with the git command line === | ||
+ | *Upload your patch from Git to the target project, where <i>(project)</i> is the project specifier as per the Gerrit Web UI and may include a prefix, eg <i>cdt/org.eclipse.cdt.git</i>: | ||
<pre style="width: 60em;">git push ssh://username@git.eclipse.org:29418/(project).git HEAD:refs/for/master | <pre style="width: 60em;">git push ssh://username@git.eclipse.org:29418/(project).git HEAD:refs/for/master | ||
+ | </pre> | ||
+ | For example: | ||
+ | <pre style="width: 60em;">git push ssh://moberhuber@git.eclipse.org:29418/cdt/org.eclipse.cdt.git HEAD:refs/for/master | ||
</pre> | </pre> | ||
− | |||
− | |||
− | |||
==== Adding a dedicated remote ==== | ==== Adding a dedicated remote ==== | ||
Line 52: | Line 100: | ||
</pre> | </pre> | ||
− | === Using Gerrit with EGit | + | === Using Gerrit with EGit === |
Eclipse will look for your private key in the SSH2 Home location specified in the General>Network Connections>SSH2 Preference Page. If your <code>id_rsa</code> private key makes use of the AES-128-CBC algorithm (view the file as text to confirm), Eclipse will need at least <code>com.jcraft.jsch 0.1.44</code> to make use of it. | Eclipse will look for your private key in the SSH2 Home location specified in the General>Network Connections>SSH2 Preference Page. If your <code>id_rsa</code> private key makes use of the AES-128-CBC algorithm (view the file as text to confirm), Eclipse will need at least <code>com.jcraft.jsch 0.1.44</code> to make use of it. | ||
− | * Clone the repository and | + | * [[EGit/User_Guide#Cloning_Remote_Repositories | Clone the repository]] |
− | * Alternative approach | + | * Afterwards open the Git Repositories view and select '''Gerrit Configuration...''' in the context menu of the remote "origin" in the Git Repositories view to [http://wiki.eclipse.org/EGit/User_Guide#Gerrit_Configuration configure pushing to the code review queue]. |
+ | * Alternative approach: Add a new review remote in the Git Repositories view and select '''Gerrit Configuration...''' in the context menu of the remote | ||
** From the appropriate Remotes node, create a New Remote and choose to Configure for Push. A unique name should be chosen, ''review'' is suggested. | ** From the appropriate Remotes node, create a New Remote and choose to Configure for Push. A unique name should be chosen, ''review'' is suggested. | ||
+ | ** Changes committed to your local clone can now be pushed to Gerrit using the ''review'' Remote. You will be prompted for your private key's passphrase if Eclipse is looking for it in the right place. | ||
+ | * Instead of using the '''Gerrit Configuration...''' wizard you can do the configuration steps manually: | ||
** Change the main URI or Add a Push URI (your Gerrit user name must be used here) | ** Change the main URI or Add a Push URI (your Gerrit user name must be used here) | ||
*** <code>ssh://username@git.eclipse.org:29418/(project).git</code> | *** <code>ssh://username@git.eclipse.org:29418/(project).git</code> | ||
− | ** In the Ref | + | ** In the Ref mapping section, add a RefSpec specification of <code>HEAD:refs/for/master</code> |
− | + | ||
*Visit our [https://git.eclipse.org/r/ Gerrit Code Review instance] to start reviewing | *Visit our [https://git.eclipse.org/r/ Gerrit Code Review instance] to start reviewing | ||
+ | |||
+ | === Using the Mylyn Gerrit Connector === | ||
+ | The Mylyn Gerrit Connector can be installed from the Mylyn p2 repository, e.g. for juno from http://download.eclipse.org/mylyn/releases/juno. | ||
+ | |||
+ | It contains several useful features: | ||
+ | * Cloning from Gerrit and automatic configuration | ||
+ | ** The wizards "Import Projects from Git" and "Clone Git Repository" will offer the possibility to browse the list of repositories on Gerrit servers and to clone selected repositories. After cloning the Gerrit configuration will be done automatically. | ||
+ | * Importing Gerrit changes as Mylyn tasks | ||
+ | * Fetching patch sets directly from the task editor | ||
+ | * Reviewing changes in the task editor | ||
+ | * Submitting changes from the task editor | ||
+ | |||
+ | === Bypassing code review === | ||
+ | In some cases it may be desirable to bypass code review. Your Gerrit-enabled project must be configured to allow bypassing code review. Please ask Webmaster if you are not sure. | ||
+ | |||
+ | Please see [http://eclipsewebmaster.blogspot.ca/2013/11/using-gerrit-code-review-without-code.html Denis' blog post] outlining how to bypass code review. | ||
+ | |||
+ | = Gerrit Code Review Cheatsheet = | ||
+ | |||
+ | == Install the commit-msg hook in your repository == | ||
+ | <pre style="width: 60em;">scp -p -P 29418 username@git.eclipse.org:hooks/commit-msg .git/hooks/ | ||
+ | </pre> | ||
+ | This will ask for a password. It is the password that you have to generate in the ''SSH Keys'' section of settings in your Gerrit account. | ||
+ | |||
+ | You can alternatively [https://git.eclipse.org/r/tools/hooks/commit-msg download the file] or use curl to install it via https: | ||
+ | <pre style="width: 60em;"> | ||
+ | # if you are behind a proxy you may need | ||
+ | export https_proxy=https://<proxy-host>[:<proxy-port>] | ||
+ | curl https://git.eclipse.org/r/tools/hooks/commit-msg > .git/hooks/commit-msg | ||
+ | </pre> | ||
+ | |||
+ | The [http://gerrit.googlecode.com/svn/documentation/2.1.2/cmd-hook-commit-msg.html hook] helps append a Change-Id to your commit message. | ||
+ | |||
+ | EGit can also [[EGit/User_Guide#Committing_Changes | generate the Change-Id]] and can also be configured to [[EGit/User_Guide#Gerrit_Configuration | automatically include it]]. | ||
+ | |||
+ | == Troubleshooting == | ||
+ | |||
+ | If something went wrong you should check your log entries like this: | ||
+ | <pre style="width:60em;"> | ||
+ | git log -n <number of commits you want to view> | ||
+ | </pre> | ||
+ | |||
+ | Each commit should provide the necessary properties as required by the Gerrit configuration. Let's see this example (accessible in your account): | ||
+ | |||
+ | [[File:Repo.png]] | ||
+ | |||
+ | Depending on your settings ''1'' and ''2'' you must provide the corresponding values in your commit messages. So for this example the fields ""Change-Id"" and ""Signed-off-by"" are enabled which means that each commit must contain the following lines (just an example): | ||
+ | |||
+ | <pre style="width:60em;"> | ||
+ | Change-Id: I786013835117ba003e185eaffd345d62868171ff | ||
+ | Signed-off-by: Jim Belushi <jim.belushi@not-so-funny.com> | ||
+ | </pre> | ||
+ | |||
+ | |||
+ | == To create a new change == | ||
+ | |||
+ | <pre style="width: 60em;">git push ssh://username@git.eclipse.org:29418/repository.git HEAD:refs/for/master | ||
+ | </pre> | ||
+ | Or, if you've followed the instructions on [[#Adding_a_dedicated_remote | Adding a dedicated remote]] you can simply do: | ||
+ | <pre style="width: 60em;">git push review | ||
+ | </pre> | ||
+ | Since the current repository has the right definition for 'review', you won't need to remember the canonical push URL | ||
+ | |||
+ | == To update an existing change with a new commit == | ||
+ | <pre style="width: 60em;">git push ssh://username@git.eclipse.org:29418/repository.git HEAD:refs/for/master | ||
+ | </pre> | ||
+ | This works because Gerrit links the new commit to the prior change based upon the Change-Id footer in the commit message. (This is automatically generated by the commit-msg hook you installed above.) If you refuse to use the commit-msg hook, or don't have a Change-Id footer, you should read the Gerrit documentation on [https://git.eclipse.org/r/Documentation/user-changeid.html change-id lines] and [https://git.eclipse.org/r/Documentation/user-upload.html#push_replace replacing changes]. | ||
+ | |||
+ | '''Note:''' To be picked up by Gerrit, a Change-Id line must be in the bottom portion (last paragraph) of a commit message, and may be mixed together with the Signed-off-by, Acked-by, or other such footers. So if your Change-Id line is ignored it's probably not in the last paragraph :). | ||
+ | |||
+ | == To compare bulk diffs using Git == | ||
+ | |||
+ | Since each Gerrit review patchset actually commits its own tree, you can pull out the trees and compare them. | ||
+ | |||
+ | If you've got a large changeset, and you want to be able to do diffs between them via (command line) git instead of browsing on the web, then you can fetch the individual changes and then perform a diff. For example, [http://git.eclipse.org/r/2 http://git.eclipse.org/r/2] shows the 'download' section for each patchset. In this case, it looks like: | ||
+ | |||
+ | *Patch Set 1 <code>git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/1 (1d3331a91bd477d3f70cde9613576cf9688ac358)</code> | ||
+ | *Patch Set 2 <code>git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/2 (13ab9a43d4d512963556a92e889b1204d32f8e68)</code> | ||
+ | *Patch Set 3 <code>git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/3 (d14cc645655683ba3e30a35833fb2282142e898f)</code> | ||
+ | *Patch Set 4 <code>git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/4 (43de8d385b614c72fd796e17da75d381f6e0cc25)</code> | ||
+ | |||
+ | Performing a <code>git pull</code> will both get the bits and merge them into your tree, which won't do what you want for comparison. So, in order to get the bits (but not merge), you need to do a <code>git fetch</code> instead. Let's say we want to diff the last two patches against each other rather than reviewing the entire patchset again: | ||
+ | <pre>git fetch ssh://username@git.eclipse.org/jgit refs/changes/02/2/3 | ||
+ | git fetch ssh://username@git.eclipse.org/jgit refs/changes/02/2/4 | ||
+ | |||
+ | git diff d14cc645655683ba3e30a35833fb2282142e898f 43de8d385b614c72fd796e17da75d381f6e0cc25 | ||
+ | |||
+ | # or git diff d14cc6 43de8d | ||
+ | </pre> | ||
+ | If you're doing this from within an already checked out project, you can do <code>git fetch origin</code> (or any other remote name in <code>.git/config}</code>. | ||
+ | |||
+ | Git fetched data will stay around in your repository, but will be 'orphaned' if no references point to it. To clean up, you can run <code>git gc</code> or wait until this happens automatically. | ||
+ | |||
+ | == To approve a change == | ||
+ | |||
+ | *Click on Publish Comments | ||
+ | *Vote with the radio buttons | ||
+ | |||
+ | == To add a reviewer == | ||
+ | |||
+ | Once you've pushed your commit to Gerrit for review, you can go to the web page (https://git.eclipse.org/r/) and see your changes. By clicking on the review, there's an option to add a reviewer by e-mail address; they'll then be sent a message indicating that they'd like your review on the item. | ||
+ | |||
+ | == Code Review == | ||
+ | |||
+ | The code review category indicates your opinion on the quality of the code, and how well it fits within the purpose of the existing surrounding code. A +2 vote from any committer is required before submission can occur. A -2 vote from any committer will block submission. | ||
+ | |||
+ | == IP Review == | ||
+ | |||
+ | Follow the rules given in [[Development_Resources/Handling_Git_Contributions#Gerrit|Handling Git Contributions received via Gerrit]]. | ||
+ | |||
+ | == Verifying Changes on Hudson using Gerrit Trigger Plugin == | ||
+ | |||
+ | You may use the [https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger Jenkins Gerrit Trigger Plugin] installed on [https://hudson.eclipse.org/sandbox/ sandbox Hudson] in order to run a Hudson job to verify each new patchset uploaded to Gerrit for code review. Hudson will then also vote on these changes using the "Verify" voting category. | ||
+ | |||
+ | [[Image:Jgit.gerrit-reviewer.png]] | ||
+ | |||
+ | [[Image:Jgit.gerrit-vote.png]] | ||
+ | |||
+ | In order to setup a verification build job [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community file a bug in Bugzilla] on "Eclipse Foundation > Community" using component "Hudson sandbox" and ask the webmaster to create a new build job on sandbox Hudson. Then | ||
+ | configure the new job following the description given on the [https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger plugin's home page]. Note: You may need to ask in the bug to configure the Gerrit plugin itself. | ||
+ | |||
+ | The configuration sections for the Git plugin and the Gerrit trigger plugin of the verification job used by the JGit project may serve as an example. | ||
+ | |||
+ | |||
+ | ====General configuration settings==== | ||
+ | |||
+ | # Check "This build is parametrized". Click the "Add" button and select "String Parameter". Set the parameter 'Name' to "GERRIT_REFSPEC" and 'Default Value' to 'refs/heads/master'. | ||
+ | |||
+ | ====Configuration of Source Code Management==== | ||
+ | |||
+ | # Under "Source Code Management" select Git. Under "Branches to build", click on "Advanced" and change the '''Choosing Strategy''' to '''Gerrit Trigger'''. | ||
+ | # Follow the settings depicted below: | ||
+ | |||
+ | [[Image:Jgit.gerrit-git-config.png]] | ||
+ | |||
+ | ====Configuration of Gerrit trigger plugin==== | ||
+ | |||
+ | # Follow the settings depicted below: (Important: Under "Branches" in the "Gerrit Trigger" section, make sure that the combo-box is set to "Path" and the value to "**".) | ||
+ | |||
+ | [[Image:Jgit.gerrit-gerrit-config.png]] | ||
+ | |||
+ | ====Configuration of the build action==== | ||
+ | |||
+ | Under "Build" click the "Add a build step" button, and select the appropriate action. The actual action depends on what you want Hudson to do. A typical example, for projects build with Maven is to select "Invoke Maven 3" and set "Maven 3" to "apache-maven-latest" and "Goals" to "clean verify". | ||
+ | |||
+ | |||
+ | [[Category:Gerrit]] |
Revision as of 14:41, 20 January 2016
This wiki page desribes how to contribute to the Eclipse project via Gerrit hosted at https://git.eclipse.org/r
Gerrit is a web based code review system, facilitating online code reviews for projects using the Git version control system. For more information about Gerrit, please see http://code.google.com/p/gerrit/.
Contents
- 1 Enabling Gerrit for your Eclipse.org Project
- 2 User Account
- 3 Gerrit setup
- 4 Doing Code Reviews with Gerrit
- 5 Gerrit Code Review Cheatsheet
- 5.1 Install the commit-msg hook in your repository
- 5.2 Troubleshooting
- 5.3 To create a new change
- 5.4 To update an existing change with a new commit
- 5.5 To compare bulk diffs using Git
- 5.6 To approve a change
- 5.7 To add a reviewer
- 5.8 Code Review
- 5.9 IP Review
- 5.10 Verifying Changes on Hudson using Gerrit Trigger Plugin
Enabling Gerrit for your Eclipse.org Project
- File a bug and specify for which project you'd like to enable Gerrit
- Ask your Project Lead to +1 the request
- Select a date for project committers to update their repo URLs
- Choose one of the two options:
- I want project committers use Gerrit code review exclusively for my project. Everything must be reviewed -- no direct access to the main repo should be available.
- I want project committers to be able to bypass the Gerrit code review system and push changes directly to the git repo. Please note that this will have to be done via the 'new' Gerrit URLs(SSH and HTTPS). The original dev.eclipse.org SSH URLs will become inactive once Gerrit is enabled.
- (see bug 413753 for a third option -- Eclipse Platform projects keep direct access to the Git repo)
- Note: If you're adding all of your code repos to Gerrit, you will lose control of the 'container' for your project(/gitroot/projectname), as Webmaster will give the container to the Gerrit user. This means that you will not be able to create new repos via the initrepo command, instead you will have to contact Webmaster(via a bug).
User Account
- In order to contribute you need an Eclipse user account and agree to the Contributor License Agreement (CLA). If you are an Eclipse committer you already have one.
To sign the 'CLA Log into the Eclipse projects forge (you will need to create an account with the Eclipse Foundation if you have not already done so); click on "Eclipse CLA" (on the top-right of this page); and Complete the form. Be sure to use the same email address when you register for the account that you intend to use on Git commit records.
Gerrit setup
Gerrit Web UI
Logon to the Gerrit Web UI (see links below) using the email address you registered with your Eclipse Foundation account and password.
- Eclipse projects:
https://git.eclipse.org/r/
- LocationTech projects:
https://git.locationtech.org/r/
- PolarSys projects:
https://git.polarsys.org/r/
Git over SSH
When accessing Gerrit over SSH from git or EGit use the username displayed in your user settings (e.g eclipse.org Gerrit) and upload your public SSH key to Gerrit.
Upload keys for:
SSH Keys
- Add one or more public SSH keys to Gerrit here.
- If you are absolutely certain you do not have keys already, you must create a public and private pair of SSH keys. It is strongly recommended that you use a passphrase.
- Generating SSH key pair on command line
ssh-keygen -t rsa -C "your_email@youremail.com"
- Execute SSH once to accept the host key (or copy it from the registration web page)
ssh -p 29418 username@git.eclipse.org
Gerrit push URL
Gerrit SSH URl:ssh://username@git.eclipse.org:29418/path/to/repository.git
Git over HTTPS
When accessing Gerrit over HTTPS from git or EGit use username and HTTP password displayed here Note: By default the password field is blank, be sure to generate a password using the "Generate Password" button.
Gerrit HTTPS URl:https://git.eclipse.org/r/path/to/repository.git
Be notified of upcoming changes
Enabling Gerrit notifications is as important as enabling Bugzilla's ones when you are contributor on a project. Here is the place where you can subscribe to Gerrit notifications: https://git.eclipse.org/r/#/settings/projects
Doing Code Reviews with Gerrit
After someone pushed a change you can start reviewing the changes.
- Visit the Eclipse Gerrit Code Review instance to start reviewing.
- Use Gerrit queries to filter the review list for changes you are interested in.
- Register to watch projects if you want to be notified by email on new or updated changes pushed for review.
- Adjust your Gerrit preferences to customize it to your needs.
- See the Gerrit user guide for more information about using Gerrit.
- The EGit tutorial walks you through the basic steps of working with Gerrit and EGit.
- Gerrit tutorial by Lars Vogel
Using Gerrit with the git command line
- Upload your patch from Git to the target project, where (project) is the project specifier as per the Gerrit Web UI and may include a prefix, eg cdt/org.eclipse.cdt.git:
git push ssh://username@git.eclipse.org:29418/(project).git HEAD:refs/for/master
For example:
git push ssh://moberhuber@git.eclipse.org:29418/cdt/org.eclipse.cdt.git HEAD:refs/for/master
Adding a dedicated remote
Since git can have multiple remotes, you can define one to be used to refer to Gerrit to save typing. Inside a previously checked-out repository you can run:
cd path/to/project git config remote.review.url ssh://username@git.eclipse.org:29418/(project).git git config remote.review.push HEAD:refs/for/master
You can now submit review requests from either repository using:
git push review
Using Gerrit with EGit
Eclipse will look for your private key in the SSH2 Home location specified in the General>Network Connections>SSH2 Preference Page. If your id_rsa
private key makes use of the AES-128-CBC algorithm (view the file as text to confirm), Eclipse will need at least com.jcraft.jsch 0.1.44
to make use of it.
- Clone the repository
- Afterwards open the Git Repositories view and select Gerrit Configuration... in the context menu of the remote "origin" in the Git Repositories view to configure pushing to the code review queue.
- Alternative approach: Add a new review remote in the Git Repositories view and select Gerrit Configuration... in the context menu of the remote
- From the appropriate Remotes node, create a New Remote and choose to Configure for Push. A unique name should be chosen, review is suggested.
- Changes committed to your local clone can now be pushed to Gerrit using the review Remote. You will be prompted for your private key's passphrase if Eclipse is looking for it in the right place.
- Instead of using the Gerrit Configuration... wizard you can do the configuration steps manually:
- Change the main URI or Add a Push URI (your Gerrit user name must be used here)
- In the Ref mapping section, add a RefSpec specification of
HEAD:refs/for/master
- Visit our Gerrit Code Review instance to start reviewing
Using the Mylyn Gerrit Connector
The Mylyn Gerrit Connector can be installed from the Mylyn p2 repository, e.g. for juno from http://download.eclipse.org/mylyn/releases/juno.
It contains several useful features:
- Cloning from Gerrit and automatic configuration
- The wizards "Import Projects from Git" and "Clone Git Repository" will offer the possibility to browse the list of repositories on Gerrit servers and to clone selected repositories. After cloning the Gerrit configuration will be done automatically.
- Importing Gerrit changes as Mylyn tasks
- Fetching patch sets directly from the task editor
- Reviewing changes in the task editor
- Submitting changes from the task editor
Bypassing code review
In some cases it may be desirable to bypass code review. Your Gerrit-enabled project must be configured to allow bypassing code review. Please ask Webmaster if you are not sure.
Please see Denis' blog post outlining how to bypass code review.
Gerrit Code Review Cheatsheet
Install the commit-msg hook in your repository
scp -p -P 29418 username@git.eclipse.org:hooks/commit-msg .git/hooks/
This will ask for a password. It is the password that you have to generate in the SSH Keys section of settings in your Gerrit account.
You can alternatively download the file or use curl to install it via https:
# if you are behind a proxy you may need export https_proxy=https://<proxy-host>[:<proxy-port>] curl https://git.eclipse.org/r/tools/hooks/commit-msg > .git/hooks/commit-msg
The hook helps append a Change-Id to your commit message.
EGit can also generate the Change-Id and can also be configured to automatically include it.
Troubleshooting
If something went wrong you should check your log entries like this:
git log -n <number of commits you want to view>
Each commit should provide the necessary properties as required by the Gerrit configuration. Let's see this example (accessible in your account):
Depending on your settings 1 and 2 you must provide the corresponding values in your commit messages. So for this example the fields ""Change-Id"" and ""Signed-off-by"" are enabled which means that each commit must contain the following lines (just an example):
Change-Id: I786013835117ba003e185eaffd345d62868171ff Signed-off-by: Jim Belushi <jim.belushi@not-so-funny.com>
To create a new change
git push ssh://username@git.eclipse.org:29418/repository.git HEAD:refs/for/master
Or, if you've followed the instructions on Adding a dedicated remote you can simply do:
git push review
Since the current repository has the right definition for 'review', you won't need to remember the canonical push URL
To update an existing change with a new commit
git push ssh://username@git.eclipse.org:29418/repository.git HEAD:refs/for/master
This works because Gerrit links the new commit to the prior change based upon the Change-Id footer in the commit message. (This is automatically generated by the commit-msg hook you installed above.) If you refuse to use the commit-msg hook, or don't have a Change-Id footer, you should read the Gerrit documentation on change-id lines and replacing changes.
Note: To be picked up by Gerrit, a Change-Id line must be in the bottom portion (last paragraph) of a commit message, and may be mixed together with the Signed-off-by, Acked-by, or other such footers. So if your Change-Id line is ignored it's probably not in the last paragraph :).
To compare bulk diffs using Git
Since each Gerrit review patchset actually commits its own tree, you can pull out the trees and compare them.
If you've got a large changeset, and you want to be able to do diffs between them via (command line) git instead of browsing on the web, then you can fetch the individual changes and then perform a diff. For example, http://git.eclipse.org/r/2 shows the 'download' section for each patchset. In this case, it looks like:
- Patch Set 1
git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/1 (1d3331a91bd477d3f70cde9613576cf9688ac358)
- Patch Set 2
git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/2 (13ab9a43d4d512963556a92e889b1204d32f8e68)
- Patch Set 3
git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/3 (d14cc645655683ba3e30a35833fb2282142e898f)
- Patch Set 4
git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/4 (43de8d385b614c72fd796e17da75d381f6e0cc25)
Performing a git pull
will both get the bits and merge them into your tree, which won't do what you want for comparison. So, in order to get the bits (but not merge), you need to do a git fetch
instead. Let's say we want to diff the last two patches against each other rather than reviewing the entire patchset again:
git fetch ssh://username@git.eclipse.org/jgit refs/changes/02/2/3 git fetch ssh://username@git.eclipse.org/jgit refs/changes/02/2/4 git diff d14cc645655683ba3e30a35833fb2282142e898f 43de8d385b614c72fd796e17da75d381f6e0cc25 # or git diff d14cc6 43de8d
If you're doing this from within an already checked out project, you can do git fetch origin
(or any other remote name in .git/config}
.
Git fetched data will stay around in your repository, but will be 'orphaned' if no references point to it. To clean up, you can run git gc
or wait until this happens automatically.
To approve a change
- Click on Publish Comments
- Vote with the radio buttons
To add a reviewer
Once you've pushed your commit to Gerrit for review, you can go to the web page (https://git.eclipse.org/r/) and see your changes. By clicking on the review, there's an option to add a reviewer by e-mail address; they'll then be sent a message indicating that they'd like your review on the item.
Code Review
The code review category indicates your opinion on the quality of the code, and how well it fits within the purpose of the existing surrounding code. A +2 vote from any committer is required before submission can occur. A -2 vote from any committer will block submission.
IP Review
Follow the rules given in Handling Git Contributions received via Gerrit.
Verifying Changes on Hudson using Gerrit Trigger Plugin
You may use the Jenkins Gerrit Trigger Plugin installed on sandbox Hudson in order to run a Hudson job to verify each new patchset uploaded to Gerrit for code review. Hudson will then also vote on these changes using the "Verify" voting category.
In order to setup a verification build job file a bug in Bugzilla on "Eclipse Foundation > Community" using component "Hudson sandbox" and ask the webmaster to create a new build job on sandbox Hudson. Then configure the new job following the description given on the plugin's home page. Note: You may need to ask in the bug to configure the Gerrit plugin itself.
The configuration sections for the Git plugin and the Gerrit trigger plugin of the verification job used by the JGit project may serve as an example.
General configuration settings
- Check "This build is parametrized". Click the "Add" button and select "String Parameter". Set the parameter 'Name' to "GERRIT_REFSPEC" and 'Default Value' to 'refs/heads/master'.
Configuration of Source Code Management
- Under "Source Code Management" select Git. Under "Branches to build", click on "Advanced" and change the Choosing Strategy to Gerrit Trigger.
- Follow the settings depicted below:
Configuration of Gerrit trigger plugin
- Follow the settings depicted below: (Important: Under "Branches" in the "Gerrit Trigger" section, make sure that the combo-box is set to "Path" and the value to "**".)
Configuration of the build action
Under "Build" click the "Add a build step" button, and select the appropriate action. The actual action depends on what you want Hudson to do. A typical example, for projects build with Maven is to select "Invoke Maven 3" and set "Maven 3" to "apache-maven-latest" and "Goals" to "clean verify".