Wednesday, 6 June 2012

Creating a correctly structured Git Repository using Eclipse and EGit

So I've been really getting into Git source control and playing around with it in order to get my head around the differences between Git and SVN (which I have far more experience with).

I love the whole DVCS concept. I have to remind myself often that every copy of the repository is a full copy of the repository. Migrating one of my projects that I was hosting remotely on a local server to a hosted repository at BitBucket became a lot easier once I realised I could just create an empty repository somewhere else and add it as a remote repo and push to it. So cool...

But I digress.

My purpose for writing this post is that I've seen a few people asking (because I was searching for the answer to the same question) about how to import a hosted Git Repository into a new project in Eclipse using eGit. Should be as easy as right-clicking in the workspace in Eclipse and choosing Team --> Import --> project from Git right? Uh.. no.

The problem is that this method, while cloning your project correctly, insists on adding a sub directory under what should be the repository root.... so let's say our repositories are stored by default at /Users/beldougie/git/MyProject. What you'd get is the project being created at /Users/cinh/git/MyProject/MyProject which isn't what we're after. Especially if you're working on something to be distributed. You need it to be structured correctly.

So I've found a solution (I think) in any case. It certainly seems to work for me. For this example, I'm using a private repository hosted at BitBucket and I'm going to set up an imported linked project that uses EGit to manage it. To follow along with this example you will need ssh access to your git repository at BitBucket. I'm not planning to write anything about that step of the process because there's plenty of material available already if you need it. Plus BitBucket's documentation is pretty thorough.

  1. So I'll start by creating a basic, empty repository in BitBucket.
  2. Next we need to create reference to the repository in Eclipse. If you don't already have the Git Repositories view open in Eclipse, open it...
  3. On your BitBucket repository page in your browser, copy your repositories url. Don't worry about the "e;git clone"e; part, we just need to copy the url
  4. Return to Eclipse and in your Git Repositories view, right-click in the open pane and you should see something like

    Click it.
  5. If you've copied the URL correctly from step 3, you will see a dialog appear similar to:

    Click 'Next' and it should connect to the remote repository to get a list of branches.

    Of course, this will be empty at the moment if this is a brand new repository so just go ahead and click next.

    On this last screen, do make sure you enter a tick next to "Import all existing projects after clone finishes". This will save you the following steps if valid projects already exist within your repository.
  6. Click "Finish" and you're done - at least you would be, if you had existing projects within your repository. But if you've been following along with this, you have an empty repository and, therefore you don't have any projects yet. So...

    Right click on your php explorer and click New --> PHP Project (assuming that you want a PHP project of course... it could be any project as far as I know but I haven't tested that.)
  7. Enter a name for your project, Select the option to "Create project at existing location (from existing source)" and enter the directory you cloned your remote repository to.

    Note the warning at the bottom of the dialog. It's really just a notification and shouldn't be a problem.
  8. At this point, just click "Finish" unless you want to configure the project further at this point. You can always go back and do this from the properties later on though, so we're just going to push on and create the project.

    You'll see a new project called "Dummy" (or whatever you called your project) in your workspace.
  9. There's still a problem though. If you right-click on your project and select the team option, you'll see that it still invites you to 'share' your project, or link it to a repository. So click the 'share project' option. In the dialog select Git and click Next

    Make sure you tick the option to "Use or create repository in parent folder of project" and tick select your project in the lower half of the dialog and you should end up with something like
  10. Click Finish and the connection is made and you now have the team functions enabled for your project:
  11. Unfortunately though, there is still a problem (if you're using BitBucket at least) because our remote repository was created without any branches. This is pretty simply fixed though. Because Eclipse has already added .project, .buildpath and .settings directories to the project root, we don't need to add a README file or equivalent (as the Git docs would have you do). Unless you want to of course. It's generally good practice.

    Anyway, I'll leave that up to you. What we're going to do is add a .gitignore file instead.

    I like to share my .project folder so people get my basic .project settings and can work in Eclipse nice and easily, but not my buildpath and .settings as they are system or even user specific. So to your .gitignore file add
    and then right-click on the project in Eclipse and click Team --> Commit.

    Fill out your commit message, tick the items for .gitignore and .project (to add them to the index) and click 'Commit'
  12. Now your project is committed locally, you'll have a master branch in your local repository. Right click on your project in Eclipse, choose Team --> Push to upstream and you now have a fully functional remote repository with EGit support in Eclipse and a correct project structure.

I hope this helps someone else, but I know it will help me the next time I forget all this (and I will!)

1 comment:

  1. Thanks a lot!


    I searched hours, to find a solution to get a "normal" structured git-project with egit! (And found it eventually in your post!

    Best regards,


Please leave your feedback and comments. I love to discuss this stuff!