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
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 "firstname.lastname@example.org"
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):
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:
💡 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:
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 :-).
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:
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
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 🙂
- git version control system software: https://git-scm.com/
- Subversion (svn): https://subversion.apache.org/
- Concurrent Versions System (cvs): https://en.wikipedia.org/wiki/Concurrent_Versions_System
- Version Control with Processor Expert Projects: https://mcuoneclipse.com/2013/03/29/version-control-with-processor-expert-projects/