Version Control Best Practices for Embedded Firmware Teams

By embeddedSoft

Published in Miscellaneous Articles

June 25, 2026

6 min read

Version Control Best Practices for Embedded Firmware Teams

Introduction

Why Version Control Is Non-Negotiable in Embedded

Branching Strategy for Firmware Projects

Commit Message Conventions

Handling Binary and Hardware-Specific Files

Code Review Practices for Firmware

Tagging Releases and Reproducibility

Protecting Your Main Branch

Summary

Introduction

If you have ever inherited a firmware project where the “latest” code lived on someone’s laptop in a folder called firmware_v3_final_REAL_final2.zip, you already understand why version control matters. Embedded firmware development has unique constraints — hardware dependencies, binary artifacts, long-lived release branches, and engineers who may work on different silicon revisions simultaneously. These realities make version control both more challenging and more critical than in pure software projects.

Git is the de facto standard for version control, but using Git effectively for embedded firmware requires deliberate workflow choices. This post covers the practices that separate teams who ship reliably from teams who spend Friday nights hunting regressions introduced by an unnamed commit from three weeks ago.

Why Version Control Is Non-Negotiable in Embedded

Embedded firmware sits at the intersection of hardware and software. A bug in a motor controller or a misconfigured radio register can brick physical devices in the field. Unlike a web application, you cannot simply redeploy a hotfix over the air in every case — many devices have no connectivity, or a failed update can render them unrecoverable.

Version control gives your team three superpowers:

Accountability — Every change has an author, a timestamp, and a message explaining why.
Reproducibility — You can rebuild any past release exactly as it was shipped.
Parallel development — Multiple engineers can work on different features without stepping on each other.

Without these, you are flying blind. Let us look at how to set up a workflow that actually works for embedded teams.

Branching Strategy for Firmware Projects

A good branching strategy balances isolation (letting engineers work independently) with integration (merging work together frequently). For most embedded firmware teams, a simplified version of GitFlow works well:

main (production releases)
  |
  develop (integration branch)
    |
    feature/implement-ble-bonding
    feature/add-ota-support
    bugfix/uart-race-condition
  |
  release/v2.4.0 (stabilization before release)

Key Principles

main is always shippable. Code on main has passed testing and is production-ready. Never commit directly to main.
develop is your integration point. Feature branches merge here first. Run continuous integration (CI) on every merge to develop.
Feature branches are short-lived. Aim for days, not weeks. Long-lived branches create merge conflicts that are painful to resolve, especially when hardware requirements change underneath you.
Release branches exist for stabilization. When develop is ready for release, create a release/vX.Y.Z branch. Only bug fixes and documentation updates go here. Once stable, merge to main and back to develop.

ASCII Diagram: Branch Lifecycle

+-----------+
                       |   main    |
                       +-----------+
                             ^
                             | merge & tag (v2.4.0)
                       +-----+-----+
                       |  release/ |<----------+
                       |  v2.4.0   |           |
                       +--+-----+--+           |
                       ^  |     |              | merge
        branch release |  v     | branch       | bugfix
                       |  merge v bugfix       |
                       |  back +---------------+---+
                       |       | bugfix/uart-dma   |
                       |       | bugfix/ble-timeout|
                       |       +-------------------+
                       |
                       +-----------+
                       |  develop  |<----------+
                       +-----------+           |
                          |  ^                 | merge
           branch feature |  |                 | feature
                          v  |                 |
                       +-----+-------------+   |
                       | feature/ota-      |---+
                       |   support         |
                       | feature/adc-dma-  |
                       |   driver          |
                       +-------------------+

Commit Message Conventions

Good commit messages are a gift to your future self and your teammates. In embedded systems, where a single bit flip in a register configuration can cause weeks of debugging, knowing why a change was made is invaluable.

The Format

<type>(<scope>): <subject>

<body>

<footer>

Types and Scopes

To remain compatible with automated changelog and release notes generators, it is best to stick to standard Conventional Commit types and use embedded-specific classifications as scopes.

