Team Eclipse and Git with EGit

In previous Wazi articles we've looked at using Eclipse with the Subversion source code management tool – but increasingly, Subversion is being left behind as developers move to Git. If you and your projects are following suit, the good news is that Eclipse plays very nicely with Git, too, using the EGit plugin.

To install EGit, fire up Eclipse, go to Help -> Install New Software, then click the Available Software Sites link. Search for "egit," and tick the box to add the EGit download site. On the Available Software screen, type egit in the box, then click Eclipse Git Team Provider and click Next to install it.

Once installed, go to Window -> Open Perspective -> Other -> Git Repository Exploring to look at the Git repositories available. At this point you can either clone an existing repository, or create a new one.

If you have a new project and want to create a repository from it, you could start by creating a new repository from the Git Repository view, but importing your existing project to it is complicated. It's easier to go back to the Java view, right-click on your project in the Package Explorer, and choose Team -> Share -> Git. You can either specify a repository or tell the wizard to create a new repository. EGit recommends against using a parent folder in your current workspace; instead it suggests using an external directory. Note that if your new repository is created in an external directory, EGit will move your working directory from your workspace into that new directory as well.

Committing and deleting files

When your new repository is first set up, it has not yet been committed. Before you do so, if you're working on a Java project, it's a good idea to create a .gitignore file in the root of your project with two lines:


This tells Git to ignore (not keep under version control) your bin/ directory (which should contain only generated files, and which changes every time Eclipse recompiles your project in the background) and .metadata, which is an Eclipse file.

Now go to the Git Staging View (Window -> Show View -> Other -> Git Staging). Drag all of your changes from Unstaged to Staged, add a commit message, then click the Commit button, which is the little red arrow into a yellow silo in the top right of the window. If you then look at the Git Reflog tab in the Git Repository Exploring perspective, you should see your commit recorded.

giteclipse stage

Here you can see a line in the Staged area, waiting to be committed.

Open one of your files, make a change, and you should see it appear in the Git Staging view in the Unstaged Changes window. Drag it into the Staged Changes area, add a commit message, and click Commit. You can also use the Team menu; right-click on the file, choose Team -> Add to Index, then Commit. The Commit menu won't let you commit without specifying a commit message, which is a nice way of enforcing good practice. Now, if only it could check for a meaningful commit message....

To delete a file, just right-click and delete it, then Commit the whole repository to commit the change.

Your experience may differ, but I had some problems with the Git Staging view the first time I used it. If you don't see your changes appearing in Git Staging, click the Link with Editor and Selection button in the Git Staging view, then go to the Git Repositories perspective and click on the repository. (This link suggests that you may need to right-click and copy the path, but I don't think that's necessary.) Similarly, to use the History view, you need to open the Git Repositories perspective and click the relevant repository to load its history.

Cloning an existing repository

To clone an existing repository, go to the Git Repository view, right-click, and click Clone Repository. You'll be asked to specify the location of the repository, which branches to clone, and a couple of other questions. Next, to create a project from that repository, right-click the repository and choose Import Projects. For Java code, you should be able to use the New Project wizard (or import existing projects, if your Git repository is set up with Eclipse project information). For other languages, you may struggle; it's not always clear how exactly the new project creation options in Eclipse work, and they can be sparsely documented. In particular, I struggled to get a Ruby project set up from a Git repository. Covering the details is beyond the scope of this tutorial, but if you have problems, Google is probably your friend.

You can also add a remote branch to track. Highlight "Remotes" in the Git Repository view, right-click, and select Create. In theory, you can choose to configure this branch on setup as either Push or Fetch. In practice, I found that nothing happened if I chose Fetch. Instead, configure Push first (if you don't have Push credentials, just choose Save rather than Save and Push), then configure Fetch afterward. In addition, to set the URI for the remote repository, you need to click Change, not just paste the URI into the config box. Once the remote is saved, right-click the Fetch line (with the green arrow), and click Add next to the ref mappings box to add a reference to fetch. Once you start typing into the Source box, you'll be offered a choice of remote branches to select from (e.g. dev). You can also specify where to fetch to locally, but the default should be OK. Once the remote is set up, you can right-click on your local branch, choose Merge (or Rebase), and choose the remote branch. Once you've added a Remote, you should also see it appear farther up, under Branches-Remote Tracking in the repository viewing tree.

If you do have Push credentials and wish to push your changes to the remote branch, just go to the Git Repository view, right-click on that branch, and choose Push. Farther up in the repository you'll see that the Remote Tracking section of Branches is updated with the latest change. (Unfortunately, it seems impossible to delete the Push configuration, which is a bit irritating if you don't have Push credentials, but not a show-stopper.)

Branching and viewing history

Git makes branching easy, and EGit follows suit. To create a new branch, right-click the project in Java view, go to Team -> Switch To -> New Branch, and create and check out your new branch. You'll see that in the Package Explorer view, the new branch name shows at the top of the project in brackets. Make your edits, saving them and commiting them as you go. Once you're happy with your branch, switch back to the master branch (Team -> Switch To -> master) and merge (Team -> Merge) with your branch. It couldn't be much more straightforward!

Well, there is one improvement you can make – you can eliminate the need for those awkward right-clicks. Right-click on the command bar and choose "Customise Perspective." Click on Command Groups Availability, and click the Git groups, then go back to Tool Bar Visibility tab, and click Git there too. Click OK and you'll get a selection of Git buttons in the toolbar. Click Add to move a change from unstaged into staged; click Commit to commit a change (you'll be prompted for a commit message); and try the Merge, Pull, and Rebase buttons. You can also double-click on a branch in the Git Repository View to check that branch out.

One of the really useful aspects of using an IDE or graphical interface with your version control system, especially one with lots of branching, is that you can see a graphical version of your history. To see this in EGit, including a line-drawing representation of the various branches and merges, go to the Git Repository view and click the History tab, then click the repository you want to view.


The history of an open source project I'm working on

The value of a version control system is strongly linked to how often you commit, so anything that makes it easier to hit that button is likely to improve your coding practices. Even though it has a couple of wrinkles, EGit does give you that touch-of-a-button Git integration in Eclipse, which makes it well worth setting up.

Join the Network World communities on Facebook and LinkedIn to comment on topics that are top of mind.
Must read: 10 new UI features coming to Windows 10