Tutorial: Git with Eclipse

Posted on September 30, 2018 by Erich Styger

There are things which are game changer in the world of software development: one such event was when I started using a VCS (Version Control System): it changed for me how I keep and store my projects and settings. It even changed the way how I deal with non-software related items like documents or other valuable things: I started storing them in to a VCS too.

VCS in a nutshell

In a nutshell: a VCS is a data base or a system which allows me to store and retrieve files. It keeps a history and I can go back in time to retrieve an earlier state or compare different states. It ‘versions’ items or files in a kind of data base. In most cases such a data base is used by multiple users or developers, and with this the system is able to ‘merge’ changes of different developers: it keeps an audit track and backup of all the changes. Not using a VCS for any medium or larger scale project especially with multiple developers collaborating sounds like suicide to me. If you never have used a version control system, you probably want to start using one. I have used different VCS (cvs, svn, git), and while I still keep projects for historical reasons in vcs and svn, I’m using git for all my new stuff.

If a VCS or git is new to you, I recommend you have a look at this tutorial video: https://git-scm.com/video/what-is-version-control

Git – Quick Start

The git project has been started by the famous Linus Torvalds. It is a modern and distributed version control system. To install git, follow the links and tutorial on https://git-scm.com/downloads

With git there are several basic actions:

add: adding files to the list of changes
commit: enter the change into the (local) repository
push: transfer the changes in the local repository to the remote one
pull: get the changes from the remote repository

By default, there is always a local repository. A remote repository is needed to share something, e.g. on GitHub.

In the Git Bash shell, configure first your user name and default email address:

git config --global user.name "John Doe"
git config --global user.email "john.doe@company.com"

That all what we need for configuration.

To create a new git repository I use

git init myGitRepo

which creates the repository with that name after the ‘init’.

Next I create a readme.txt in that folder created (I’m using nano below, you can use any text editor):

cd myGitRepo
nano readme.txt

To add that file to the repository I use:

git add readme.txt

and then commit it to the repository with:

git commit -m"initial version of readme"

Instead doing things on the command line, you are free to use graphical clients, see https://git-scm.com/downloads/guis

EGit Client for Eclipse

I’m always having a GUI client installed beside of the command line version and the Eclipse plugin. Each client has its pros and cons, and I’m using SourceTree which is free-of-charge. My model is:

Using a GUI client like SourceTree for normal working with git
Using the command line version for more advanced things or for automation
Using the Eclipse plugin for working with Eclipse projects

My preference for an Eclipse plugin is ‘EGit‘, for which I wrote an article how to install it into CodeWarrior. Many Eclipse distributions already come with a git client pre-installed, and the NXP MCUXpresso IDE comes with EGit too.

Otherwise use (or update) from the following Eclipse Update site (Help > Install New Software):

http://download.eclipse.org/egit/updates

Going forward, I will show how to use Eclipse (NXP MCUXpresso IDE 10.2) with EGit.

Git Perspective and Repository Setup in Eclipse

In Eclipse I switch to the Git perspective:

From the git perspective, I can add an existing repository (e.g. the one I have created above with the shell):

Then browse to the repository folder and add it:

Instead using the shell, I can use it to create a new repository too:

Then it asks me for the repository folder name:

and it adds it to the available repositories:

Or I can clone from an existing repository, e.g. from GitHub. For this I use ‘clone’:

For example I can clone and use the McuOnEclipse repository on GitHub:

https://github.com/ErichStyger/mcuoneclipse.git

💡 You won’t have access rights to push to that repository on GitHub. If you want to make changes to a GitHub repository: Clone it on GitHub to your own list of repository and use your repository URL.

Press next and select the desired branch (if any).

Then specify the (new/empty) directory name where to clone the repository:

Press Finish and it will download repository content which might take a while depending on the data in the repository.

Adding Projects to Repository

With the repository configured, I can add an existing project to a repository. Right-Click on the project and select Team > Share Project…

Select the VCS to use:

Select the repository to use and press Finish:

Ignore File

Git uses the file .gitignore to filter (hide) files or folders which should not end up in the repository.

Git stores the list of files and folders to be ignored into a file named .gitignore. By default the Project Explorer view hides all files starting with a dot. To show them, use the ‘Filters and Customization’ menu:

And then uncheck the *.resources setting:

With this I can edit the .gitignore file inside Eclipse:

The file is processed from the top to the bottom, with # used to start a comment line.

As a general rule: ignore everything which is derived or generated as it would easily create conflicts in the repository.

