Saturday, October 04, 2014

Add Eclipse Project to Local and Remote Git Repository

This is a brief tutorial on using Eclipse to check in projects to local and remote Git repositories.

  1. Install and configure EGit within Eclipse, if not already done.
  2. Create a project in Eclipse.
  3. Add project to local git repository.
  4. Create a project in GitHub (with the same name as our local project).
  5. Check in our project to the remote git repository.
  6. The two phases of commitment.
  7. Helpful Resources.

Prerequisites are as below.

  • You have an account already on GitHub. Free accounts can be used to create only public repositories i.e. everybody will be able to see your code. So if you need a private Git repository on GitHub, you have to pay.

To top of post.

Install and Configure EGit

Here you will install the EGit plugin within Eclipse. This gives Eclipse the ability to interact with Git repositories. If you have Eclipse Kepler (4.3), Eclipse Luna (4.4) or later, then this easily installed through the Eclipse Marketplace.

  1. Open Eclipse, go HelpEclipse Marketplace.
  2. In the search field, type EGit and press ENTER.
  3. The first result will be EGit - Git Team Provider 3.5.0 (latest version as of this writing).
  4. Click the Install button.
  5. Select Eclipse Git Team provider component.
  6. Select Next, accept license agreements, let it install, let Eclipse restart.

Before you can use EGit, you need to configure it.

Set up your identity. In Eclipse, go WindowPreferencesTeamGitConfiguration. Enter your name and email - Git will use this to identify who is making commits.

Set up location for local repositories. In Eclipse, go WindowPreferencesTeamGit and set a location for Default Repository Folder. I have used D:\Documents\Work\Git.

It is a good idea to create your Git repositories in a different directory than your Eclipse Workspace. The Git repository folders will hold lots of files related to Git setup, not just your project files. If you create your Git repository within your Eclipse Workspace, some operations in Eclipse would suffer a performance hit because they will have to scan all of these other files, not just project files.

You will need to create this directory first and it should be empty.

To top of post.

Create a project

In Eclipse, select FileNewProject → select whatever project type you want (I am using a Java Project). Give it a name and press Finish. The contents of the project aren't important - it is just a few bare files to show the next part of the process - adding it to a local repository and then a remote one.

Note that your project has been created in your Eclipse workspace. In my case, this was D:\Documents\Work\JavaTests\TestProject.

To top of post.

Add project to local git repository

In Package Explorer view, right click on the project you just created and select TeamShare Project. In the Share Project dialog, select Git and then click Next.

The next screen is Configure Git Repository.

I am not selecting Use or create repository in parent folder of project for reasons stated above - the repository folder will contain a lot of Git-specific files apart from my project files and I do not want Eclipse having to scan these folders.

The general idea is that you have one project per repository, so we make one repo for this project. Click Create.

Give the new repository the same name as your project and click Finish.

I am now back on the Configure Git Repository dialog.

I can see the following:

  • Repository: D:\Documents\Work\Git\TestProject\.git - all the files related to Git go here.
  • Working Directory: D:\Documents\Work\Git\TestProject - the parent folder for the Git directory and the (new, target) project directory.
  • Current Location: D:\Documents\Work\JavaTests\TestProject - where the project directory current is, but it will be moved to Target.
  • Target Location: D:\Documents\Work\Git\TestProject\TestProject - new location for the project files.

Note that the Working directory field (read only) gives the repository location (D:\Documents\Work\Git in my case). Also note that the Current Location and Target Location are different. Current Location shows where my files are right now - in my Eclipse workspace. Target Location shows where my files will be moved to - a folder underneath the Git repository Working directory.

This means that when you press Finish, Eclipse will move your files out of the Eclipse workspace and into the Git repository folder. Don't be surprised - this is normal. It takes some getting used to if you haven't used Git before. In the Git repository, you will also notice a new folder - .git, which contains all the files Git uses to manage the repository.

Click Finish.

Now take some time to notice what has changed. The icons in Package Explorer are different.

Note the duplication in names - I have a Git repository called TestProject containing a project called TestProject. The icons reflect Git state. See EGit/User Guide/State which has this image showing at a glance the different states.

Also note that your files have indeed been moved out of your Eclipse workspace and into your Git repository.

Open up the Git Staging view: WindowShow ViewOther → select GitGit Staging.

This view makes it very easy to commit changes.

Click and drag the files down to the Staged Changes box. Type a commit message in the Commit Message text area.

Click Commit.

You can also do this with the commit action. Control+shift+3 is the default keyboard shortcut, or right click on the project and select Teamcommit. However, I find the Git Staging view much easier to use.

To top of post.

Create a project in GitHub (with the same name as our local project)

Go to GitHub and log in.

On the actions menu, select New repository.

Give Repository name the same value as your Eclipse project's name, and whatever Description is appropriate. Note that my repository is Public, so that anyone will be able to see what I check into it. Click Create Repository.

This screen gives us very important information that we will use in the next step - the HTTP URL for interacting with this repository from EGit in Eclipse: https://github.com/robertmarkbram/TestProject.git.

To top of post.

Check in our project to the remote git repository

Back in Eclipse, right click on your project in Package Explorer and select TeamRemotePush...

Most importantly, in the URI field, enter the URL we got from GitHub earlier. The Host and Repository path fields will auto-fill correctly. In the Authentication section, enter your GitHub username and password. I let Eclipse store these details by selecting Store in Secure Store. If this is the first time I have done it, Eclipse will ask me to set up a Master Password.

Click Next and you will see the Push to: ... dialog.

Click Add All Branches Spec. Under Source ref select master [branch]. Under Destination ref, select refs/heads/master.

Click Next and see the Push Confirmation dialog. Click Finish.

The project files will then be pushed to the GitHub remote repository. When it is complete, you will see a results dialog.

If you refresh your GitHub repository, you should now see the files committed remotely.

And underneath the main project folder are my files.

To top of post.

The two phases of commitment

We know have a system of two phase commits, so to speak. Work locally and commit changes to the local repository so you have a history and backups as needed.

When you commit, you have a choice of using Commit or Commit and Push. Just choosing Commit will commit your changes to the local repository. Selecting Commit and Push will commit them to your local repository and then push them to the remote repository - e.g. GitHub. The first time you use Commit and Push, it will ask you to set up the remote repository.

Press next and you will see the Push Branch master dialog wherein you tell Git what to do when pulling changes from the upstream repository i.e. bring changes from GitHub back into your local.

Hit Next and the rest of this is like any other commit, but you will have sent your changes to two repositories - local and GitHub.

To top of post.

Helpful Resources

To top of post.