One thing that every embedded software developer, and hopefully every general software developer has in common is that they use a revision control system to manage their software. There are different revision control systems out there, but the most popular system today is Git. If you have never used a revision control system or are just getting started using Git, here are a few tips and tricks for mastering Git that will help get you up to speed quickly.

 

Tip #1 – Start using Git from the command line

When I first started to use Git, I started out using a graphical user interface (GUI) that completely abstracted out the details of Git and what was happening behind the scenes. This was certainly convenient, but the problem was that I had no clue what was happening behind the scenes. The lack of understanding about these details created gaps in my knowledge which made managing the repository more difficult.

When getting started, the best thing to do, even though it will be slower at first, is to use Git through the command line. This forces a developer to fully understand Git, how it works, what the commands are and get the behind the scenes knowledge. Only then, does it really make sense for a developer to abstract those details and move to a GUI.

 

Tip #2 – Practice with a test project

Developers can learn Git on the fly on a project, but the best way to learn is to take some time and create a test project. A test project provides several advantages to the develop team such as:

• Experimenting with branching
• Experience merging branches
• Working in a repository with multiple developers
• Integrating continuous integration and testing
• Figuring out the workflow and how to fix inevitable issues

A test project doesn’t have to be complicated. It can be nothing more than a few text files that developers paste random text into. Developers can play with their project organization, how to ignore specific file types such as object files and even create submodules.

 

Tip #3 – Use submodules

A Git submodule is basically another Git repository that is included as part of another repository. For example, I was recently working on a project that used Microchip Harmony library for all the low-level drivers and some middleware support. Rather than create a single project repository, I created a repository to store the Microchip Harmony library and then another repository for my application code. The Microchip Harmony library was included in the application repository as a submodule.

The submodule in this case also has a few additional advantages. First, I can use the submodule across multiple repositories. If I’m working on several projects that use Microchip Harmony, I don’t have to keep separate copies of the libraries. I just have the Microchip Harmony repository that I add as a submodule to my application repositories. Second, when I check-out my application and make changes, by default the submodule will not be included without additional commands or command options. This is useful because if I had checked everything into a single repository, it would take git several minutes to search my project for changes due to the number of files that are contained with the Microchip Harmony library.

 

Tip #4 – Leverage Git GUI’s to simplify software management

I’ve always found working from a terminal to be a bit tedious. Terminals do provide an extra level of control that many developers may want to use, but once you understand what Git is doing behind the scenes and its capabilities, it is often usual and faster to abstract those details out and use a GUI tool to interact with the repository. There are many GUI tools out there that developers can use. The two that I use the most are SourceTree and TortoiseGit. SourceTree is a tool that is provided by Atlassian for free that works with Mac and Windows machines. TortoiseGit is for Windows and integrates directory into Windows Explorer which can be pretty convenient.

 

Tip #5 – Develop and / or adopt a standard Git flow

The nice thing about getting started with Git is that there are quite a few workflows that have already been developed and used by developers for years. When getting started, you can try to figure out what works for you by trial and error, or you can use a standard Git flow. There are several different workflows that have become quite popular such as:

• Gitflow Workflow
• Forking Workflow
• Feature Branch Workflow

I personally typically use a Feature Branch Workflow. A developer in this case creates a branch from the mainline that is used to develop a specific application feature such as an ADC driver, button debounce feature, etc. Other developers working on the project also create branches for themselves to work from while they develop their feature. Once the feature is complete, it is merged into the mainline. This has several important advantages such as:

• The mainline never contains experimental or broken code
• The mainline can be used by a continuous integration server
• Each developer works from their own branch, minimizing impact from work being performed by other developers

You can learn more about different GitFlows from the official Atlassian tutorial at https://www.atlassian.com/git/tutorials/comparing-workflows .

 

Tip #6 – Commit code with useful comments

When committing code to a repository, developers should include useful comments that make it easy for the them to go back through the repository and understand what is in that version of code. When I create a branch, I name the branch something useful like FEATURE_ADC. When I commit that code or merge the result with the mainline, there are several pieces of information I make sure that I include in my comments log:

• The version number for the software and / or feature
• What changes were made
• Any known issues with that version
• General comments

I will often include a section for each I my comments and fill in each section. For example, in the changes section I will often comment on what I added, removed and updated. In the issues section, I may include notes that I need to add error handling or that testing only covered 50%, or any note that lets me know what additional work I need to do. I may also include any new bugs discovered that I did not fix in that commit. Finally, I may leave general comments about the code such as the need to update documentation, an idea for an improvement and so forth.

Comments can be extremely useful to identify what is in that version, but they can also be useful to review after lunch to remember where you left off and what needs to be tackled next in the software.

 

Tip #7 – Identify a good reference manual

The last tip for today is that every developer needs a good Git reference. For the most part, it’s easy to just perform a search in your favorite search engine to figure out what the command was to initialize a submodule or to stash your current changes or rebase to the current mainline. For whatever reason, I also still like to keep a physical reference around in book form sometimes. I’ve found that while I can find something on the internet pretty fast, a good book works just as well and gives my eyes a break from staring at a screen. For Git, I’ve found that Jon Loeliger and Matthew McCullough’s “Version Control with Git” to be a good reference and also a good book for beginners to glean some in depth understanding on how to setup and use their Git repositories. I suspect most developers just search the web as needed but since Git performs such an important task for developers, we really should all be digging deeper.

 

Conclusions

Every developer today should be using a revision control system. Git is the most popular and it certainly is not difficult to get started. Some of the nuances can certainly be challenging for newbies. In today’s post, we’ve explored a few simple tips for getting started that should help the reader get up to speed quickly.