Migrating Eclipse projects to new locations

Preface

To begin with, the operation described here is something that falls outside of the way Eclipse is meant to be worked with.  Eclipse has a concept of "Workspaces" to allow the IDE to be completely reconfigured for the type of development that is being done.

This is a great idea in theory, but in practice it can be quite cumbersome and off-putting.  Off-putting simply because changing a Workspace means that everything needs to be reconfigured again.  Font colors, view locations, and who knows what else.

It's true that creating a new Workspace allows the Workbench Layout and Working Sets to be copied.  And the settings can be exported from one Workspace to the next.  Still, once all of this is done, if changes are made in one, they would have to be applied to any of the other Workspaces that have been create as well, if one wants to maintain a consistent environment across all projects.  Plus, it doesn't really work anyway.  All Views still need to be replaced to where they were in the other Workspace, and the whole application is restarted when a Workspace is changed.

What becomes of this approach is that besides managing development and projects, it becomes a matter of managing the IDE too.  And the driver for all of this is illustrated in the next section, "The Problem."


The problem

Project management is a mandatory feature of any IDE.  The implementation in Eclipse has some nice features like "Working Sets," but it can be frustrating when trying to organize projects because Eclipse can only recognize projects in the root of its Workspace.

This proves to be problematic if a more intricate organization of projects becomes necessary.  The command that allows a project to be moved doesn't work as expected and as such isn't an option.  So, the following steps describe how to go about organizing projects.


The procedure

This assumes a set-up developing PHP web applications on a Mac OS X system with Eclipse using ~/Sites as its Workspace directory and the following three projects.

~/Sites/PHPProject1
~/Sites/PHPProject2
~/Sites/PHPProject3

The environment is being rearranged to accommodate development for other technologies like CFML and is being restructured to look like this:

~/Sites/php/PHPProject1
~/Sites/php/PHPProject2
~/Sites/php/PHPProject3
~/Sites/cfml/CFMLProject1
~/Sites/cfml/CFMLProject2
~/Sites/cfml/CFMLProject3

The situation could just as easily be driven by the need to support more than one customer.  Perhaps, it would be nice to organize projects by customer.

~/Sites/LittlePigsPetSupply/store
~/Sites/RockyRoadPaving/fleet
~/Sites/HighSeasTours/fleet
~/Sites/SportShoes/payroll

Using a single Workspace, there would be a problem between the fleet applications developed for both RockyRoadPaving and HighSeasTours because the folder structure for each of the applications would be:

~/Sites/store
~/Sites/fleet
~/Sites/fleet
~/Sites/payroll

Of course the problem could be remedied with a structure like this:

~/Sites/LittlePigsPetSupply-store
~/Sites/RockyRoadPaving-fleet
~/Sites/HighSeasTours-fleet
~/Sites/SportShoes-payroll

Honestly, this "solution" is a little messy and would be painful to maintain as applications accumulate.

Based on the way it's described in the "Preface," Eclipse would like each one of these set up as a new Workspace.  That is, a new Workspace for each new technology (PHP, CFML, et cetera), but it would be so much nicer if projects could be organized into sub-folders off of the Workspace.  The procedure described in the rest of this article explains how to do this.

If projects are being moved to sub-folders in the Workspace, move a project like this:

1. Create a directory for the project in its new location.

   ~/Sites/php/PHPProject1

2. Copy the .project file from the project's old folder into the new project folder.

   ~/Sites/PHPProject1/.project
   

   to

   ~/Sites/php/PHPProject1/.project

3. Import the project into Eclipse.

   File | Import… | General | Existing Project into Workspace | Next

   NOTE: This is really just sort of re-telling Eclipse about its own project. The import process seems to be necessary just to tell Eclipse to rewrite all it's path references.

4. Select root directory (browse to the project's new folder)
5. Choose the project from the listing under Projects.
6. Finish
7. Copy all the files from the project's old directory to the new one.

   NOTE: On Unix-like and Mac OS X systems, this operation may best be performed via the command line so as not to miss any "dot" files. For example, if there is a Git repository in this directory it will likely be named ".git." Copying the files from the GUI might miss files like this if it's not set to show all files.
   
   NOTE: It's also important not to copy the .project file again.  This will overwrite the file that Eclipse just imported and all the references it just recreated will be undone.  Additionally, Eclipse creates a .settings directory and .buildpath file.  It might be better to avoid copying these files as well in case there are any vestiges of the old path in these as well.

8. Re-add any Build Paths or Include Paths that were in the old project.

Consider This

If designing a project structure like this, it's important to understand that it will impact the creation of new projects.  New projects will involve stepping through this procedure each time, except that it will need to be created initially as a sort of temporary project.  These steps will be taken to then, import that project into its final home.

~/Sites/newApplication-temp

will ultimately be

~/Sites/somefolder/newApplication