Git an Arduino IDE workflow – The new stack

Dr. Torq

Rob (drtorq) Reilly is a freelance consultant, writer, and speaker specializing in Linux/OSS, physical computing, hardware hacking, tech media, and the DIY/Maker movement.

Even small microcontroller projects require multiple iterations of code as the project progresses. In the past, I’ve simply used consecutive numbers attached to filenames to mark each latest version of Arduino code. Although doable, it’s clunky and not so easy to manage. Despite fairly modest and simplistic file sizes, tracking changes using the Arduino IDE is confusing and time consuming.

A typical Arduino-based project uses source code files that are converted to binary format for uploading (as firmware) to an Arduino microcontroller.

Traditional Arduino modules, such as the Nano, have rather modest firmware storage capacities and can only handle the fairly simple tasks of reading inputs, performing calculations, and setting certain outputs. Newer Arduino-compatible microcontrollers, like the ESP32, have much larger program spaces and can accommodate much larger and more complicated applications.

Priced at around $8 each, the ESP-32 also has built-in WiFi and Bluetooth capability. Add to that a small 320×240 color LCD screen and you have the makings of a compact and interesting sensor display platform.

I am working on the combination of a GPS module together with the ESP-32 and LCD display with a 3D printed case to create a small clock that never needs to be reset. It will get the time from all GPS satellites floating above your head. WiFi and BT give it future UI and possible MQTT functionality.

Today we are going to see how to use the git version control system to manage the code of an Arduino IDE workflow.

The Arduino IDE method

I approach my projects in phases. Communicate the microcontroller with the IDE (interactive development environment) in a single phase. Connect the microcontroller to the LCD in another. A third phase could be sending data from the GPS module to the microcontroller. You had the idea.

Often I learn to use a new sensor or output device in a project. Each iteration builds on individual components and code modules until we have a complete system. Completing each phase maintains motivation and resolves all issues. Building even simple hardware has surprising complexity.

Putting a project under git packs everything into a convenient package layout. In the past, I’d sometimes save a new version to a default directory, then come back later and wonder where it was going when I couldn’t find it. With half a dozen projects running simultaneously, it’s easy to get caught up in time-wasting file-finding expeditions.

Project Setup

My initial vision for my own project is an Arduino-like microcontroller, with a small color LCD screen, that reads data from a GPS module and displays the current local time. Since we’re talking about workflows, the project-specific technical details won’t be as in-depth as usual.

This project uses a common system ESP32 modulea 320×240 color TFT LCD displaya breadboard and a simple 2600mAh Power Stick which was bundled into a recently purchased JeVois Smart Vision Sensor Set.

Programming is done via USB connection to the trusty old Dell Core-i7 laptop running Xubuntu 20.04.4 LTS. I’m also using the Arduino IDE, version 1.8.13.

All Arduino firmware source code files reside in a named directory. When saving a new file, the Arduino IDE automatically generates a software directory, which reflects the name of the source file. I switched the Arduino IDE sketchbook directory under the Preferences tab to group all new source directories by default. It is also important to bring all libraries into the consolidation directory, so that the Arduino IDE can access them when compiling.

Most Arduino libraries provide sample filesets that illustrate the use of features. I opened a sample program, in the Arduino IDE, from the TFT_eSPI library called TFT_Print_Test. It displays a randomly colored background with multiple lines of text of varying fonts and sizes. This is a program of a few dozen lines that is easy to follow and modify for demonstration. Here is a graph of the display.

Bare-bones esp32/color LCD breadboard displaying text

Bare-bones esp32/color LCD breadboard displaying text

The Arduino files directory was configured with the following in a Xubuntu text terminal.

drtorq% cd /home/rob
drtorq% mkdir esp32-lcd
drtorq% cd mkdir esp32-lcd

Returning to the IDE, the sample file was saved in TFT_Print_Test.ino. The IDE automatically generated a TFT_Print_Test directory under /home/rob/esp32-lcd phone book.

Here is a code segment of the file after the first save in the IDE.

Arduino original file esp32-lcd

Arduino original file esp32-lcd

Then I went back to the text terminal to configure the git instance.

drtorq% git init
drtorq% ls (to remind me of the esp32-lcd directory name, which is “TFT_Print_Test”)
drtorq% git add TFT_Print_Test
drtorq% git commit -m "initialized the esp32-lcd basic project code under git control"
drtorq% git status

Initial git status

Initial git status

As you can see, we now only track ESP-LCD project files and not libraries. You could just as well put the library files into git, with a ‘git add *‘ ordered. In some cases this may be desirable, such as for custom configuration files. I chose not to for simplicity in this case. Additionally, git tracks all files at the directory level. So anything added or updated in the TFT_Print_Test directory, under /home/rob/esp32-lcd directory is tracked with git.

Add new feature with new branch

With the base code indexed in git, it’s simple to set up a base branch in git, for later use. To do this, we need to know the git commit reference number. Use the git log command.

drtorq% git log

Initial git log showing the commit number of the original Arduino file

Initial git log showing the commit number of the original Arduino file

Here we’ll see quite a few, above the author line, labeled “validate”. The latest commits are at the top. Copy this number to your Linux terminal’s clipboard using vs.

We want to create a new branch, so this is easily done with the traditional git checkout command.

Then paste the commit number in git checkout with the -b option and the branch name. In this case, I used “orig-state” for the name. Use a v on the command line to paste the number.

drtorq% git checkout -b orig-state [commit number]

Now make a git status and you will find that you are on the new original state branch. Quit the Arduino IDE. Don’t change anything and just go back to the main branch with another git payment.

drtorq% git status
drtorq% git checkout master

In fact, most users will probably want to use the new git switch command to switch between branches. It does the same thing as payment, it’s just newer, easier to remember, and there are fewer characters to type. Here is an example.

drtorq% git switch master

I added some comments to the file, saved it, then quit the Arduino IDE, then did the usual git add and git commit. If you git go back to original state branch, you will see the original “Hello, World” text when you open the Arduino IDE. Exit the IDE, switch git to master, then restart the IDE. The latest major changes will be displayed in the IDE.

Check out the latest version of the main branch of the file.

code segment showing master branch version

code segment showing master branch version

You can now modify your code (on the master branch) for new functionality knowing that the initial file is safely indexed in the orig-state branch.

It is important to save and close the source file in the Arduino IDE before each commit. git handles all the versioning magic.


We discussed how to get started using git with the Arduino interactive development environment. Remember to set your directories correctly, then save and check out files before doing a git add and git commits. Switch to the branch of your choice. Then reopen the file to get the chosen version.

Contact Rob “drtorq” Reilly for consultations, speaking engagements and commissioned projects at [email protected] or 407-718-3274.

The New Stack is a wholly owned subsidiary of Insight Partners, an investor in the following companies mentioned in this article: Torq.

Comments are closed.