Type	Use When
`feat`	New feature or capability
`fix`	Bug fix
`refactor`	Code restructuring without behavior change
`test`	Adding or updating tests
`build`	Build system or CI changes
`docs`	Documentation only

Common Scopes for Embedded Commits:

hw — Hardware-specific changes (pin mapping, schematic fixes)
driver — Peripheral driver modifications (SPI, I2C, UART)
ble / wifi — Wireless protocol configurations
bsp — Board Support Package changes

Examples

feat(ble): add configurable connection interval

Allow runtime configuration of BLE connection interval
to balance power consumption against data throughput.
Default remains 50ms for backward compatibility.

Closes: #142

fix(driver): correct SPI clock divider for STM32H7

The SPI1 clock divider was configured for 48MHz source
but the actual bus clock on H7 is 64MHz. This caused
clock mismatches with the external flash datasheet
maximum of 80MHz.

Tested with: Winbond W25Q128 at 80MHz operation.

Rules for Embedded Commits

One logical change per commit. Do not mix a driver fix with a new feature in the same commit. Bisecting a mixed commit is a nightmare.
Reference issue trackers. Always include Closes: #NN or Refs: #NN so readers can trace the full context.
Mention hardware when relevant. If a fix is specific to a board revision or silicon version, say so: hw(revB): reroute I2C to alternate pins.
Never commit binary inputs directly. Use Git LFS for third-party binary libraries, precompiled protocol blobs, or large test fixtures, and ignore compiler-generated outputs.

Handling Binary and Hardware-Specific Files

Embedded projects have files that do not play well with standard Git text workflows, or represent a risk to repo size:

Compiler build outputs (.bin, .hex, .elf, .map) — these change on every build and should be git-ignored.
Precompiled vendor libraries (.a, .lib) — opaque binary files.
Hardware configuration generator files (.ioc, .mex) — auto-generated source files that produce large diff noise.
IDE/Toolchain workspace files (.uvoptx, .user) — contain absolute local paths and dev-specific settings, causing constant merge conflicts.
Large test fixtures, calibration data, and oscilloscope captures.

Git LFS for Large Files

Git Large File Storage (LFS) replaces large files with lightweight references while storing the actual content on a remote server. This keeps your repository cloneable and fast.

[!WARNING] Do not use version control (even with Git LFS) to store compiler-generated build outputs like locally compiled .bin, .hex, or .elf files. These should be excluded via .gitignore. Instead, configure your CI/CD pipeline to compile release builds and upload them to a dedicated artifact registry (e.g., GitHub Releases, JFrog Artifactory, or AWS S3).

Only use Git LFS for large input dependencies or design files that cannot be generated dynamically:

Vendor-supplied static libraries (.a, .lib)
Precompiled RF protocol stacks (binary blobs)
Calibration tables or board configuration assets
Bootloader binary images embedded in main application builds

Generated Code: Commit or Not?

Tools like STM32CubeMX or NXP’s Config Tools generate initialization code based on graphical configurations.

Always commit the configuration file (e.g., .ioc or .mex). This is the hardware configuration source code.
Committing generated source files (.c, .h) is usually recommended for embedded teams. While it introduces diff noise, running proprietary code-generation tools in a headless Linux CI pipeline is notoriously complex to configure. Committing the generated code guarantees that any developer can clone the repository and build the project immediately without toolchain dependency issues.

Code Review Practices for Firmware

Code review is your last line of defense before code hits real hardware. In embedded systems, reviewers need to look beyond logic and consider hardware implications.

What to Look For

Register access correctness — Are the right bits being set? Is the register address correct for this chip revision?
Interrupt safety — Are shared variables accessed from both ISR and task context protected? Are critical sections properly scoped?
Resource leaks — Are DMA channels released? Are timers stopped when no longer needed? Is memory freed in error paths?
Timing assumptions — Does the code depend on a specific clock frequency? Will it break if the clock tree changes?
Error handling — Are return codes checked? What happens when a peripheral returns an error?

Review Workflow

