Checkout multiple projects automatically into your Eclipse workspace with Team Project Sets

When working in Eclipse, you’ll often end up with a number of projects in your workspace that constitute an application. You could have a multi-tiered system with a web, server and database project and other miscellaneous ones. Or if you’re an Eclipse RCP developer, you could end up with dozens of plugins each represented by a project.

Although multiple projects give you modularity (which is good), they can make it difficult to manage the workspace (which is bad). Developers have to check out each project individually from different locations in the repository. Sometimes they even have to get projects from multiple repositories. This is a painstakingly long and error-prone task.

But an easier way to manage multiple projects is with Eclipse’s Team Project Sets (TPS). Creating a workspace becomes as easy as importing an XML file and waiting for Eclipse to do its job. Yes, there are other more sophisticated tools out there that do this and more (eg. Maven and Buckminster) but team project sets are a good enough start if you haven’t got anything set up and may be good enough for the longer term as well, depending on how your team works.

Create a Team Project Set to share with other developers

It’s easy to create a team project set (TPS).  The first thing is to start with a workspace that already has all the projects checked out. Then it’s as easy as choosing File > Export > Team > Team Project Set, selecting the projects you want to export and then entering a file name. Done.

But it’s always better to see it in action. In the video, I export 3 projects that I’ve already checked out from Subversion into a TPS file.

Notes:

  • You can select which projects should go into the TPS. This way you can exclude irrelevant or personal projects you’ve got in your workspace.
  • Eclipse adds the extension .psf if you don’t provide one.

The exported file is an XML file, with the default extension of psf, so in the video the file would be music.psf. There is a project entry for each project you exported that includes the project’s name and its repository location, separated by commas. Once created, the file is easy to edit so go ahead and make your own changes if you want to. Here is an example of what it looks like:

<?xml version="1.0" encoding="UTF-8"?>

<psf version="2.0">	 	 

<provider id="org.tigris.subversion.subclipse.core.svnnature">	 	 

<project reference="0.9.3,file:///C:/Temp/svn/repo/music-application/trunk,music-application"/>	 	 

<project reference="0.9.3,file:///C:/Temp/svn/repo/music-db/trunk,music-db"/>	 	 

<project reference="0.9.3,file:///C:/Temp/svn/repo/music-web/trunk,music-web"/>	 	 

</provider>	 	 

</psf>

Import the Team Project Set to checkout multiple projects into your workspace

Now for the fun part. To import a team project set (TPS), start with any workspace (normally an empty one) and choose File > Import > Team > Team Project Set. Choose the TPS file that someone else kindly exported for you and then wait for Eclipse to do its magic.

Notes:

  • If you have an existing project in your workspace whose name matches a project in the TPS, Eclipse will prompt you whether you want to overwrite the project. I always choose No To All, since overwriting the project will mean you lose any changes you made to it. But if you have the urge to start from scratch then you can choose Yes.
  • The import also creates a link to the repository in SVN Repositories, so you don’t have to do that. If one already exists, it will not duplicate it but reuse the existing connection.
  • The process may take a while depending on the number of projects in the TPS and the speed of your repo checkouts. You can choose to run the import in the background (as I did in the video), giving you the opportunity to use Eclipse while the import happens. Otherwise, grab some coffee and wait for it to finish the checkouts.

Gotcha: You may find that Eclipse 3.4 and lower may actually create a repository connection per project if the repository didn’t exist beforehand, which is not ideal. To solve this, create an initial repository root that’s shared by the projects and then do the import of the TPS. This problem has been fixed in 3.5

Managing the team project set and working with branches

I’d recommend checking in the team project set into your repository and versioning/tagging it along with the rest of your code base. With each release you may be adding/removing projects and consequently updating the TPS, so it’s important that the TPS matches what the repo looks like at that point.

