What is an Eclipse or STS Workspace?

What is a workspace in an Eclipse-based integrated development environment (Eclipse, Spring Tool Suite, etc.), and how do you use it? For all of the documentation on Eclipse, including configuring workspace settings, nothing in the docs explains the basic concept.

Background and Structure

There are situations when a programmer needs to have multiple projects open at the same time because there may be dependencies and/or need to be worked on in parallel. Some IDEs require multiple copies to be open, but Eclipse allows the programmer to work on multiple projects in a single instance of the IDE.

There are advantages and disadvantages to this. An obvious advantage is that a programmer can switch back and forth between files in different projects or view them side-by-side. And an obvious disadvantage is that the programmer can become confused as to which project a particular file belongs and edit the wrong file, especially when the files have the same name or appear similar.

Eclipse solves the multiple-project problem with a workspace. A workspace is simply a folder somewhere on the computer. Workspace folders work best on a storage device which is local to the computer. The workspace folder is used to store configuration information. This includes which projects are part of the workspace, which projects are open (because projects can be closed in a workspace too), which files were open when the workspace was last closed, and what the perspective (layout) of the Eclipse window last was. This all allows Eclipse to pick up right where the programmer left off the next time the workspace is opened.

All of this information is stored under the .metadata hidden folder, and in folders and files hidden underneath it. For example, the project information (not the files) is stored in folders mirroring the project name in .metadata/.plugins/org.eclipse.core.resources/.projects, and the perspective selected and its last layout information is stored in .metadata/.plugins/org.eclipse.e4.workbench/workbench.xml.

A quick google search will reveal where the settings for any aspect of Eclipse are stored in these plugin folders.

Best Practices

Should you store project source under the workspace folder? It does not really matter. Eclipse creates new projects by default in the workspace folder, each in a folder with the project name. This makes it easy to find the project files for related projects. But on the other hand, sometimes projects may be used in multiple workspaces and it would make more sense to keep the project source folders outside of the workspace folder. This is a choice you need to make. If there was one best way to do it, then that would be the only way to do it!

Keep projects in the workspace closed unless you are actually working on them. You can right-click and close (or open) a project in the Package or Project Explorer. This just helps to keep you from accidentally editing the wrong file where multiple projects have files with the same name or have similar content.

Use Git at the project level, which is the normal obvious way to have projects in repositories. You really do not want to have a Git repository that contains multiple projects because publishing changes to one project would impact all of the other ones. And, you really do not want to publish your workspace settings into the Git repository. They are your development environment, not anybody else.

As a side-note you have to think about Git, projects, and individual project settings. Project settings are stored in the .project folder in the project source, not in the workspace. The subject is outside the scope of this document, but was addressed in two of my other blog posts, Eclipse Team Projects and Best Practices, and Normalizing SDKMAN Across Development Computers.

Copying or Sharing Workspace Settings

In the upper-right corner of the Eclipse window you can select the perspective that you want to use. You can also rearrange pretty much everything in the perspective you are using, including removing and adding new views (Window menu -> Show View). And you can save your new perspective with a new name by right-clicking on the current perspective button and choosing "Save as..."

When you create your own new perspectives, they are local to the workspace you are in when you do it. You may want to use a custom perspective in a new workspace, or you may want to share it with someone else.

Assuming that you want to create a new workspace and have your custom perspectives, the easiest way to do this is to use the File menu -> Switch Perspective, select Other..., expand Copy Settings, and check the Workbench Layout before you make the new workspace.

Or, in the current workspace you can select the menu option File -> Export..., and in the dialog expand General and select Preferences. You will probably want to leave Export all option checked. Then open the new workspace and reverse the process and import the preferences.