Organizing Projects with Eclipse and Git

There are many ways to organize projects and workflows, and I would say Eclipse is flexible enough for everything. As I have been asked recently how I organize my projects, I’ll share it here.

Eclipse Workspace and Project Location with Git

Eclipse Workspace

Eclipse has the concept of a ‘workspace’: This is what you select at starting the IDE.

Workspace Selection

Basically a ‘workspace’ is a ‘collection of projects and settings’.

A workspace folder contains the .metadata folder:

This hidden folder is used to store the workspace settings including the list of projects.


An Eclipse project is a folder with a .project file in it:

That file for example specifies the name of the project. Depending on the project type there can be other setting files like .cproject which is for a C/C++ project.

Default Project Location

During project creation the default location is the current workspace folder, but you are free to use any folder location you want:

Default project location

So how do I organize projects, especially in combination with a version control system like git?

Separating Workspace and Projects

What has worked best for me is to separate the ‘workspace’ folder from the project folders. The workspace folder is *specific* to an Eclipse version and never should be shared or ‘re-used’ between different Eclipse IDEs. So my workspace folder is IDE specific. I only place ‘scratch’ projects in the workspace folder (e.g. trying out an SDK example) which I delete afterwards (‘kill-me projects’).

The ‘real’ or ‘valuable’ projects I put under version control like git. A git repository is basically a collection of files and folders, cloned on my disk somewhere.

So all the valuable projects are outside the workspace folder, but they are still listed in the ‘Project Explorer’ view because I have ‘linked‘ them.

Linking Projects

Using Drag&Drop a project folder to the MCUXpresso IDE, I can choose to link it:

Linking Project with Drag&Drop

Using the File > Import > Existing projects I do not copy them:

Link Imported Projects

Version Control Projects

The reason for this: I have many projects in my workspace, from many different git repositories. Putting the workspace folder under version control is problematic as I have to make sure the .metadata folder is *not* put under version control (.ignore it). Having projects organized in individual git repositories I have the freedom how I want to organize them, and what I want in my workspace.

Below is an an example of my projects and where they are in a git repository:


It is really up to you how you organize things, but I hope it gives you some ideas how things can be done. I prefer to use the Eclipse Workspace folder as a scratch area and store my git projects in separate folders.

Happy EclipseGiting 🙂


9 thoughts on “Organizing Projects with Eclipse and Git

  1. Super helpful! Now if only Microsoft Studio and its derivatives (e.g. Microchip Studio) were as git friendly as Eclipse! (I’m still trying to figure out if it’s possible to link an entire directory in MS.)

    Liked by 1 person

  2. Basically the same way I’ve been doing it for years. Separating projects from the workspace (when the projects are version controlled) is the route to a happy life with eclipse.

    Liked by 1 person

    • Yes, I do the same for many years, and teach that to students too. It should be an obvious way to work with projects and git, and still I see many not following that best practice.


  3. It’s worth mentioning that the way Eclipse gathers projects together into a workspace has consequences for the referencing of files and folders between projects. Projects should not assume that they are peers with other projects at the filesystem level. For example, a CDT managed build executable project which uses an object library provided by another project should set the include path and library search path using the workspace_loc dynamic build variable to ensure that the project is fully portable.

    Portable: ${workspace_loc:/myLibraryProject/include}
    Not portable: ../../myLibraryProject/include

    Liked by 1 person

    • Hi John,
      good point!
      If the project location is outside the workspace then using a workspace variable or workspace relative path does not work. Project relative path to other pieces of the project which *are* indeed relative to the project (e.g. common folder between projects) are a good thing. If there are dependencies between independent projects or libraries, then I recommend using Eclipse Build Variables:

      Liked by 1 person

      • To be clear, ${workspace_loc} with no argument resolves to the absolute workspace location (not usually very useful), but when specifying an Eclipse resource as an argument such as ${workspace_loc:/myLibraryProject/include} the dynamic build variable resolves to the absolute location of the specified resource which might be anywhere on the file system (not necessarily under the workspace folder). So we can reference files or folders in one project from another project without any knowledge of their relative or absolute locations on the underlying filesystem.

        Liked by 2 people

        • Hi John,
          ah, I see now. So yes, this is useful in that case. But one need to be careful with these absolute (potentially long) paths, as you can easily run into the 8K path/command line limit which to my knowledge still exists on Windows. So it makes sense to use relative paths to everything inside the project itself.

          Liked by 1 person

  4. Thanks for the tip, Erich!

    Have you weighed the trade-offs between locating projects on a network server vs. on your c: drive? There can be a significant difference in access times when working from home over VPN. Obviously using your c: drive makes you responsible for backups and I wonder if you have any experience-based advice on trade-offs.

    Liked by 2 people

    • Hi Gary,
      I *never* files on a low latency device (network server, etc). It is not only much slower but can lead strange problems, especially if placing the workspace itself into such locations. I have seen many cases where students did place their project or workspaces in to ‘shared’ locations with dramatic consequences.
      The true answer is: use git! I mean git with a remote repository and a local clone. This is the big benefit of git: you can work locally with the maximum speed while having the ‘backup’ automatically synced with the one on the server. So using Git (with the distributed repo) is what I recommend and what I’m using: it solves all these problems and gives you backups, tracking, versioning, ….

      Liked by 1 person

What do you think?

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.