💡 For a list of things to be ignored for CodeWarrior and Processor Expert see https://mcuoneclipse.com/2013/03/29/version-control-with-processor-expert-projects/.

Update: It is recommended to ignore the .settings folder of the project (see discussions in the comments section of this article). The .settings folder contains XML files with local plugin settings and are specific to the user. So in general I do not put that folder into the version control system. However, for some files like the language settings that still could be ok to share them. This depends on the plugins used and might depending on the Eclipse version too.

For MCUXpresso IDE and SDK projects it is very simple: only the output folder with the generated make and object files needs to be ignored which is usually named ‘Debug‘ and/or ‘Release‘. As seen from the above .gitignore, Eclipse already added this to the list, so we are fine :-).

One question remains with the NXP Configuration Tools. These tools (Clocks, Pins, …) create a file with a .mex extension in the project root:

Should I put it into the version control system? The answer is ‘no’, for three reasons:

The settings you do with the config tools are stored in the sources (e.g. clock_config.c) in YAML format.
When launching the config tools, if there are is no .mex present, it re-creates the content of it from the YAML in the sources. Therefore the .mex file is a ‘cached’ version of the settings in the sources.
Sharing the .mex file across teams in a version control system will easily create conflicts. Simply don’t do it.

Actually I really love the way the config tool is storing the settings in the sources in YAML format: that way I even do not need the graphical tool, I can do everything in the sources. And everything is perfectly shareable in a version control system.

With this, my typical .gitignore looks like this:

# Eclipse local settings, nothing special for my projects:
/.settings/

# all the build output:
/Debug/

# NXP config cache file, settings are with YAML in the sources:
*.mex

Commit

In the previous step I have added the project to the list of changes. But it is not yet stored in the repository. For this I need to do a commit. With the project added I have now many more actions available in the Team menu:

With the ‘Commit…’ menu item I get a Git Staging view:

The left upper area shows all the changes. I have to stage them into the lower left area using drag&drop or using the ‘+’ and ‘++’ icons in that toolbar and add a commit message:

Then I can commit (make the change in the local repository and push later) or do a commit with a push to the remote repository.

💡 I prefer to make smaller commits and then push them later. With a local (not shared) repository a push is not needed/possible as the push is to the remote repository.

Push, Pull and Compare

The push action is available in the Team menu:

In the same menu I find the pull actions (to get the changes from the repository.

To compare the changes, double-click on the file and it opens the Eclipse diff view:

Import from Git

Another cool thing is that I can import projects from git into my workspace. I use the Import item from the File menu:

Then select import from Git:

Select the repository source:

If you have cloned the McuOnEclipse repository, you can select that one or any of your repositories:

Then select the folder with the project(s) to import:

That way I can easily import projects from any repository :-).

As always with Eclipse, there are many ways to do one thing. Another way to import projects is from the Git Repositories view:

More Features

Be free to explore more of the EGit features in Eclipse. I recommend to go trough the Git perspective default views. For example the History view

Summary

Eclipse with the EGit plugin makes it easy to work with the git version control system. It takes a bit practice if not familiar with version control systems, but things are easy to learn and the internet is full of more tutorials and videos. Keep learning 🙂

Happy Gitting:-)

30 thoughts on “Tutorial: Git with Eclipse”

Liviu Ionescu (ilg) on September 30, 2018 at 21:41 said:

