31.8. Version Control with Git

Table of Contents

Why Use Git for Geant4 Applications

Geant4 applications tend to grow from a few files into complex projects that evolve over long periods and are often shared among collaborators. Using a version control system is the simplest way to keep track of changes, recover from mistakes, and collaborate safely. Git is the de facto standard tool for this purpose in scientific computing.

With Git you can record snapshots of your code, move backward to earlier states, work on multiple ideas in parallel, and synchronize your work between machines and collaborators. For Geant4 projects this is especially valuable because you will frequently change geometry, physics lists, analysis code, and macro configurations while exploring different designs.

Always put your Geant4 project under version control before you start serious development. Do not rely on copying directories with timestamps as a replacement for Git.

Initial Git Setup for a Geant4 Project

The best moment to introduce Git is when you create the project structure, before adding complex code. In a typical Geant4 project you will have at least src, include, CMakeLists.txt and one or more macro directories such as macros or run.

To start version control, first create or move into the top-level project directory, then initialize Git and make an initial commit that captures a known good baseline that compiles and runs a trivial case.

Although Git itself is language agnostic, a small amount of C++ awareness helps. For example, you should track your .cc, .hh, and CMakeLists.txt files, but never track build artifacts such as object files or binaries.

A minimal but effective workflow for a brand new Geant4 project is:

Create the project skeleton and ensure that it configures and builds once.
Initialize the repository and add only source, headers, CMake files, macro files, and documentation.
Commit with a clear message that describes the initial state, such as “Initial Geant4 skeleton: detector, physics, actions, CMake”.

Do not commit code that does not compile for your initial baseline. Your first commit should be a working, minimal Geant4 application that you can always return to.

Ignoring Build and Geant4 Generated Files

A central part of using Git productively is the .gitignore file. This file tells Git which files and directories it should not track. For Geant4 applications, ignoring build and generated files prevents unnecessary noise, large commits, and merge conflicts.

At a minimum, you should ignore the build directory. Many developers create a subdirectory called build inside the project, and some keep multiple build directories for different configurations, for example build-debug and build-release. All of these should be excluded from version control.

You should also ignore common CMake and compiler outputs, such as CMakeCache.txt, CMakeFiles, compiled binaries, shared libraries, and intermediate object files. This avoids committing machine specific artifacts that can differ between operating systems, compilers, and Geant4 installations.

If your Geant4 application writes output data files into a subdirectory, for example output or results, these should also be ignored unless you explicitly want to store a small, curated set of reference results. Large simulation outputs should be treated as data products and managed outside the code repository.

Geant4 data libraries themselves must not be committed. They are large, versioned separately from your code, and already distributed by the Geant4 project. Track only the configuration logic that points to them through CMake or environment variables.

Never commit build directories, Geant4 data libraries, or large simulation output files. Use .gitignore to keep your repository focused on source code and configuration.

Structuring Commits for Geant4 Development

Good commit structure is especially helpful in Geant4 projects, where geometric, physical, and analysis changes may interact in non-obvious ways. A small, focused commit history lets you answer questions like: “Where did this change in dose distribution come from?” or “When did we alter the shielding thickness?”

Try to keep each commit logically cohesive. For example, one commit might update only the geometry definitions, another might adjust the physics list selection, and a third might modify analysis routines or histograms. Avoid committing unrelated changes together, because this makes it difficult to track the effect of a specific modification on simulation results.

Useful commit messages describe both what you changed and why. For example, a message that says “Increase phantom depth, add extra slices for Bragg peak fine sampling” is much more informative than “update geometry” when you later inspect differences in plots or validation tests.

When you are tuning parameters such as material thicknesses or energy cuts using macro files, commit these macro changes along with the relevant C++ changes that interpret them. That way, you can always reproduce exactly the configuration that produced a given dataset.

Commit code in small, consistent chunks and write messages that explain the motivation, not just the action. This is critical when you later try to understand changes in simulation results.

Branching Strategies for Simulation Work

Branches are a powerful way to experiment with new ideas in a Geant4 application without risking a broken main line of development. For example, you might have one branch where you explore a new detector geometry, another where you test an alternative physics list, and a third where you rework analysis.

A simple and effective strategy for small projects is to keep one main branch that always compiles and passes basic validation tests, and to create feature branches for specific tasks. Typical feature branches in a Geant4 context could include geometry-upgrade, hadronic-physics-study, or root-output-refactor.