As projects are added/removed with each release, you have 3 possibilities:

  • Recreate the TPS from an existing workspace: Same as the steps above, but it means that whoever does the export needs to maintain an up to date workspace to reflect the current project structure.
  • Modify an existing TPS with the new/deleted project: This entails adding/removing an entry from the PSF file. Not a lot of maintenance, but someone needs to remember to do this.
  • Automatically create/update the TPS: You could write a script that somehow updates the TPS to reflect the new repo structure. For example, if you’re developing an Eclipse RCP application, the PDE Build provides a map file that could be used as input to create the PSF file.

If you want to checkout a branch other than trunk, just open the PSF file and do a Find/Replace of trunk with your branch name. You could also introduce an automated process as part of your build/release scripts to update the TPS with the correct branch and check it back in automatically, but that’s really optional.

Related Tips

Support Eclipse On E

7 thoughts on “Checkout multiple projects automatically into your Eclipse workspace with Team Project Sets

  1. Thanks for artical
    What is format and option for TSF (may be psf) file ?
    How I can change the checkout folder to other that default root workspace

    • Thanks for the comment, Dmitry. The psf file is just an xml file with a element for each project in the workspace. Each project element contains the project’s name together with the svn path. There’s an example of a psf above in the post (I’ve updated it recently because the format got broken). I think you can only save it out in xml format.

      As for using a checkout folder outside the workspace, I haven’t seen a way of doing it easily with the default team project sets (but that doesn’t mean it doesn’t exist).

      As an option, you could create a dummy Eclipse workspace in a new folder and import your team project set (which will checkout the projects into the new folder). Then you can create a second workspace and import those existing projects into the second workspace (using File > Import > General > Existing Projects Into Workspace). Other than that, I’m not sure how to go about it.

      If you can let me know why you want to check out the projects into a different folder, I can try and think of an easy way in Eclipse to help you.

    • I have the same question: how can I change the checkout folder.
      I need this, because we have a huge count of projects and for receiving different applications we are combining them in different ways. Sometimes we get new team members and they should manually setup their Eclipse. This is very boring.
      We’d like to have “one-button” setup and psf files very nice… but folders are required.
      Another way I though: (1 step) use psf and (2 step) refactoring script to move project to their folders, but this action does not recorded in refactoring history and I don’t know how to write it with myself.

  2. Hey Byron, good explanation, but what I need is a bit more complicated. I’m trying to do all of the above under program control. I’ve found the ProjectSetCapability class and the addToWorkspace() method that does the import, but I can’t figure out a clean way to deserialize the .psf file into the String[] that addToWorkspace() expects.

    I’d prefer to use some Eclipse built-in deserializer, but if no such exists I can always just run the .psf through an XML parser.

    Any thoughts?

    • Thanks for the comment Hagstrom. I just had a quick look at the Team code and it seems like you could work with the class that the wizard itself uses, ie.


      // Run the operation with no dialog container, the psf filename
      // (presumably the name as java.io.File would expect it) and no working sets.
      ImportProjectSetOperation operation = new ImportProjectSetOperation(null, psfFileName, new IWorkingSet[0]);
      operation.run();

      This way you only have to pass the filename without having to worry about deserialising it or other nasty bits that may have to be set up. The operation calls addToWorkspace() eventually down the line so you shouldn’t have to.

      ImportProjectSetOperation is in the plugin org.eclipse.team.ui and it’s called from the import wizard’s finish method (ProjectSetImportWizard.performFinish()).

      I’d try and make this work without having to worry about interpreting the file myself. I haven’t tried any of this myself so please let me know how it goes.

  3. Actually if all projects are in the same repository it is not necessary the procedure above. Just add the repository and than File – Import – SVN – Checkout Projects from SVN – Use existing repository location – select all and finish.

    • Thanks Luca. You’re absolutely right, that is another (easier) way to do it especially if you’re repo is structured correctly, ie. by branch then modules instead of by modules then branch.

      The team project set technique is probably more suited for working across different repositories and also where you want projects from different “trunk roots” to form the workspace (possibly doesn’t affect the majority of people but sufficient to be a problem, I’d guess).

      I think I’ll add a note to the post to mention that as it’s important.

Leave a Reply

Your email address will not be published. Required fields are marked *