2. Baseline Solver Deck Versioning with Git

Why a Baseline Deck Needs Its Own Version Boundary

A solver deck is the single artifact that most directly determines whether a CAE result can be reproduced. Geometry and mesh may be regenerated, but the deck encodes the physics: material cards, property assignments, boundary conditions, step definitions, solver tolerances, and output requests. When a baseline deck is committed to Git without a deliberate version boundary, later edits silently overwrite the reference state, and any downstream comparison loses its anchor. This case establishes that anchor: initialize a repository, commit the baseline deck as the first tracked model state, and mark it with an annotated tag so the exact deck content can be recovered by name rather than by hunting through commit history.

The task is deliberately narrow. It does not cover large-file handling (that belongs to geometry and mesh workflows), nor does it define the full project skeleton. It assumes a single baseline solver deck file already exists on disk and must become a verifiable, tagged Git object.

Preconditions and the Deck Under Version Control

Before running any Git command, confirm three things. First, the deck file is final for this baseline: no pending edits, no placeholder values. Second, the file is text-based (for example an Abaqus .inp, a CalculiX .inp, or a Nastran .bdf), because line-oriented diffs are what make deck versioning useful. Third, the working directory contains only what should be tracked. A typical starting layout for this case is:

baseline_deck/
├── model_A_baseline_v00.inp
└── README.md

The deck name encodes model variant and revision, consistent with the project naming convention. The revision token v00 signals "baseline, pre-change." Keeping the deck at the repository root for this case keeps the first commit unambiguous; subfolder organization can be layered on later without rewriting history.

Initializing the Repository and Configuring Identity

Initialize Git inside the deck directory so the repository root coincides with the model folder. Commit authorship must be correct from the first commit, because the baseline tag will inherit that metadata and reviewers will use it to trace responsibility.

cd baseline_deck
git init -b main
git config user.name "CAE Analyst"
git config user.email "analyst@example.com"

Using -b main sets the initial branch name explicitly, avoiding the default-branch ambiguity that appears when repositories are created on machines with different Git configurations. The user.name and user.email set here are repository-local; they do not alter global settings. In a shared environment, use the identity associated with the analysis team rather than a personal alias, so the baseline commit remains attributable after handover.

Staging and Inspecting Before the First Commit

The first commit is the most consequential one, so inspect what will be recorded before recording it. Add the deck and the README, then review the staged set and the diff summary.

git add model_A_baseline_v00.inp README.md
git status
git diff --cached --stat

git status should list both files under "Changes to be committed" and nothing under untracked files. git diff --cached --stat should report the deck with a nonzero insertion count — a solver deck of a few thousand lines will show a correspondingly large insertion figure. If the deck appears with zero insertions, the file is likely empty or was matched by an ignore rule; check git check-ignore -v model_A_baseline_v00.inp to confirm.

Committing the Baseline with a Meaningful Message

A commit message for a baseline deck should state what the deck represents, not merely that a file was added. The message is the human-readable half of the version boundary; the tag is the machine-addressable half.

git commit -m "Add baseline solver deck model_A v00

Baseline static analysis deck: 4 material definitions,
12 boundary condition sets, 3 step definitions.
Reference state for all subsequent model_A revisions."

The subject line is imperative and specific. The body records the deck's scope so that a reviewer reading git log months later understands what the baseline contains without opening the file. Avoid messages such as "initial commit" or "update deck" — they carry no information about the model state and defeat the purpose of a baseline.

Tagging the Baseline as an Annotated Reference

A lightweight tag is just a pointer; an annotated tag is a full Git object with its own message, tagger, and date. For a baseline that will be cited in reports and used to reproduce results, the annotated form is the correct choice.

git tag -a baseline-model_A-v00 -m "Frozen baseline deck for model_A, revision v00"

The tag name mirrors the deck's revision token, so the mapping between file name and tag is immediate. Annotated tags are also what git describe uses by default, which matters when later commits need to be expressed as "so many commits after the baseline."

Verifying That the Deck Is Tracked and Tagged

Verification is not optional; it is the acceptance criterion for this case. Three checks together confirm the baseline is properly recorded.

git log --oneline --decorate
git ls-files
git show baseline-model_A-v00 --stat

The first command should show a single commit with the tag decoration (tag: baseline-model_A-v00) on the same line. The second should list model_A_baseline_v00.inp and README.md, confirming both are tracked rather than merely present. The third should display the annotated tag's metadata followed by the commit's file statistics, confirming the tag resolves to the baseline commit and that the deck is part of it.

A fourth, stronger check confirms content integrity: compare the working-tree deck against the committed blob.

git diff --exit-code HEAD -- model_A_baseline_v00.inp

An exit code of 0 with no output means the tracked content matches the working file exactly. Any output indicates uncommitted drift, which must be resolved before the baseline can be trusted.

Failure Symptoms and Their Causes

When the verification steps do not pass, the symptom usually points to a specific cause. The table below maps observable failures to the corrective action.

Baseline Record Card

The following record captures the state established by this case. It is the artifact a reviewer or downstream analyst consults to confirm the baseline exists and is addressable.

With the tag in place, any later revision of the deck can be compared against the baseline by name, and the recovery command restores the exact baseline content into the working tree without disturbing the current branch history. That is the operational meaning of a versioned baseline: a named, immutable reference that survives every subsequent edit.