Tips and Tricks: Using Eclipse with GitHub

If you’re using Eclipse and sharing your code (and issues) on GitHub, you really should take a look at the variety of Eclipse Plugins for working with Git. The most obvious plugin is EGit, the Eclipse Git Plugin. EGit (and the underlying JGit) plugins have improved a great deal over the past 2-3 years. I find myself turning to the command-line less and less, which really keeps me in the flow.

EGit also integrates very well with GitHub, especially when you have the Mylyn GitHub Connector installed. You can easily search for and clone a repository right from your Eclipse IDE.

This was done by Kevin Sawicki, Christian Trutz and Chris Aniszczyk (with some help from a few others) – All very talented developers! The tool also brings your GitHub issues right into your Eclipse IDE, making issue management a breeze.

You can install EGit, Mylyn and the Mylyn connector from the Eclipse Marketplace, or download this Yoxos profile and start it with the Yoxos Launcher.

1. Setup a Task Repository

In order to track GitHub issues within Eclipse you need to setup one or more issue (task) repositories. Mylyn provides a Task Repository view which you can use to add new task repositories. The pattern for a GitHub issue repository is simply the URL to the GitHub repository <https://github.com//>.

2. Setup Queries

Once your task repository is configured you can create Queries to determine which tasks to display. You can structure your queries to show tasks pertaining to specific milestones, labels, or who is assigned to the task. In this example, I’ve created a query to show all the bugs that are marked Milestone 1.0.0.

Tasks can now be viewed in the Task List view. You can quickly search for tasks and filter (and sort them) by different criteria. Progress can also be tracked as work items are completed.

Select a task to see the milestone, description and even comment directly on the issue. You can even modify attributes such as label, milestone and bug status (open or closed).

3. Focusing on the Task-At-Hand

While bringing your tasks into the IDE is a good first step, to keep you focused on your work, Mylyn offers a ’task focused’ way of working. There is lots of information about the Task Focused UI and benefits of this workflow. The key is to activate a particular task before working. One major advantage to this method of working is that Mylyn will automatically generate commit comments for you based on the task.

The commit comment template can be configured under Mylyn -> Team. If you use #${task.key} in your template (or simply #task_number in your commit message), GitHub will automatically update the issue with a link to the commit (once you’ve pushed your changes back to GitHub of course).

For example, I used #1 in my commit message which results in the issue having a link to the particular commit (7de0447…). This is a tremendous help for traceability between issues and source code.

In addition to #<issue_number>, several other annotations can be used in a Git commit. For example, if you say fixes #<issue_number> in a commit message, the issue will be automatically closed when the commit is pushed back to GitHub. Other synonyms include:

• fixes #xxx
• fixed #xxx
• fix #xxx
• closes #xxx
• close #xxx
• closed #xxx

For more information on working with GitHub issues, check out https://github.com/blog/831-issues-2-0-the-next-generation.

4. Managing Pull Requests

GitHub Pull requests provide a way to inform others of changes you’ve made to a GitHub repository. In many open source projects a master repository emerges (likely the one the binaries are eventually built from). Contributors can fork this repository and adapt it as they see fit. Once the fork has been modified, it’s often desirable to merge these changes back into the master repository. Pull requests provide a way for a contributor to indicate to a project maintainers that they have a set of changes ready for review.

Pull requests can also be used between different branches in a single repository.

To track pull requests, simply add another Task Repository (GitHub Pull Requests).

Whenever someone initiates a pull request it will show up in your task list. The Pull request can be viewed, merged, or even debated right from the Eclipse IDE. Once the pull request has been integrated (or rejected), the task can be closed. Notifications will be sent to all those watching the request.

5. Working with Gists

Gists are simple ways of sharing small snippets of code with others. For example, say you have a snippet that shows a problem with a simple SWT program and you want to share it with others (to get feedback), you simply right-click the file in Eclipse and choose GitHub -> Create Gist. Gists are managed through task repositories as well, and you can configure a Query to show all your Gists.

You can view and comment on a Gist right from Eclipse. You can even clone a Gist to a local Git repository, update the file(s) and push the changes back to GitHub. Changes will then be reflected in your Gist editor.

6. Sharing your Configurations

GitHub makes it very easy to share repositories both publicly and privately, however using it within Eclipse still requires a number of setup steps (install the plugins, configure & clone the repositories, setup the Mylyn queries, etc…). Yoxos is a free service which automates this process for you, allowing you to get up and running faster. You simply define a profile that describes the tools you want to install, and the workspace settings (such as Git repository locations, Mylyn queries, checkstyle rules, etc…). Members of your team can launch this profile, completely automating the installation process (including dependency calculation).

For information on how you can use Yoxos with Git, please see my post on Sharing Git Configurations with your Team.

7. Summary

The Eclipse Community has moved away from CVS and in late 2012 the Eclipse Foundation will turn off CVS access. The Eclipse platform has already migrated to Git (along with over 60% of the Eclipse projects). As more and more Eclipse committers use the Git tooling, these plugins will continue to improve. GitHub has also been a big supporter of Eclipse, first providing Git mirrors of all the Eclipse projects and now helping with first class Git tooling for Eclipse. Check out https://eclipse.github.com/ for more information about Git and Eclipse.

For more Eclipse Tips and Tricks (and the annual Top 10 List), why not follow me on Twitter:

Follow @irbull