I know that this is a blog about Eclipse, but anway… I gave up using the Eclipse Git plug-ins long time ago, in favour of the separate Git client SourceTree (https://www.sourcetreeapp.com). The Mac version is probably the best Git GUI client available.

My main complaint about the Eclipse Git plug-ins was that they tried (at least in the beginning, when I evaluated them) to behave somehow similar to the SVN plug-ins, which is confusing, Git is really different from SVN.

LikeLike

Reply ↓
- Erich Styger on October 1, 2018 at 08:35 said:
  
  Hi Liviu,
  yes, me too: I’m using SourceTree for all the general Git work. Still the EGit plugin is handy to work within the Eclipse flow, but is not a replacement for a GUI client like SourceTree. I have used SVN a lot in the past, and I agree that early version of EGit had inherited some of that, but the current plugin is reasonable in my view.
  
  LikeLike
  
  Reply ↓
Brad on September 30, 2018 at 22:53 said:

Once you commit a project to the remote repository, can you delete the local files?

LikeLike

Reply ↓
- Erich Styger on October 1, 2018 at 08:28 said:
  
  Yes, but this means deleting it from your local copy, which means you won’t have it available any more e.g. to edit/build. The files remain in the remote repository, and if you do a pull the files will be restored on your local copy/disk.
  
  LikeLike
  
  Reply ↓
Joost on October 1, 2018 at 12:20 said:

Good article!
A confusing thing for me is still which files to check-in. Ideally you want _all_ project settings to be part of the git archive, for other developers to re-use, or to have them available when making multiple clones when working on different branches/features/bugs in parallel.
There’s the Eclipse .project and .cproject files (using relative paths?), and the .gitignore. And the include path/indexer settings that appear to be in the workspace (discovered just recently):
/home//workspace-eclipse/.metadata/.plugins/org.eclipse.cdt.core/.language.settings.xml
But I have seen SDK Eclipse example projects that have a .settings directory as part of the project structure; not sure yet if this gets copied to the Eclipse workspace when importing.
Perhaps there are more relevant files like this to be reused between developers (editor settings, highlighting settings, perspectives, cached index when large, …)?
In most case I’ve seen external make file projects (for automation purposes), in git, developing using Eclipse. How do other people do this (efficiently)? Custom wrapper scripts that create/modify the whole Eclipse workspace structure and start-up sequence does not seem the way to go. Ideally you want the features of Eclipse (debugger, assembly, etc.), with the speed and efficiency of a small editor/mini IDE like geany (www.geany.org).

LikeLike

Reply ↓
- Erich Styger on October 1, 2018 at 20:37 said:
  
  Thanks!
  You absolutely want the .project and .cproject files in the repository. The .gitgnore as well as it describes what to ignore.
  This has nothing to do with the Indexer thing: the indexer data is stored in the .metadata folder of the workspace, and that folder *never* should be in a version control system.
  The .settings directory in the project is debatable in my view: Usually I don’t store it as currently there is nothing of value and if I have a project imported without that .settings folder, things get recreated.
  But if you want to put it into the repository, why not.
  You can use external make files for the build, but this is rather a pain in my view. It is much easier to use the IDE in command line mode to build things, at least in a smaller scale. For larger scale systems it makes sense to use make files.
  
  LikeLike
  
  Reply ↓
  - Liviu Ionescu (ilg) on October 1, 2018 at 21:44 said:
    
    > The .settings directory … in the repository
    
    It depends on the plug-ins, but the files in this folder store the per-project user preferences, and sometimes include paths to local files.
    
    Putting these files in the repository makes life miserable to other team members, especially if they use different platforms (Windows/Mac/Linux).
    
    And even if these files do not include paths, being user preferences, might not match other users preferences.
    
    LikeLike
    
    Reply ↓
    - Erich Styger on October 2, 2018 at 07:28 said:
      
      Ok, good information! It seems I was right with ignoring the .settings directory in the past. I’ll add a note to the article.
      Multumesc mult!
      
      LikeLike
    - Liviu Ionescu (ilg) on October 2, 2018 at 08:21 said:
      
      Ok. Just that the files are not XMLs, but Java preferences (simple name=value lines).
      
      LikeLike
  - Joost on October 2, 2018 at 14:07 said:
    
    > The .settings directory in the project is debatable in my view:
    > Usually I don’t store it as currently there is nothing of value
    
    The Indexer settings, like include paths and macros, can be a long list. They did not seem to get stored as part of the project settings. I found them in my workspace, but apparently you can also store them as part of the .settings. In that case it would be useful to reuse those settings between developers/clones, and put it in git. I haven’t fully figured this out yet though. I was surprised this didn’t work as expected out of the box.
    
    LikeLike
    
    Reply ↓
    - Erich Styger on October 2, 2018 at 14:13 said:
      
      The include paths and all the other projects settings are in the .cproject file, see https://mcuoneclipse.com/2013/03/29/version-control-with-processor-expert-projects/.
      The Indexer in Eclipse is something completely different, see https://mcuoneclipse.com/2012/03/20/fixing-the-eclipse-index/
      
      LikeLike
    - Joost on October 2, 2018 at 14:27 said:
      
      > The Indexer in Eclipse is something completely different
      
      Not entirely it seems. For the Indexer to work, I needed to set the project settings -> C/C++ General -> “Preprocessor Include Paths and Macros etc”. These did not end up in the project settings but in the workspace .metadata. So a second clone, or other developer, did not have this long list of required settings. This was/is still the unexpected part.
      [Eclipse Photon Release (4.8.0)]
      
      LikeLike
    - Joost on October 9, 2018 at 11:01 said:
      
      In Eclipse [Photon Release (4.8.0)] there appear to be _two_ configuration items for include paths,etc (?).
      – project settings -> C/C++ General -> “Paths and Symbols” (also has include paths, macros, etc.)
      – project settings -> C/C++ General -> “Preprocessor Include Paths and Macros etc”
      Not clear what the difference is, and the impact on the Indexer. I’ll see if I can play around with it a bit. Perhaps they end up in different config files.
      
      LikeLike
    - Erich Styger on October 10, 2018 at 07:45 said:
      
      These two configuration settings are typically populated by the CDT build plugin (project settings > C/C++ Build > Settings) and do not need to be configured, at least to my knowledge.
      Or in other words: the include path settings and the preprocessor macros shown there are coming from the build tool settings (compiler, assembler).
      
      LikeLike
    - Joost on October 10, 2018 at 17:03 said:
      
      When you have an external makefile project, I believe you need to modify the Indexer settings (see also https://mcuoneclipse.com/2017/07/22/tutorial-makefile-projects-with-eclipse/). Unless there’s an Eclipse feature I don’t know about. Will investigate some more.
      
      LikeLike
Gary on November 16, 2018 at 18:54 said:

Another great git GUI that I’ve recently found and like is Git Extensions: https://github.com/gitextensions/gitextensions. It’s very much no-frills, function over form, and gets the job done.

I didn’t like the idea of having to register and “integrate” with Atlassian just to manage projects which have no interaction whatsoever with Bitbucket in the case of Sourcetree (assuming I didn’t mess up during the install and bring that on myself). Git Extensions is the best standalone, free license alternative I’ve found.

LikeLike

Reply ↓
- Erich Styger on November 17, 2018 at 06:08 said:
  
  Thank your for that link, this is indeed an interesting alteratnive. I did not like that Atlassion registration too, and the constant updates which seem to cause some problems on my end too.
  
  LikeLike
  
  Reply ↓
Pingback: Upgrade to a new NXP MCUXpresso SDK | MCU on Eclipse
Pingback: Organizing Projects with Eclipse and Git | MCU on Eclipse
Alex on September 7, 2021 at 11:51 said:

I’m a little late to discussion, but still.

If you want your developers to easily import and start using projects on their machines right away, you absolutely need to store .settings folder under VCS.
1. language.settings.xml file has Discovery settings in it and for Indexer to show correct results you need these settings.
Not having correctly working Indexer causes mistakes and frustration as people don’t see what exactly they are building (especially with code disabled by #if #else, #ifdef, etc.). If these settings are not under VCS, you have to set this up manually on each machine you’re going to use the project.
After doing it for fifth time in one project I decided it’s time to start storing Discovery settings in VCS.

2. If you have each project use specific toolchain and build tools (and you absolutely must have it this way), toolchain and build tools paths are stored in respective files under .settings folder. So, naturally, you need this in VCS.
Having anything but specific toolchain path stored within the project is a bad idea as different developers will have different global or workspace toolchain settings in their local Eclipse and you’ll end up with different people building same sources with who knows what compilers ending up with different binaries from same sources – been there, saw it all the time.
Even more – sooner or later you’ll end up with different projects being built with different version of compiler (say, we have gcc 7.1.1, gcc 8.1.0 and gcc 10.1.0 at the moment). And you want to use one IDE for all of the projects. The only way to have it is to store paths to specific toolchains for each project.

Last time we set up new machine, it was all just “put compiler into predefined folder, checkout project, import it in Eclipse, go”. No manual fiddling AT ALL.

The only downside of having .settings folder under VCS is env-hash field in language.settings.xml. Environment hashes in this file are being changed all the time. I have to remember about it and skip commiting this file if it’s only hashes. This is frustrating but still better than having set up everything by hand for every developer. There are several discussions about this issue and I don’t see any workaround. Maybe newer versions of Eclipse have this fixed, but we still use pretty old ones.

LikeLiked by 1 person

Reply ↓
- Erich Styger on September 7, 2021 at 15:18 said:
  
  Thanks for all the details and explanation! Indeed, it might be good to store some settings, but It seems it heavily depends on what plugins are used. As for myself (using CDT) I had no issues not storing/sharing the language.settings.xml, and indexer/etc always worked fine, and the file gets automatically recreated with the correct content if it is not there. So I think it really might depending on the plugins, and one need to check the individual files in the .settings folder: if the entries are ok and not using any machine specific data, they could be stored in a VCS, otherwise not. As always: it depends and makes things complicated I think.
  
  LikeLike
  
  Reply ↓
  - Alex on September 7, 2021 at 15:48 said:
    
    Are you working alone or in a moderate size team?
    
    LikeLiked by 1 person
    
    Reply ↓
    - Erich Styger on September 7, 2021 at 16:19 said:
      
      Team size is different for different projects. Some use a ‘team of 1’, most use 4-6 team members, but I’m running projects with up to 50 members too.
      
      LikeLike
    - Alex on September 9, 2021 at 13:43 said:
      
      Team of 50 people is impressive.
      How do you manage which compiler all of the members use on their local machines? Eclipse by default uses whatever global settings are present and build every project with this global settings. Which is not just bad, but dangerous – everyone gets different results.
      You might set up your CI/CD server correctly, but on a daily debugging basis people still have to build things locally. Or maybe I’m living in the past and you build everything only on CI/CD server?
      
      In my practice this is one area where people tend to not fully understand what happens when they press “Compile” button in Eclipse – what make is being used and where does it get the compiler to do things.
      
      LikeLiked by 1 person
    - Erich Styger on September 9, 2021 at 14:03 said:
      
      Most projects are with the eclipse based NXP MCUXpresso IDE which makes things super easy: everything is within the IDE, including the build tools, so everyone is using the exact same environment, and that way the build environment is the same for everyone, and no problem occur. For the stock eclipse projects I’m using the GNU MCU Eclipse plugins which allow a very flexible build environment: for these I package the build tools into the IDE locally too: that way everything is self contained like in a container. Or in other words: to control things everything is IDE centric, and no ‘global’ tools are used.
      
      LikeLike
    - Alex on September 9, 2021 at 14:07 said:
      
      So you never had to work simultaneously in one Eclipse IDE on several projects requiring different toolchains?
      For each project there’s self-contained standalone Eclipse?
      
      LikeLiked by 1 person
    - Erich Styger on September 9, 2021 at 14:11 said:
      
      Sure, an Eclipse instance can have multiple and different tool chains if needed. This is handled by the GNU MCU Eclipse plugins which allow both to use the ‘global’ Eclipse toolchain or a toolchain specified by each project (project specific). The key is that the toolchain(s) are bundled with the Eclipse used by the development team.
      
      LikeLike
    - Alex on September 9, 2021 at 14:19 said:
      
      That’s exactly was my point. GNU MCU plugin can use toolchain on a project specific basis, but this setting goes into .settings folder.
      If you’re not having this folder under VCS, you have to set the project manually on each developer’s machine. Otherwise MCU plugin will NOT override global Eclipse toolchain path.
      And this was my original question – if you’re not storing .settings in VCS, do you manually set up toolchain on each machine or maybe you find a way to share toolchain settings somehow, not with .settings folder?
      Or do you always just use one global IDE toolchain and never had to use different toolchains at all.
      
      LikeLiked by 1 person
    - Erich Styger on September 9, 2021 at 15:43 said:
      
      Ok, I see now what you mean: indeed, if you make local project settings to point to custom build tools or custom compiler, they are ineed stored inside .settings/ilg.gnuarmeclipse.managedbuild.cross.prefs. And indeed, apart of a few ‘trial’ projects which were not put onto git, no project is using ‘custom’ settings like this, and only use the ‘global’ toolchain. So indeed, if using a custom toolchain per project, that file needs to be stored in git. One just need to be careful and not using absolute paths in there, as it would not make it portable.
      
      LikeLike
    - Alex on September 9, 2021 at 16:17 said:
      
      Yeah, now we’re on the same page 🙂
      I made a lot of effort to set up things so there’s only relative paths in the projects. After that we are able to just import projects on a clean machine and start working without any fiddling with local settings.
      
      LikeLiked by 1 person

What do you think? Cancel reply

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

MCU on Eclipse

Everything on Eclipse, Microcontrollers and Software

Tutorial: Git with Eclipse

VCS in a nutshell

Git – Quick Start

EGit Client for Eclipse

Git Perspective and Repository Setup in Eclipse

Adding Projects to Repository

Ignore File

Commit

Push, Pull and Compare

Import from Git

More Features

Summary

Links

30 thoughts on “Tutorial: Git with Eclipse”

What do you think? Cancel reply

VCS in a nutshell

Git – Quick Start

EGit Client for Eclipse

Git Perspective and Repository Setup in Eclipse

Adding Projects to Repository

Ignore File

Commit

Push, Pull and Compare

Import from Git

More Features

Summary

Links

Share this:

Related

30 thoughts on “Tutorial: Git with Eclipse”

What do you think? Cancel reply