+------------------+      +------------------+
|    Developer     |      |     Reviewer     |
|                  |      |                  |
|  Writes Code &   |----->|   Reviews for:   |
|  Opens Pull Req. |      |   - Safety & ISRs|
+------------------+      |   - HW Registers |
                          |   - Leaks & Time |
                          +--------+---------+
                                   |
                                   v
                          +--------+---------+      +------------------+
                          |    Approved?     |----->|      CI/CD       |
                          +--------+---------+      |                  |
                                   | Yes            | Runs:            |
                                   v                | - Build          |
                          +--------+---------+      | - Unit Tests     |
                          |  Merge to develop|      | - Static Check   |
                          +------------------+      +--------+---------+
                                                             |
                                                             v
                                                    +--------+---------+
                                                    |  Report Status   |
                                                    +------------------+

Review Culture

Be specific. “This looks wrong” is not helpful. “This register write sets bit 7, but the reference manual says bit 7 is reserved on Rev B silicon” is actionable.
Respect the author’s constraints. Sometimes a seemingly suboptimal approach is required by hardware timing or memory limitations. Ask why before demanding changes.
Review promptly. In embedded development, a blocked developer may be unable to test on hardware until the review is complete. Hours matter, not days.

Tagging Releases and Reproducibility

Every production firmware release should be tagged in Git. This creates a permanent reference point that allows you to rebuild the exact binary that shipped to customers.

Semantic Versioning

v<major>.<minor>.<patch>

In embedded firmware, Semantic Versioning should account for hardware and protocol compatibility:

Major — Breaking changes. This includes hardware layout changes (e.g., firmware no longer supports PCB Rev A), non-backward-compatible flash memory or NVS layout changes that break OTA updates, or modifications to external communication interfaces (e.g., CAN database / DBC edits).
Minor — Backward-compatible new features (e.g., adding support for a new peripheral while maintaining the existing API).
Patch — Backward-compatible bug fixes.

# Tag a release
git tag -a v2.4.0 -m "Release v2.4.0: BLE 5.0 support, OTA improvements"

# Push tags to remote
git push origin --tags

Reproducible Builds and Post-Mortem Debugging

A git tag is only useful if you can actually rebuild the same binary or debug it when field errors occur. Document and lock your build environment:

Compiler version (e.g., arm-none-eabi-gcc 13.2.rel1)
Library versions (e.g., HAL driver 1.27.1)
Build flags (optimization level, linker script version)

Store this information in a VERSION file or as part of your CI pipeline output. Many teams use containerized build environments (such as Docker) to guarantee identical toolchains across developer machines and CI runners.

[!IMPORTANT] Archive your .elf files. Always store the compiled .elf (Executable and Linkable Format) file corresponding to every released tag in a secure, long-term archive. The .elf file contains the debug symbols (DWARF) needed to resolve stack traces and memory addresses (using addr2line or GDB) from crash dumps reported in the field. A .bin or .hex file does not contain symbols and is useless for post-mortem debugging.

Protecting Your Main Branch

On a firmware team, a broken main branch can halt production. Protect it:

Require pull requests — No direct pushes to main or develop.
Require CI to pass — The build must succeed, unit tests must pass, and static analysis must be clean.
Require at least one approval — A second pair of eyes on every change.
Require up-to-date branches — PRs must be rebased on the target branch before merging.

Most Git hosting platforms (GitHub, GitLab, Bitbucket) support these protections natively. Enable them.

Summary

Version control is not just a backup system — it is the backbone of collaborative embedded firmware development. The key practices covered in this post:

Use a clear branching strategy that keeps main stable and gives engineers isolated feature branches.
Write meaningful commit messages that explain the “why” behind changes, especially when hardware is involved.
Handle binary files with Git LFS and make deliberate decisions about generated code.
Review code with hardware awareness — logic correctness is necessary but not sufficient when real peripherals are involved.
Tag every release and document your build environment for reproducibility.
Protect your main branch with CI gates and required reviews.

These practices compound over time. A well-maintained Git history becomes your team’s most valuable debugging tool, your audit trail for regulatory compliance, and your safety net when things go wrong in the field.