git with eclipse (egit) - tutorial
DESCRIPTION
GITTRANSCRIPT
317
Free tutorial, donate
to support
by Lars Vogel
Git with Eclipse (EGit) - Tutorial
Lars Vogel
Version 3.1
Copyright © 2009, 2010, 2011, 2012, 2013 Lars Vogel
13.01.2013
Revision History
Revision 0.1 11.12.2009 Lars
Vogel
Created
Revision 0.2 - 3.1 12.12.2009 - 13.01.2013 Lars
Vogel
bug fixes and enhancements
Git with Eclipse (EGit)
This tutorial describes the usage of EGit; an Eclipse plug-in to use the distributed version control
system Git. This tutorial is based on Eclipse 4.2 (Juno).
Table of Contents
1. What is EGit
2. Command line Git
3. EGit Installation
4. Setting up EGit
5. Using EGit for a local Git repository
5.1. Overview
5.2. Creating an Eclipse project
5.3. Creating a local Git repository
5.4. Create .gitignore file
5.5. Initial commit
5.6. Making changes and commiting them
5.7. Commmiting files directly
5.8. Show changes
6. Commit messages
6.1. Importance of Git commit messages
6.2. Guidelines for useful commit messages
6.3. Example
7. Repository view
8. Clone existing project
9. Using EGit
9.1. Basic operations
9.2. Merge
9.3. Solving Merge Conflicts
9.4. Git amend
9.5. View the resource history
10. Branching
10.1. What are branches?
10.2. Switch Branches
11. Create Patches
12. Blame annotations
13. Stash support for uncommited changes
13.1. Stash to save uncommitted changes
13.2. Stash via the Git repository view
14. Git repository for multiple projects
14.1. Create a new repository
14.2. Add a project to an existing Git repository
15. Tutorial: Create Git repository for multiple projects
16. Using EGit with Github
vogella.com Tutorials Training Services Publications Connect
BACK TO TOP
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
1 of 27 1/21/2013 11:28 AM
16.3. Push project to Github
16.4. Clone repository from Github
17. Mylyn integration with Github
18. Hacking EGit - Getting the source code
19. Thank you
20. Questions and Discussion
21. Links and Literature
21.1. EGit and Git Resources
21.2. vogella Resources
1. What is EGit
EGit is an Eclipse plug-in (software component) which allows you to use the distributed version control
system Git directly within the Eclipse IDE. .
EGit is based on the JGit library. JGit is a library which implements the Git functionality in Java.
2. Command line Git
This tutorial describes the usage of EGit. If you want to learn about the usage of the Git command line
you can use the Git Tutorial as a reference.
This tutorial also explains the basic Git terminology, e.g. what is a commit, branch, etc.
3. EGit Installation
EGit can be installed into every Eclipse IDE installation. Most Eclipse 4.2 packages from Eclipse.org
contain EGit in there default configuration. In this case no additional installation is required.
If EGit is missing in your Eclipse installation, you can install it via the Eclipse Update Manager via: Help
→ Install new Software. EGit can be installed from the following URL.
http://download.eclipse.org/egit/updates
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
2 of 27 1/21/2013 11:28 AM
4. Setting up EGit
EGit allow you to configure your default user and email address for each commit. To setup your user
and email address select Window → Preferences → Team → Git → Configuration
EGit will automatically read your default .gitconfig in which your global Git settings are stored.
You can add entries via pressing the Add Entries button. To add your user, use the user.name as key
and your real name as value. Repeat the procedure via your email address.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
3 of 27 1/21/2013 11:28 AM
You can add more values in this dialog. These values are also valid for the Git command line in case
you are also using the command line.
5. Using EGit for a local Git repository
5.1. Overview
The following section explains how to create a local Git repository for one Eclipse project with EGit.
This allows you to keep locally track of change you do to your repository and allows you to revert to
another state at a later point in time.
5.2. Creating an Eclipse project
Create a new Java project called de.vogella.git.first in Eclipse. Create the de.vogella.git.first
package and the following class.
package de.vogella.git.first;
public class GitTest { public static void main(String[] args) { System.out.println("Git is fun");
}
}
5.3. Creating a local Git repository
To put your new project under version control with Git, right click on your project, select Team → Share
Project → Git.BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
4 of 27 1/21/2013 11:28 AM
On the next dialog press the Create button.
EGit will propose an directory outside your workspace. It is recommended to place your Git repositories
outside the Eclipse workspace to avoid that you add unwanted data created by the Eclipse IDE. Enter
your project name as Name for your local Git repository. Select the Finish button.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
5 of 27 1/21/2013 11:28 AM
After pressing Finish the The wizard shows you the settings for your local Git repository. Select the
Finish button to put your repository under Git version control.
You have created a local Git repository. The Git repository is in this case directly stored in the specified
folder in a .git folder. The following screenshot shows the directory structure .
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
6 of 27 1/21/2013 11:28 AM
5.4. Create .gitignore file
Git can be configured to ignore certain files and directories. This is configured via the .gitignore file.
Create a .gitignore file in your project with the following content.
bin
.metadata
All files and directories which apply to the pattern described in this file will be ignored by Git. In this
example all files in the bin and the .metadata directory will be ignored.
You can also use EGit to add files and folder to a local .gitignore via right-mouse click on the file or
folder and by selecting Team → Ignore but the Git convension is to have one .gitignore in the root
directly which describes the files which should get ignored.
5.5. Initial commit
EGit gives you several option to stage and commit your files. The Git Staging View is an convinient
way for staging and commiting changes.
Open the Git Staging View via the menu Window → Show View → Other → Git → Git Staging.
In this View select all files which have changed and drag them into the Staged Changes area.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
7 of 27 1/21/2013 11:28 AM
Write a descriptive commmit message and press the Commit button which is hightlighted in the
following screenshot.
Now the first version of your Java project is under version control. If you don't experience any hardware
error you data is now savely stored in your Git repository and you can always restore your Eclipse
project to this initial point.
5.6. Making changes and commiting them
Change the System.out.println message in your GitTest class.
package de.vogella.git.first;
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
8 of 27 1/21/2013 11:28 AM
public static void main(String[] args) { System.out.println("Git is cool");
}
}
Also create a new file called readme.txt
We want to commit the changes of GitTest class but not add and commit the readme.txt file to the
Git repository.
Using the Git Staging View drag only the GitTest class into the Staged Changes area, write a good
commit message and press the commit button.
This change is now also stored in your local Git repository.
5.7. Commmiting files directly
Alternatively to using the Git Staging View you can committed changes of individual files, by selecting
the file, right-mouse clicking on it and selecting Team → Commmit
5.8. Show changes
Open the Git repository view via the following menu entries: Window → Show View → Other → Git →
Git Staging.
Select your project, right click on it and select Show in → History to see the timeline of changes.
If you select a commit you see the commit message and the involved files.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
9 of 27 1/21/2013 11:28 AM
Via right mouse click on an individual file you can compare this file with its ancestor (the commit before
that) or with the current version in the workspace.
6. Commit messages
6.1. Importance of Git commit messages
The commit message describes the changes done by a commit and is used as the first point of
checking the history of a Git repository.
A commit message should therefore be descriptive and informative without repeating the code
changes.
6.2. Guidelines for useful commit messages
A commit message should have a header and a body. The header should be less than 50 characters
and the body should wrap its text at 72 so that the commit messages is displayed well on the
command line. The body should be separated by the header with an empty line.
The body should contain the reason why the change was made.
The commit message should be in present tense, e.g. "Add better error handling" instead of "Added
better error handling".
6.3. Example
The following can serve as an example for a commit message.
Short summary (less than 50 characters)
Detailed explanation, if required, line break at around 72 charactersmore stuff to describe...
7. Repository view
EGit has a Git repository view which allow you to browse your repositories, checkout projects and
manage your branches.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
10 of 27 1/21/2013 11:28 AM
8. Clone existing project
EGit allows to clone an existing Git repository.
Select File → Import → Git → Project from Git.
Select URI in the next dialog.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
11 of 27 1/21/2013 11:28 AM
Press clone and enter the URL to your Git repository. Git supports several protocols, e.g. git:// and
https://. You only have to paste the URL to the first line of the dialog, the rest will be filled out
automatically.
Please note that some proxy servers block the git:// protocol. If you face issues, please try to use the
https:// protocol.
For example the following URI can be used to clone the example projects of the Eclipse 4 application
development book: [email protected]:vogella/eclipse4book.git
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
12 of 27 1/21/2013 11:28 AM
After pressing next the system will allow you to import the existing branches. You should select at least
master as this is typically the main development branch.
The next dialog allows you to specify where the project should be copied to and which branch should
be initially selected.BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
13 of 27 1/21/2013 11:28 AM
After the Git repository is cloned, EGit opens an additional import dialog which allows to import the
Eclipse projects from the Git repository.
Once this dialog is completed, you have checked out (cloned) the projects into a local Git repository
and you can use Git operation on these projects.BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
14 of 27 1/21/2013 11:28 AM
9. Using EGit
9.1. Basic operations
Once you have placed a project under version control you can start using team operations on your
project. The team operations are available via right mouse click on your project. You can:
Select Team → Add, on the project node to add all files to version control.
Select "Team" -> "Commit", to commit your changes to the local Git repository.
Select "Team" -> "Push" to push your change to a remote Git repository (see the GitHub chapter).
"Team" -> "Tag" allows you to create and manage tags.
9.2. Merge
EGit supports merging of branches to add the changes of one branch into another if this branch has
not been changed. Select your project and Team → Merge to start the merge dialog.
9.3. Solving Merge Conflicts
If you pull in changes or merge a branch and you have conflicting changes, EGit will highlight the
affected files. EGit also supports the resolution of these merge conflicts.
Right click on a file with merge conflicts and select Team → Merge Tool.
This opens a dialog, asking you which merge mode you would like to use. The easiest way to see the
conflicting changes is to use the Use HEAD (the last local version) of conflicting files as merge mode.
This way you see the original changes on the left side and the conflicting changes on the right side.
You can manually edit the text on the left side or use the Copy current change from right to left button
to copy the conflicting changes from right to left.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
15 of 27 1/21/2013 11:28 AM
Once you have manually merged the changes, select Team → Add from the context menu of the
resource to mark the conflicts as resolved and commit the merge resolution via Team → Commit.
9.4. Git amend
Git amend allows to adjust the last commit. For example you can change the commit message. The Git
Staging view allows to perform the Git amend command via the the highlighted button in the following
screenshot.
9.5. View the resource history
Select a resource and select Show in (Alt+Shift+W) -> History to see the commit history of this
resource.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
16 of 27 1/21/2013 11:28 AM
ų
10. Branching
10.1. What are branches?
Git allows you to create branches, i.e. independent copies of the source code which can be changed
independently from each other. The default branch is called master.
Git allows you to create branches very fast and cheaply in terms of resource consumption. Developers
are encouraged to use branches frequently.
10.2. Switch Branches
Right-click your project and select Team → Branch to create new branches or to switch between
existing branches.
11. Create Patches
A patch is a text file which contains instructions how to update a set of files to a different state.
If you use Git you can create a patch for the changes you did and this patch can be applied on another
Git repository.
To create a patch for a set of changes with EGit, select the elements which should be include in the
patch in the package explorer, right click on it and select Team → Create Patch
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
17 of 27 1/21/2013 11:28 AM
This file can be used to get applied to another Git repository, via Team → Apply Patch
12. Blame annotationsBACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
18 of 27 1/21/2013 11:28 AM
this, right click on your file and select Team → Show Annotations.
Afterwards you can place the mouse on the left side of the editor and a popup will show the commit
information.
13. Stash support for uncommited changes
13.1. Stash to save uncommitted changes
Git provides the stash command which allows to save the current uncommmitted changes and
checkout the last committed revision.
This allows you to pull in the latest changes or to develop an urgent fix. Afterwards you can restore the
stashed changes, which will reapply the changes to the current version of the source code.
In general using the stash command should be the exception in using Git. Typically you would create
new branches for new features and switch between branches.
13.2. Stash via the Git repository view
Stashing is available in the Git repository View.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
19 of 27 1/21/2013 11:28 AM
14. Git repository for multiple projects
14.1. Create a new repository
Eclipse allows to work with projects which are not included in the workspace.
To put several Eclipse projects into the same Git repository you can create a folder inside or outside
your workspace and create the projects inside this folder. You can create a Git repository for this folder
and all projects in this folder will be handled by the same repository. The best practice is to put the Git
repository outsite of the Eclipse workspace.
You can import these projects into your workspace via File → Import → Git → Projects from Git
14.2. Add a project to an existing Git repository
To add a new Eclipse project to an existing Git repository, select the project, right click on it and select
Team → Share → Git and select the existing Git repository.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
20 of 27 1/21/2013 11:28 AM
EGit moves the projects to the repository and imports the project automatically into your workspace.
15. Tutorial: Create Git repository for multiple
projects
Create two Java projects called de.vogella.egit.multi.java1 and de.vogella.egit.multi.java2. Do not use
the default location (which would be the workspace) but use a subfolder called gitmulti.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
21 of 27 1/21/2013 11:28 AM
Create at least on Java class in each project. Git is not able to save empty folders.
Afterwards select both projects, right click on them and select Team → Share → Git.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
22 of 27 1/21/2013 11:28 AM
You create a new Git repository which contains both projects.
16. Using EGit with Github
16.1. Github
Github is a popular hosting provider for Git projects and if you repository is public to everyone Github
hosting is free. To use GitHub create an account on the Github Website. During the sign-up you will
be asked to provide a "passphase". This "passphase" is later needed to push to Github from your local
repository.
16.2. Create Repository in Github
Create a new repository on Github, e.g. "de.vogella.git.github".
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
23 of 27 1/21/2013 11:28 AM
ų
After creation of your new repository Github tells you what to do if you would inport via the command
line. As we are going to use EGit we can ignore this information.
16.3. Push project to Github
Create a new project "de.vogella.git.github" and put it under version control. Right-mouse click on your
project and select "Team" -> "Push". A dialog pops up. Maintain the following data. Adjust the
hightlighted line so that you are using your user and your project name.
git+ssh://[email protected]/vogella/de.vogella.git.github
Maintain your passphase which you maintained during the Github setup.
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
24 of 27 1/21/2013 11:28 AM
Select your branch (you should currently only have master if you followed my tutorial), press "Add all
branches spec" and select next.
Press finish.
If you now select your github Dashboard and then your project you should see the commited files.BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
25 of 27 1/21/2013 11:28 AM
16.4. Clone repository from Github
Use the same URI you use to push to Github to clone the project into another workspace.
17. Mylyn integration with Github
Eclipse Mylyn is a productively tool for programmers. There is a GitHub connector for Mylyn available,
please see http://wiki.eclipse.org/EGit/GitHub/UserGuide for details. .
18. Hacking EGit - Getting the source code
EGit is self-hosted on git://egit.eclipse.org. You can clone the EGit code from the repository using
EGit using the following URL git://egit.eclipse.org/jgit.git and git://egit.eclipse.org/egit.git.
You also need some libraries from Orbit. See Libraries from Orbit for getting these libraries.
19. Thank you
Please help me to support this article:
20. Questions and Discussion
Before posting questions, please see the vogella FAQ. If you have questions or find an error in this
article please use the www.vogella.com Google Group. I have created a short list how to create
good questions which might also help you.
21. Links and Literature
21.1. EGit and Git ResourcesBACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
26 of 27 1/21/2013 11:28 AM
http://wiki.eclipse.org/EGit/User_Guide EGit User Guide
http://wiki.eclipse.org/EGit/Contributor_Guide EGit contributor guide
Git Tutorial
21.2. vogella Resources
vogella Training Android and Eclipse Training from the vogella team
Android Tutorial Introduction to Android Programming
GWT Tutorial Program in Java and compile to JavaScript and HTML
Eclipse RCP Tutorial Create native applications in Java
JUnit Tutorial Test your application
Git Tutorial Put everything you have under distributed version control system
BACK TO TOP
vogella.com Tutorials Training Services Publications Connect
Git with Eclipse (EGit) - Tutorial http://www.vogella.com/articles/EGit/article.html
27 of 27 1/21/2013 11:28 AM