Practical Git branch management with worktrees in embedded and FPGA development

It is common to work on multiple branches simultaneously in an embedded and FPGA development process. New features are developed while bugs must be fixed in stable versions, requiring frequent context switching. Traditional approaches such as git checkout, git stash, or cloning the repository multiple times introduce inefficiencies, especially in projects with long build times and multiple hardware configurations.

Git worktree is a built-in method for managing multiple working directories from the same repository, allowing developers to check out multiple branches at the same time without affecting their primary working tree.

What is Git worktree?

Git worktree allows a single repository to have multiple working directories (i.e. worktrees) attached to it. Each worktree can have a different branch checked out, but all share the same .git repository metadata.

Every repository has one main worktree, which is created during git init or git clone. Worktrees, called linked worktrees, can be created using git worktree add. These worktrees allow developers to work on multiple branches simultaneously without needing to switch between them in the same directory.

Creating and managing Git worktrees

To create a new worktree:

git worktree add ../my_bugfix-branch my_bugfix        

This creates a new linked worktree at ../my_bugfix-branch, where the my_bugfix branch is checked out. The original working directory remains unchanged, making it easy to work on multiple branches at once. If a branch does not already exist, Git worktree can automatically create one:

git worktree add ../my_feature-x        

This command creates a new branch my_feature-x and checks it out in the ../my_feature-x directory. A worktree can also be created without a branch, using a detached HEAD for experimental changes:

git worktree add -d ../test-environment        

This allows changes to be tested without affecting any existing branches. To remove a worktree run the command:

git worktree remove ../my_bugfix-branch        

This detaches the worktree from the repository. If the worktree directory is deleted manually, Git will eventually remove the associated metadata, or it can be cleaned up with:

git worktree prune        

To list all active worktrees and get an overview of all linked worktrees and their branches we use the command list:

git worktree list        

Challenges with traditional methods

Branch switching

Switching branches using git checkout or git switch requires a clean working directory, meaning that any ongoing work must either be committed, stashed, or discarded before switching. This process can be inefficient when developing, as changing branches often results in long rebuild times due to the need to recompile large codebases. Different branches may also require separate build environments, leading to frequent reconfiguration of dependencies, toolchains, or hardware-specific settings. Interruptions like these can increase development time and make shifting between tasks more challenging.

Git stash

git stash is commonly used to temporarily store work before switching branches. While this allows switching without committing, it has several drawbacks. If the code changes while work is stashed, conflicts may arise when attempting to reapply the stashed changes. Additionally, build artifacts are not preserved, which may result in the need for a full rebuild when returning to the original branch. Managing multiple stashes can also become complicated, especially when handling several tasks at once.

Cloning the repository multiple times

Some tackle branch switching challenges by creating multiple clones of the same repository, with each branch stored in a separate directory. While this approach prevents disruptions when switching branches, it comes with several disadvantages. Each clone consumes significant disk space, as it includes the full repository history. Keeping the clones up to date requires manual synchronisation, often involving frequent git pull operations. Managing multiple clones can also lead to a more complex and disorganised workflow which makes it hard to track ongoing development.

Advantages of Git worktree in embedded and FPGA development

Git worktree simplifies context switching by allowing each branch to be checked out in its own directory. Instead of committing, stashing, or discarding changes to switch tasks, developers can simply move between directories, reducing interruptions and improving workflow efficiency.

In FPGA and embedded development, frequent branch switching often leads to full rebuilds, significantly increasing development time. By using worktrees, multiple branches can exist in separate directories, ensuring that build artifacts remain available and minimising the need for recompilation. This approach also improves parallel development, because a stable branch can remain open for testing while new features are developed in another worktree. Older versions can be quickly checked out for debugging without interfering with ongoing work, and different hardware configurations can be maintained separately to optimise development across multiple targets.

Another benefit of using worktrees is that they provide a structured way to separate simulation and synthesis processes in FPGA development. One worktree can be dedicated to simulation while another handles synthesis, allowing for effective validation without the need to repeatedly switch environments.

Conclusion

For teams working with large codebases, FPGA tools, or embedded firmware, Git worktree offers a structured and efficient way to manage multiple branches without disrupting ongoing work. By allowing each branch to exist in a separate directory, worktrees eliminate the need for temporary commits or stashing and help preserve build artifacts, reducing unnecessary recompilation. In projects with long build times and complex configurations, traditional branch switching can be inefficient and lead to workflow interruptions. Worktrees present a more organised and practical solution than maintaining multiple cloned repositories, making them particularly valuable for handling parallel development in embedded and FPGA projects.

#embedded #fpga #versioncontrol #git #methodology Inventas