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.
EGit/Contributor Guide
EGit | |
Website | |
Download | |
Community | |
Mailing List • Forums • IRC • mattermost | |
Issues | |
Open • Help Wanted • Bug Day | |
Contribute | |
Browse Source • Project Set File |
Contents
Obtaining Sources
EGit and JGit are self hosted in Git. Browse the repositories in gitweb.
There are several ways to obtain a copy of each repository:
From the command line
git clone git://egit.eclipse.org/jgit.git jgit git clone git://egit.eclipse.org/egit.git egit
From an installed EGit plugin
- File > Import > Git > Git Repository
- Enter URI:
git://egit.eclipse.org/jgit.git
- Import projects
- File > Import > Git > Git Repository
- Enter URI:
git://egit.eclipse.org/egit.git
- Import projects
To compile you also need libraries from Orbit.
Builds
EGit and JGit builds run on build.eclipse.org via Hudson using
Hudson
JGit
- JGit can be built using Maven 2 or 3.
- JGit packaging project (Eclipse feature and update site) are built using Maven 3 and Tycho.
EGit
- EGit is built using Maven 3 and Tycho.
Mailing Lists
If you're interested in following builds, please check out the following mailing lists:
Maven Build Sequence
- Due to a current limitation of Tycho 0.8.0 it is not possible to mix pom-first and manifest-first builds in the same reactor build hence the pom-first JGit build has to run separately before the build for the manifest-first JGit packaging project.
- The 3 builds must share the same local Maven repository otherwise dependencies between these builds cannot be resolved.
- To run the build behind a firewall follow http://maven.apache.org/guides/mini/guide-proxies.html and for Tycho additionally pass proxy settings via system properties (https://issues.sonatype.org/browse/TYCHO-279): mvn -DproxyHost=myproxy -DproxyPort=1080 ...
Complete build sequence for a clean build (assuming $M2_HOME/bin is on the path and local Maven repository at ~/.m2/repository):
[~/src/jgit] $ mvn clean install [INFO] Scanning for projects... ... [~/src/jgit] $ mvn -f org.eclipse.jgit.packaging/pom.xml clean install [INFO] Scanning for projects... ... [~/src/jgit] $ cd ../egit [~/src/egit] $ mvn clean install [INFO] Scanning for projects... ...
Documentation
The EGit project sources its documentation from the wiki and generates Eclipse help content from it (under the covers, we are using Mylyn WikiText to make this possible). This significantly lowers the barrier for people to contribute documentation to the EGit project. To contribute documentation, simply modify the EGit User's Guide.
The documentation is contained in the org.eclipse.egit.doc plug-in. The build-helper.xml drives the generation of the help content.
The aim is to generate new documentation every month or so (or just on demand). If you're making big changes or want the documentation refreshed, please let us know on the egit-dev mailing list.
Tests
JGit Unit Tests
The JGit unit tests are executed during the maven build for the bundle org.eclipse.jgit.test. To run them from the Eclipse workbench use the launch configurations which are part of the sources of the bundle org.eclipse.jgit.test.
JGit HTTP Tests
The JGit HTTP tests rely on the Jetty web container. To run these tests from Eclipse download Jetty 7.0.1.v20091125 and unzip it in some folder. Then add its lib folder to your target platform :
- Preferences > Plug-in Development > Target Platform
- select "Running Platform (Active)"
- Add the lib folder of the Jetty distribution
EGit Core Tests
The EGit Core tests are executed during the maven build for the bundle org.eclipse.egit.core.test. To run them from the Eclipse workbench use the launch configuration which is part of the sources of the test bundle org.eclipse.egit.core.test.
EGit UI Tests
The EGit UI tests are using SWTBot, to run them you need 'SWTBot for Eclipse Testing' feature.
Manual
Install the SWTBot matching your Eclipse version from http://www.eclipse.org/swtbot/downloads.php
Automatic
Using target platform definition file:
- http://egit.eclipse.org/r/382 provides core Galileo-based dependencies and SWTBot for Eclipse Testing feature. You still need JGit projects to be opened in the workspace.
- http://egit.eclipse.org/r/383 extends the previous one with JGit from the nightly update site. This patch makes it possible to develop EGit plug-ins without checking out JGit projects.
How to use it:
- pull either first or both patches
- open Target Platform Preferences page (Window - Preferences - Plug-in development - Target Platform)
- activate 'SWTBot-based UI plug-in tests' target platform
During Maven Build
Integration of EGit UI tests into the maven build is currently under review : http://egit.eclipse.org/r/#change,558
Website
The EGit and JGit websites are located in a CVS repository on the Eclipse Foundation's servers.
egit
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org/cvsroot/org.eclipse
- Use module egit
- Finish
jgit
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org/cvsroot/org.eclipse
- Use module jgit
- Finish
Contributing Patches
Review the following style guides:
Currently the project is alpha-testing Gerrit Code Review for Git based patch submission and review. To use the alpha testing instance hosted at eclipse.org:
- Register a user account
- Use Register New Email to register your email address with our Gerrit Code Review server. This step is required to validate the address is correct.
- Add one or more public SSH keys
- Execute SSH once to accept the host key (or copy it from the registration web page)
ssh -p 29418 username@egit.eclipse.org
- Confirm you agree to the Eclipse.org Terms of Service by completing the Individual Contributor agreement.
- Upload your patch from Git to the target project:
- JGit
git push ssh://username@egit.eclipse.org:29418/jgit.git HEAD:refs/for/master
- EGit
git push ssh://username@egit.eclipse.org:29418/egit.git HEAD:refs/for/master
- Visit our Gerrit Code Review instance to start reviewing
Or, create a new bug and attach a Git formatted patch file, as produced by the `git format-patch` tool.
Commit message guidelines
- The commit message header should fit on one line
- The commit message have newline characters after every 60-70 characters.
- If there is an associated bug number in Bugzilla about it, it should come before Gerrit's Change-Id entry.
- The first sentence should be a clear and concise description about the change.
- Enter a newline before providing a more detailed description about the change.
Fix the commit dialog to respect the workbench's selection Originally, the commit dialog would automatically check off all files in the dialog. This behaviour contradicts a user's expectation because their selection in the workbench is completely ignored. The code has been corrected to only preselect what the user has actually selected. Bug: 12345 Change-Id: I71ac4844ab9d2f848352eba9252090c586b4146a
Adding a 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/jgit git config remote.review.url ssh://username@egit.eclipse.org:29418/jgit.git git config remote.review.push HEAD:refs/for/master cd path/to/egit git config remote.review.url ssh://username@egit.eclipse.org:29418/egit.git git config remote.review.push HEAD:refs/for/master
You can now submit review requests from either repository using:
git push review
Sending patches by mail
Although sending patches by mail is the approved way of interacting with, and asking feedback from, the Git project, please don't send patches via git send-email. Instead, please use git format-patch to generate the mbox
, and then attach that to an item in bugzilla as per the above SUBMITTING_PATCHES guides.
If you're sending a work-in-progress for a review, be aware that you can also attach work-in-progress (or RFC) items to Bugzilla; it's not just for finished patches.
However, it's generally preferred that you send items which you want comments on via Gerrit as per #Adding_a_remote, since Gerrit allows comments to be added in-line and allows the opportunity to send multiple versions of a patch after changes are made. Once a change has been submitted to Gerrit, you can then mail the developer mailing list with a request to review your change via URL or get Gerrit to send the mail on your behalf.
Gerrit Code Review Cheatsheet
Install the commit-msg hook in your repository
scp -p -P 29418 username@egit.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. The hook helps append a Change-Id to your commit message.
To create a new change
- JGit
git push ssh://username@egit.eclipse.org:29418/jgit.git HEAD:refs/for/master
- EGit
git push ssh://username@egit.eclipse.org:29418/egit.git HEAD:refs/for/master
Or, if you've followed the instructions on #Adding_a_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@egit.eclipse.org:29418/egit.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://egit.eclipse.org/r/2 shows the 'download' section for each patchset. In this case, it looks like:
- Patch Set 1
git pull git://egit.eclipse.org/jgit refs/changes/02/2/1 (1d3331a91bd477d3f70cde9613576cf9688ac358)
- Patch Set 2
git pull git://egit.eclipse.org/jgit refs/changes/02/2/2 (13ab9a43d4d512963556a92e889b1204d32f8e68)
- Patch Set 3
git pull git://egit.eclipse.org/jgit refs/changes/02/2/3 (d14cc645655683ba3e30a35833fb2282142e898f)
- Patch Set 4
git pull git://egit.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 git://egit.eclipse.org/jgit refs/changes/02/2/3 git fetch git://egit.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 (http://egit.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
The IP review category indicates whether or not the change has been properly logged under the eclipse IP process. Under that process, any committer should mark his/her change +1 if they were the sole author of the change. For any other change, a committer should only mark +1 after ensuring the corresponding bug in Bugzilla has been updated with the iplog flag, or the corresponding CQ has been marked checkintocvs. For contributions from external contributors have a look at the detailed rules. A +1 vote is required to submit a change, while a -1 vote will block submission.
Libraries from Orbit
Import Team Project Set
The simplest way to import the 3rd party libraries needed to compile JGit and Egit:
- Download the Team Project Set for git dependencies
- File > Import > Team > Team Project Set
- Next
- Select the downloaded GitDependencies.psf
- logon with user "anonymous", leave password field blank
- Finish
Manual Import
com.jcraft.jsch
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org/cvsroot/tools
- Use module org.eclipse.orbit/com.jcraft.jsch
- Finish
- Right click on the project > Team > Switch to another branch
- Select tag from following list
- Refresh Tags
- Branches > v0_1_41
org.kohsuke.args4j
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org/cvsroot/tools
- Use module org.eclipse.orbit/org.kohsuke.args4j
- Finish
- Right click on the project > Team > Switch to another branch
- Select tag from following list
- Refresh Tags
- Branches > v2_0_12
javax.servlet
- File > Import > CVS > Projects from CVS
- Select URL :pserver:anonymous@dev.eclipse.org/cvsroot/tools
- Use module org.eclipse.orbit/javax.servlet
- Finish
- Right click on the project > Team > Switch to another branch
- Select tag from following list
- Refresh Tags
- Branches > v2_5