When you conduct physics studies that require multiple scenarios, branching can help keep them clearly separated. You might create distinct branches for each shielding material or for different detector concepts. Once you decide on a specific configuration as your baseline, you can merge that branch into the main branch and tag it for reference.

Branches are also a good tool when you need to maintain stability while updating to a new Geant4 release. You can keep your stable code on one branch and perform the upgrade work on another, testing and adjusting until everything works, then merge back when ready.

Avoid doing large, risky experiments directly on your main branch. Use feature branches for geometry changes, physics list tests, and major refactoring so that you can always return to a known good baseline.

Tagging Versions for Reproducible Studies

Reproducibility is central in scientific simulations. To reproduce a past set of Geant4 results, you must be able to identify the exact version of the code that generated them. Git tags provide a stable label for specific commits that you can refer back to later.

A good practice is to create a tag whenever you generate a set of results that you plan to publish or use in a report. For instance, you might tag a commit as paper1-v1.0 or shielding-study-2026-01 after validating that the geometry, physics list, and analysis chain are correct.

In addition to the tag, document relevant external dependencies, such as the Geant4 version, compiler, and random seed handling, in your repository documentation or as part of the commit message. Git itself will not capture your environment, but the combination of a tag and clear notes lets you reconstruct the setup.

Using tags also helps when you need to rerun a previous scenario after making later changes. You can check out the tagged commit, rebuild, and rerun simulations, secure in the knowledge that you are using the exact same code state as before.

Create a Git tag for every code version that produces results used in publications, theses, or important reports. Use these tags as anchors for reproducible simulations.

Collaborative Workflows with Git

Geant4 projects are often collaborations across groups or institutions. Git supports distributed workflows where each collaborator has their own clone of the repository and contributes through branches and merge requests in a shared remote repository.

When multiple people work on geometry, physics, and analysis code, coordination is essential to avoid conflicting changes. Shared conventions such as naming branches with the feature and the author, and agreeing on which branch represents the stable baseline, help keep the project organized.

Code review is especially useful in Geant4 development. Asking another collaborator to review geometry changes or physics list modifications before merging can catch conceptual errors, such as unintended overlaps, incorrect material assignments, or mismatched production cuts, long before they appear in analysis results.

When collaborating, it is even more important to maintain a clean .gitignore file and to avoid committing large outputs. Different collaborators will each have their own local build directories and data paths, but the shared Git repository should contain only portable, machine independent content.

In collaborative Geant4 projects, agree on a shared workflow: which branch is stable, how to name feature branches, and how to review and merge changes. This prevents subtle physics mistakes from entering the main code base unnoticed.

Tracking Configuration and Macro Files

In Geant4 applications a large part of the simulation behavior is controlled by macro files. These define things like geometry parameters, particle sources, physics list options, and run conditions. Without tracking macro files, you cannot fully reproduce past runs, even if the C++ code is identical.

You should treat macros as first class citizens in version control. Organize them in a dedicated directory and commit them as you would any other source file. When you add a new macro for a specific study, commit it along with any code changes needed to interpret its commands.

It is often useful to distinguish between template macros and run specific macros. Template macros define a general setup, while a run specific macro may specify experiment IDs or data output file names. You may choose to version control the templates and ignore purely transient macros if they are too ephemeral, but be careful not to lose track of configurations that affect physics results.

If you use configuration files or simple text inputs for materials, geometry dimensions, or analysis parameters, these should also be version controlled. They form part of the definition of your simulation and must be available to reproduce or validate results.

Always put the macro files that define physics relevant settings under Git. Without version controlled macros, your simulation configuration is incomplete and hard to reproduce.

Using Git to Aid Debugging and Validation

Git is not only for collaboration. It is also an effective debugging and validation tool. When a change introduces an unexpected effect, such as a disappearing Bragg peak or altered detector efficiency, the ability to compare code between commits becomes invaluable.

By keeping commits small and focused, you can use Git to isolate the exact change that caused a problem. Techniques such as stepping through commits or selectively reverting individual changes can help you locate where geometry, physics, or analysis behavior diverged from expectations.

For simulation validation, you can compare code states between a validated configuration and an experimental configuration. A careful diff can reveal unintended changes, for example modified material densities, incorrect production cuts, or altered histogram binning, which might explain discrepancies with reference data.

Git also gives you the confidence to experiment. Knowing that you can always return to a previous, validated state encourages you to try alternative geometries or physics options that might improve performance or accuracy, without fear of irreversibly damaging your codebase.

Use Git history and diffs when debugging unexplained changes in physics results. Focused commits and clear messages make it much easier to track down the exact modification that altered your simulation behavior.