This tutorial describes the usage of the Eclipse IDE to perform Git operations.

1. Git support for Eclipse

Using the Eclipse IDE, you can perform Git commands such as staging, committing, merging, rebasing, pulling, and pushing.

2. Installation of Git support into Eclipse

Most Eclipse IDE distributions from Eclipse.org already contain support for Git. In this case, no additional installation is required.

If the Git tooling is not available, you can install it via the Eclipse installation manager. Select the Help Install new Software… menu entry. Enter one of the following update site URLs:

# Use this update site to get the latest release
https://download.eclipse.org/egit/updates

# use this update site to get the nightly build
https://download.eclipse.org/egit/updates-nightly/

The dialog to install the Git Integration for Eclipse is depicted in the following screenshot.

3. Exercise: Configure Git in the Eclipse IDE

Eclipse and the Git command line share their configuration

The Eclipse IDE reads and writes the same configuration files as the Git command line. If you have already configured Git on the command line, you can skip this exercise.

3.1. Configure user and email

Open Window Preferences Version Control (Team) Git Configuration. The User Settings tab shows the content of your global .gitconfig file.

If the user.name key is missing, press Add Entry…, enter user.name as Key and your full name as Value, and press Add.

Repeat this for your email address with the user.email key.

3.2. Configure Git to rebase during pull

Add the pull.rebase key with the value true in the same way. With this setting, git pull rebases your local commits onto the remote branch instead of creating a merge commit.

3.3. Validate the setup

Your configuration should look similar to the following screenshot.

Git configuration with the user and pull.rebase entries

Press Apply and Close.

3.4. Configure a proxy

If you use a proxy server, configure it via Window Preferences General Network Connections.

4. Exercise: Create and use a Git repository with the Eclipse IDE

In this exercise, you create a local Git repository with the Eclipse IDE and commit changes to it.

Keep Git repositories outside the workspace

Place your Git repositories outside the Eclipse workspace. This separates your repository from the metadata Eclipse creates. By default, Eclipse Git uses the git folder in your home directory.

4.1. Create a Git repository

Press Ctrl+3 (Cmd+3 on macOS) and type Create a new Git repository. Enter ~/git/first-eclipse-repo as the Repository directory.

The Default branch name comes from the init.defaultBranch setting and defaults to master. Press Create. Eclipse creates the repository and adds it to the Git Repositories view.

Create a .gitignore file in the top-level folder of the repository, next to the .git folder. Eclipse does not allow you to create files in this folder, so use the command line or your file explorer.

bin
*.class

Windows File Explorer does not allow file names without an extension. Create the file in Notepad via File Save As and select All files as type.

4.3. Create a Java project

Press Ctrl+3 and type Create a Java project. Enter com.vogella.git.first as the project name, keep the defaults, and press Finish.

4.4. Optional: Create a Java class

Skip this section if you are not familiar with Java.

Press Ctrl+3 and type Create a Java class. Enter com.vogella.git.first as Package and GitTest as Name, and press Finish.

Change the class to the following.

package com.vogella.git.first;

public class GitTest {
    public static void main(String[] args) {
        System.out.println("Git is fun");
    }
}

4.5. Add the project to the Git repository

Right-click the project and select Team Share Project…. Select your repository from the drop-down list and press Finish.

Eclipse moves the project into the folder of the Git repository.

4.6. Open the Git Repositories view

Press Ctrl+3 and type Git Repositories. This view lists the repositories known to Eclipse and allows you to create, clone and add repositories.

4.7. Create the initial commit

Press Ctrl+3 and type Git Staging. Press ++ (Add all files including not selected ones to the index) to stage all files. Enter a commit message and press Commit.

Git Staging view before the initial commit

4.8. Commit only selected changes

Create a file named Readme.adoc in your project via New File. Do not commit it yet.

If you created the GitTest class, change its message to Git is cool. If you skipped the Java class, skip the rest of this section and commit Readme.adoc.

Drag only GitTest.java from Unstaged Changes to Staged Changes. Enter a commit message and press Commit.

Git Staging view with only GitTest.java staged

Readme.adoc stays unstaged. Now stage and commit Readme.adoc as well.

4.9. Use the History view

Press Ctrl+3, type History, and select the entry from the Views category.

In a fresh workspace, the toolbar already fits this training. If your view differs, set the highlighted buttons as follows:

Link with Editor and Selection is enabled.
The file scope drop-down (funnel) shows all changes in the repository.
The Change which commits to show drop-down shows all branches and tags.

Select a commit to see the files it changed in the lower right part of the view.

4.10. Open an older version of a file

Select the first commit in the History view. Right-click GitTest.java in the list of changed files and select Open This Version. If you skipped the Java class, use the .project file instead.

Context menu on a file in the History view

4.11. Untrack a committed file

Create a file named test.unwanted in your project, then stage and commit it.

Add *.unwanted to your .gitignore file and change test.unwanted. Git still shows the change, because .gitignore applies only to untracked files.

Right-click the file and select Team Advanced Untrack. Stage and commit the change.

4.12. Add more projects to the repository

A Git repository can contain multiple projects. Create the Java projects com.vogella.egit.multi.java1 and com.vogella.egit.multi.java2 with at least one class each.

Select both projects, right-click them, and select Team Share Project…. Select your repository and press Finish.

Check in your file explorer that Eclipse moved the projects into the repository folder. Commit all files of the new projects.

5. Exercise: Clone an existing repository

In this exercise, you will clone a Git repository and import the existing projects from this repository into your workspace.

For this, select File Import…|Git|Projects from Git.

Select Clone URI in the next dialog.

Enter the URL to your Git repository which you want to clone. You can use the following example URI.

git://github.com/vogellacompany/eclipse_rcp_example.git

The above link uses the git protocol, alternatively you can use the http protocol: https://github.com/vogellacompany/eclipse_rcp_example.git

Git supports several protocols, e.g., git://, ssh:// and https://. You can paste the clone URL to the first line of the dialog, the rest of the dialog is filled based on this data.

Some proxy servers block the git:// and ssh:// The above link uses the git protocol, alternatively you can use the https protocol: https://github.com/vogellacompany/eclipse_rcp_example.git

After pressing the Next button the system will allow you to import the existing branches. Select at least the master branch.

The next dialog allows you to specify where the repository should be copied to and which local branch should be created initially.

Define target directory for Git repository

After the Git repository is cloned, you can import existing projects.

Once this dialog is completed, you have clone the remote repository into a local Git repository. You can use Git operation on these projects.

The project may not compile, as you may miss pre-requisites. For this exercises, this can be ignored, the purpose of it was to learn how to clone a repository.

6. Exercise: Import projects from an existing repository

If you have already an existing Git repository you can add it to the Git Repostory view. Afterwards, you can import the projects into your workspace via the File Import Git Project from Git menu entry.

Select Local if you want to important from a local repository or Clone URL if you first want to clone the repository.

The following screenshot shows multiple local repositories. To import the project contained in one of them, select one entries and press the Next button. To add a new local repository to this dialog (and the Git repositories view) use the Add… button.

The wizard allows you to specify the projects to import. After the import the Eclipse IDE is aware that these projects are part of a Git repository.

7. Exercise: Use interactive rebase in Eclipse

Git allows to adjust the local commit history via the interactive rebase functionality. Eclipse provides support for simplified versions of this as well as support for full interactive rebase operations. This includes changing the order of commits or combining, removing and adjusting commits.

7.1. Simple interactive rebase operations available via the History view

To reword a commit, right-click on it in the History view and select Modify Reword to change the commit message.

You can squash several commits by selecting them in the History view. Select afterwards the Modify Squash menu entry from the context menu.

The above options are simplified ways to do an interactive rebase.

7.2. Performing a full interactive rebase via Eclipse

To start the full interactive rebase open the History view and click Rebase Interactive on the context menu. Select the last commit preceding the oldest commit you want to rewrite. Often this is the one origin/master points to.

This opens the Git Interactive Rebase view. The Git Interactive Rebase view allow you perform the full interactive rebase functionality.

It shows the rebase plan populated with the commits to be modified. They are sorted in topological order of the sequence in which they will be processed. This order is the reverse order which you see via the git log command or in the History view. The initial action for all commits is "Pick".

The following actions are available.

Table 1. Interactive rebase actions
Action	Description
pick	includes the selected commit, moving pick entries enables reordering of commits
skip	removes a commit
edit	amends the commit
squash	combines the changes of the commit with the previous commit and combines their commit messages
fixup	squashes the changes of a commit into the previous commit discarding the squashed commit’s message
reword	similar to pick but allows modifying the commit message

Use this view to finalize the rebase plan. For example, you can reorder commits with the arrow buttons and select the rebase action you want to apply to the commit. The following screenshot demonstrates a possible selection.

When the rebase plan is finalized, click the Start button to start the interactive rebase command. Eclipse Git processes the plan. It stops at all commits with an action which needs user feedback. For example, the reword action that requires entering the new commit message. The dialog for changing the commit message is depicted in the following screenshot.

Here is the result of the rebase operation displayed in the History view.

If something goes wrong during the rebase operation, you can select Abort to stop the rebase operation and roll back to the starting point.

8. Eclipse Git configuration

The Eclipse IDE uses the default Git settings, such as those configured via the command line. You can also configure these settings directly within the Eclipse IDE.

8.1. Git user settings in Eclipse

To use Git you must configure your full name and email address. This information is used to fill the author and committer information of commits you create. These Git configuration settings can be adjusted via the Eclipse preference setting. Select Window Preferences Version Control (Team) Git Configuration to see the current configuration and to change it.

8.2. Default clone location

Eclipse clones a repository into a new sub-folder of a default folder. Configure this folder via Window Preferences Version Control (Team) Git in the Default repository folder field.

You can use Eclipse variables in the path, e.g., ${workspace_loc}/git for a git folder in the workspace.

To add the common Git operations to the toolbar and the main menu, select Window Perspective Customize Perspective…. In the Action Set Availability tab, check Git and Git Navigation Actions.

Git action sets in the Customize Perspective dialog

The Toolbar Visibility and Menu Visibility tabs allow you to hide individual entries.

8.4. Eclipse support for SSH based authentication

EGit reads SSH keys from the .ssh folder in your user home directory. Create a key pair with ssh-keygen -t ed25519 on the command line and add the public key to your Git server, e.g., under Settings SSH and GPG keys on GitHub. The settings are available via Window Preferences General Network Connections SSH2.

9. Details on the Git views

9.1. Using the Git Repositories view

The Git Repositories view allows you to browse, add, create and clone repositories. It also allows you to import projects and to manage branches. Open it via Window Show View Other… Git Git Repositories.

The highlighted toolbar buttons add an existing local repository, clone a repository and create a new repository.

The view shows the repositories with their branches, tags, references, remotes and working tree.

The context menu of an element offers the related Git operations. For example, the context menu of a branch allows you to check out, merge or delete it.

Context menu of a branch in the Git Repositories view

9.2. Using the Git Staging view

The Git Staging view allows you to stage, commit and revert changes. Open it via Window Show View Other… Git Git Staging.

Unstaged Changes lists the changes that are not yet in the staging area. Staged Changes lists the changes that the next commit includes. Drag and drop files between the two lists, or use the buttons in their toolbars. To commit, enter a commit message and press Commit.

Git Staging view with staged and unstaged changes

The view keeps your commit message when you switch repositories or restart Eclipse.

9.3. Git integration into the Package and the Project Explorer

The Package Explorer and the Project Explorer decorate files with their Git state.

Git label decorations in the Package Explorer

Table 2. Git label decorations
State	Description
tracked	The file is committed and has not changed.
untracked	The file is neither staged nor committed.
ignored	Git ignores the file.
dirty	The file has changed since the last commit.
staged	The next commit includes the changes of the file.
partially-staged	The file has staged changes and additional unstaged changes.
added	The file is staged but was not under version control before.
removed	The file is staged for removal from the repository.
conflict	The file has a merge conflict.

Double-click a partially staged file in the Git Staging view to change its staged parts in the compare editor.

The project label shows the repository and the checked out branch. It also shows the number of commits by which the local branch is ahead of (↑) or behind (↓) its remote tracking branch.

Git decorations of projects in the Package Explorer

9.4. Using the History view

9.4.1. Purpose of the History view

The History view shows the history of your repository and which commits the branches and tags point to. For the selected commit, it shows the author, the date, the commit message and the changed files.

Open it via Window Show View Other… Team History. To see the history of a resource, right-click it and select Team Show in History, or press Alt+Shift+W and select History.

Right-click a file in the file list to compare it with the previous version or with the version in the workspace. With Compare Mode turned on, which is the default, a double-click compares the file with its previous version.

The toolbar of the History view configures which commits it shows.

The most important buttons are:

Link with Editor and Selection updates the view when you select another resource or editor.
Show Find Toolbar opens a field to search commits by message, author, committer or id.
Change the File Scope for the History shows all changes of the repository, of the project, of the folder or of the selected resource only.
Compare Mode makes a double-click on a file compare it with its previous version.
Change which commits to show selects which branches the view shows. By default, it shows all branches and tags.

If the history does not show what you expect, select all branches and the repository as the file scope.

9.4.3. Using Git Search

Search Search… Git Search searches commits by message, author, committer or id. It is faster than the History view for large repositories, as it does not need to display the history.

9.5. Commit Viewer

The Commit Viewer shows the details of a commit. Open it from the context menu of a commit in the History view via Open in Commit Viewer, or via Navigate Open Git Commit. The Open Git Commit dialog accepts a branch, a tag or a commit id.

The toolbar of the Commit Viewer allows you to create a tag or a branch from the commit, to check it out, to cherry-pick or revert it, and to show it in the History view.

10. Performing Git operations in Eclipse

10.1. Pull, push and fetch

Right-click a repository in the Git Repositories view to push, fetch or pull.

Push fetch and pull in the context menu of a repository

10.2. Basic team operations

Right-click a file or a project and select the Team menu for the Git operations. The Team menu is also available in the context menu of an editor.

The most important operations are:

Team Commit… opens the Git Staging view to create a commit.
Team Create Patch… creates a patch.
Team Apply Patch… applies a patch.
Team Ignore adds the file to the .gitignore file.
Team Show in History shows the history of the selected resources.

10.3. Team operations available on the project

The Team menu of a project offers additional operations.

Team Pull pulls changes from the remote repository.
Team Fetch from origin fetches the state of the remote repository.
Team Push to origin pushes your commits to the remote repository.
Team Switch To checks out an existing branch or creates a new one.
Team Advanced contains the tag operations.

10.4. Amending a commit

Amend replaces the last commit, e.g., to change its message or to add another change. Press the highlighted Amend button in the Git Staging view to load the last commit message, then press Commit.

10.5. Creating and switching branches

Right-click your project and select Team Switch To New Branch… to create a branch. Team Switch To also lists the existing branches to switch to. The History view and the Git Repositories view offer the same operations in the context menu of a commit or a branch.

10.6. Merging a branch

Check out the branch into which you want to merge and select Team Merge… on your project. Select the branch to merge and press Merge.

10.7. Rebasing a branch onto another branch

Select Team Rebase… on your project, or Rebase… in the context menu of a repository in the Git Repositories view. Select the branch onto which you want to rebase the checked out branch and press Rebase.

If a conflict occurs, resolve it and select Team Rebase Continue. Team Rebase Skip skips the conflicting commit and Team Rebase Abort cancels the rebase.

10.8. Solving conflicts

If two changes conflict, you have to solve the conflict manually. The Package Explorer and the Git Staging view mark the conflicting files. The Git Staging view is usually the fastest way to find them.

Right-click a conflicting file and select Merge Tool. The dialog asks which version to show in the merge editor. Use HEAD (the last local version) of conflicting files shows your version on the left and the other version on the right.

Edit the left side, or use the highlighted Copy Current Change from Right to Left button.

The Show Ancestor Pane button shows the common ancestor of both versions.

Once you have resolved the conflict, save the file and stage it in the Git Staging view or via Team Add to Index. Then commit the merge.

10.9. Git reset

Right-click a commit in the History view and select Reset and the reset mode to reset the current branch to that commit.

10.10. Finding "invisible" commits with the Reflog view

A reset, an amend or a rebase can make commits unreachable from any branch or tag. The History view does not show such commits, and Git removes them after some time. The Git Reflog view lists the movements of HEAD and of each branch, so you can find and check out such commits again.

10.11. Selecting individual commits via git cherry-pick

Cherry-pick applies the change of a commit to the checked out branch. Right-click a commit in the History view and select Cherry-Pick…. Combined with a reset, this allows you to drop a bad commit: reset the branch to the commit before it, then cherry-pick the good commits that followed.

10.12. Comparing and replacing files

10.12.1. Comparing files

Compare With compares the selected file, folder or project with the index, the HEAD revision, a previous revision, a branch or tag, or a commit.

10.12.2. Replacing files

Replace With replaces the selection with the version of the index, of HEAD, of a previous revision, of a branch or tag, or of a commit.

11. See Git information line by line (aka git blame)

To see which commit and author changed a line, right-click your file and select Team Show Revision Information. The ruler of most editors offers the same action. Hover over the annotations to see the commit and the change it applied.

To ignore whitespace changes in the annotations, select Ignore whitespace changes in Preferences Version Control (Team) Git.

11.1. Stash via the Git Repositories view

Right-click your repository in the Git Repositories view and select Stashes Stash Changes…. The same menu lists the existing stashes, which you can apply or delete.

Stash changes in the Git Repositories view

11.2. Creating patches

Select the resources for the patch in the Package Explorer, right-click and select Team Create Patch…. The wizard writes the patch to the clipboard, a file or a workspace file.

Team Apply Patch… applies a patch. This works without Git, i.e., you do not need a Git repository to apply a patch.

12. Using Eclipse Git with GitHub

12.1. Clone project

Copy the URL from GitHub and select File Import Git Projects from Git in Eclipse.

Eclipse fills out the fields based on the URL in the clipboard. To push to GitHub via HTTPS, enter your GitHub user name and a personal access token as the password, as GitHub no longer accepts account passwords. Alternatively, use an SSH key as described in the configuration chapter.

12.2. Push changes

After you have made changes and committed them to your local repository, you can select Team Push to origin on the project folder to push your changes to GitHub. This requires write access to the GitHub repository.

13. Writing Good Commit Messages

13.1. Importance of Git Commit Messages

A commit adds a new version to the repository. This version is described by a commit message.

The commit message details the changes recorded in a commit. It should help users understand the repository’s history.

A commit message should be descriptive and informative without repeating the code changes.

13.2. Guidelines for Useful Commit Messages

A commit message should consist of a header and a body. The header should be less than 50 characters and the body should wrap at 72 characters. The body is separated from the header by an empty line.

This format ensures the commit message displays well on the command line and in graphical tools.

The body should explain why the change was made. The actual changes can be reviewed with Git.

Use the imperative mood for commit messages, e.g., "Add better error handling" rather than "Added better error handling".

The last paragraph may include metadata as key-value pairs. This data is known as the commit message footer.

This metadata can trigger specific behaviors. For example, the Gerrit code review system uses the Change-Id key followed by a change-id. This change-id identifies the review associated with the message.

The commit message footer can include items such as 'Signed-off-by' or a link to a bug tracking system, e.g., 'Bug: 1234'.

13.3. Example Message

The following example illustrates a well-structured commit message.

Short summary of the commit (less than 50 characters)

Detailed explanation of the changes, if necessary.
Line breaks at around 72 characters for readability.
Additional details or context can be provided here.

Fixes #8009

This example includes a reference to an issue. GitHub and other Git hosting services automatically recognize such references.

13.4. Good and Bad Examples of Git History

The following listing shows the output of the git log --oneline command from a repository with poor commit messages. The first value in each line is the shortened SHA-1, and the second is the commit message. This history is less informative.

21a8456 update
29f4219 update
016c696 update
29bc541 update
740a130 initial commit

The next listing shows the history of another repository with improved commit messages. This history provides a clearer overview of the activities.

7455823 Adds search and filter to the model editor tree
9a84a8a Missing DynamicMenuContribution in child selector
952e014 Fixes spelling error in Toolbar/Add child
71eeea9 Adds option to import model elements from legacy RCP
123672c New Application wizard is missing dependencies
97cdb9a Creates an id for handlers

14. Contributing to EGit - Getting the source code

This support is provided by the EGit project via a set of plug-ins (software component).

Eclipse uses the JGit library to perform the Git commands. JGit is a library that implements the Git functionality in Java.

EGit is hosted on git://git.eclipse.org.

See EGit contributor guide for a description how to work with the EGit and JGit source.

15. Eclipse Git Resources

Eclipse Git User Guide

Contributor guide for the Eclipse Git project

Different update sites for Eclipse Git

15.1. vogella Java example code

If you need more assistance we offer Online Training and Onsite training as well as consulting

See License for license information.

Home Tutorials Training Consulting Books Company Contact us

Get more...

Legal Privacy Policy

Eclipse Git Tutorial

Get more...