Version Control for Financial Models
Executive Summary
Key Takeaways
- ✓ Version control for financial models ensures that each version is uniquely identifiable, all material changes are recorded, and previous versions can be recovered.
- ✓ An adequate version control system comprises a file naming convention, an in-model version identifier, a change log, a version archive, and a sign-off record for decision-critical versions.
- ✓ The ICAEW Financial Modelling Code, the FAST Standard, and the Federal Reserve's SR 11-7 all require version control as a core component of model governance.
- ✓ Common failures include using "FINAL" in file names, overwriting previous versions, and maintaining the change log separately from the model.
- ✓ In project finance, lenders require version control records to confirm that the financial close model is consistent with the credit approval model or that differences have been disclosed and re-approved.
Institutional Definition¶
Version control for financial models is the systematic practice of identifying, recording, and preserving successive states of a model as it evolves over its lifecycle. Without version control, it is impossible to determine which version of a model was used for a specific decision, who made a specific change, when that change was made, or what the model looked like before the change.
What Is Version Control for Financial Models?¶
Version control for a financial model is a protocol that ensures:
- Each distinct state of the model has a unique identifier (version number or date stamp)
- All material changes are recorded with the date, the author, and the nature of the change
- The current version of the model can be unambiguously identified
- Previous versions are preserved and accessible
Unlike software version control systems (Git, SVN, Mercurial), which track changes at the line level and support branching and merging, financial model version control is typically simpler in implementation: it combines a file naming convention, an in-model change log, and an archive of model files.
Why Version Control Matters¶
Decision Attribution¶
When a financial decision is made in reliance on a model, it must be possible to identify exactly which version of the model was used and what inputs it contained. Without version control, the model used for a decision cannot be definitively identified from among multiple versions that may have been produced during the same project.
If a dispute arises about the assumptions used for a lending decision, the question "what did the model say at the time of credit approval?" can only be answered if the version used at approval has been preserved and is identifiable.
Change Tracking¶
Version control records who changed the model, when, and why. This creates accountability and enables the model's evolution to be understood. Without a change log, changes that introduced errors cannot be traced, and the model's current state cannot be explained in terms of its history.
Error Detection and Recovery¶
When an error is discovered in a current model, version control allows recovery to the last known-good state and provides a log of changes that can be examined to determine when the error was introduced and why. Without version control, correcting an error may require rebuilding the affected sections from scratch.
Regulatory and Legal Defensibility¶
In regulated contexts, model version control is a component of the model risk management framework required by prudential regulators. In legal contexts, a documented version history establishes the provenance of the model and the timeline of its development, which may be material in a dispute about model outputs or assumptions.
Multi-Party Model Management¶
Financial models in project finance, M&A, and infrastructure transactions are often shared between multiple parties (developer, lender, technical adviser, and model auditor) who may each submit revised versions. Version control allows all parties to identify which version they are working from and to understand the differences between versions.
Components of an Adequate Version Control System¶
1. File Naming Convention¶
The model file name should include a version identifier that allows any file to be unambiguously placed in the version sequence. Common conventions include:
- Date-based:
ProjectX_FinancialModel_20250115.xlsx— identifies the file by its creation or release date - Version number:
ProjectX_FinancialModel_v3.2.xlsx— identifies the file by a sequential version number - Combined:
ProjectX_FinancialModel_v3.2_20250115.xlsx— combines both for maximum clarity
The file naming convention should be applied consistently across all versions of the model and should not include descriptive modifiers that may become misleading (for example, _FINAL suffixes on files that are subsequently revised).
2. In-Model Version Identifier¶
The current version identifier should appear within the model itself, typically on the Cover or Read Me worksheet. This is the authoritative identifier for the model and takes precedence over the file name in the event of a discrepancy.
The in-model version identifier should include: the version number or date, the name of the model, the name of the project or transaction, and the date of the last material change.
3. Change Log¶
The change log is a record of all material changes to the model, maintained within the model file (typically on a dedicated Change Log worksheet or a section of the Cover worksheet).
Each entry in the change log should record: - The version number or date of the change - The person who made the change - The date the change was made - A description of the change (what was changed and why) - The version from which this version was derived (the prior version)
The change log should be maintained in reverse chronological order (most recent change at the top).
Minimum standard for material changes: any change that affects the model's key outputs (IRR, DSCR, NPV, returns) or that modifies the model's structural design must be recorded in the change log. Minor formatting changes and typographic corrections need not be individually recorded.
4. Version Archive¶
Previous versions of the model should be archived in a defined location (a folder or version control system) and should not be overwritten when a new version is created. The archive allows any previous version to be recovered.
The archive structure should mirror the version naming convention: archived versions should be stored in a location where they can be found by version number or date without ambiguity.
5. Version Sign-Off¶
For models used in institutional decisions (lending, investment, regulatory), each significant version should have a documented sign-off confirming that the version has been reviewed and approved for its intended use. The sign-off record should identify the person who approved the version and the date of approval.
Version Naming Conventions¶
Semantic Versioning for Financial Models¶
Adapted from software engineering, a semantic versioning approach uses a three-part version number: MAJOR.MINOR.PATCH
- MAJOR increments when the model's fundamental structure or scope changes (a new asset class is added, the transaction structure changes)
- MINOR increments when assumptions or calculations are materially updated (new deal terms, updated market assumptions)
- PATCH increments when minor corrections are made that do not affect the model's outputs materially (formatting fixes, clarification of cell labels)
Date-Based Versioning¶
Date-based versioning uses the release date as the version identifier: YYYYMMDD. This is simpler than semantic versioning and is unambiguous but does not convey the materiality of a change.
A hybrid approach (major version number plus release date) provides the benefits of both: v3_20250115 unambiguously identifies the third major version, released on 15 January 2025.
Implementing Version Control in the Absence of a Formal System¶
Most Excel-based financial models do not have access to a formal version control system (such as Git) that tracks changes automatically. In this context, version control relies on manual discipline:
Before making any change, save a copy of the current version to the archive folder with the current version number in the file name.
After making any material change, update the in-model version identifier and add an entry to the change log.
At each submission milestone, save a version-tagged copy of the model to the archive and record the submission in the change log.
At each decision point (financial close, investment committee approval, board sign-off), save a version-tagged copy to a designated milestone archive and document the approval.
Common Mistakes¶
| Common Mistake | Why It Matters |
|---|---|
| Using "FINAL" in file names | A model named _FINAL that is subsequently revised produces a _FINAL_v2 or _FINAL_AMENDED file, creating an ambiguous version sequence that is difficult to trace. |
| Overwriting previous versions | Saving a revised model to the same file name as the previous version destroys the ability to recover the previous version. The previous version should always be archived before the new version is saved. |
| Maintaining the change log separately from the model | A change log maintained in a separate Word document or email thread may become separated from the model, making the version history inaccessible when the model is transferred to another party. |
| Recording only approved changes and not all material changes | Changes that were made but subsequently revised should still be recorded in the change log. A change log that records only the "clean" version of the model's history is misleading. |
| Not updating the in-model version identifier when the file is renamed | The in-model identifier and the file name should always be consistent. A mismatch between them (which may arise if the file is renamed without updating the identifier) makes the model's version ambiguous. |
How Version Control Is Assessed in Audits¶
When a model is submitted for independent audit, the auditor assesses the version control record as part of the governance review.
Version identification check. The auditor confirms that the model contains a clear, current version identifier on its Cover or Read Me worksheet.
Change log completeness check. The auditor reviews the change log to assess whether it covers the model's history at the level of detail appropriate for the transaction. For a model with a long development history, the change log should record all material assumption changes and structural revisions.
Consistency check. The auditor verifies that the in-model version identifier is consistent with the file name and with the version referenced in the submission cover letter.
Archive availability check. For transactions where prior model versions are material (for example, where a lender or investor must confirm that the model has not been materially revised since a previous audit), the auditor may request access to prior archived versions.
Regulatory and Industry Context
ICAEW Financial Modelling Code. The Code requires that models be accompanied by a version history and that material changes be documented. The Code identifies version control as a core component of model governance.
FAST Standard. The FAST Standard includes a version control requirement as a structural component of a FAST-compliant model. FAST-compliant models include an in-model version identifier and a documented change log.
Federal Reserve SR 11-7. The Federal Reserve's guidance on model risk management requires that regulated financial institutions maintain version control for models used in material decisions. This guidance is primarily directed at statistical and capital models but its version control principles are widely applied to financial planning and transaction models within regulated entities.
Project finance lender requirements. In project finance contexts, lenders typically require that the model submitted for pre-financial-close audit be the same version as the model submitted for credit approval, or that any differences between versions be documented and reconciled. A model without a clear version history cannot satisfy this requirement.
Worked Example
Scenario. A project finance developer submits a model for lender review at financial close. The model is named ProjectSolar_FinancialModel_FINAL_v2_Revised_March.xlsx. The Cover worksheet shows no version identifier. The model contains no change log.
Audit findings. The auditor cannot determine: when this version of the model was produced, whether it is the same version as was submitted for credit approval, what changes have been made since the credit approval submission, or whether any previous versions have been preserved.
Impact. The lender's credit committee approved the project based on a model submitted four months prior. Without version control, the auditor cannot confirm that the financial close model reflects the same key metrics as the credit approval model, or quantify the differences if it does not.
Resolution. The developer provides email records showing when each model version was distributed, from which a retrospective change log is constructed. The audit identifies two material changes between the credit approval version and the financial close version: a revised gearing ratio and an updated O&M cost assumption. Both changes reduced the DSCR. The lender requires a credit committee re-approval before proceeding to financial close.
Lesson. Had version control been maintained from the outset, the two material changes would have been identified and disclosed proactively, allowing the credit committee re-approval to be obtained as part of the planned financial close timeline rather than as an unplanned delay.
Further Reading¶
- ICAEW, Financial Modelling Code, Institute of Chartered Accountants in England and Wales
- FAST Standard Organisation, FAST Standard for Financial Modelling
- Federal Reserve, SR 11-7: Guidance on Model Risk Management, Board of Governors of the Federal Reserve System
Continue Reading¶
Prerequisites¶
- Financial Model Governance — the parent pillar
Related Technical Guides¶
- Model Documentation Standards — the documentation requirements that complement version control
- Spreadsheet Engineering — the broader engineering approach within which version control is one component
Related Glossary¶
- Audit Trail — the broader audit trail concept of which version history is a component
- FAST Standard — the standard that includes version control as a structural requirement
Related Checklists¶
- Model Handover Checklist — the checklist for model transfers that includes version control requirements
Related Products¶
- Financial Model Audit Engine (FMAE) — deterministic structural auditing referenced throughout this guide
How OXXON tests thisRun a free structural check with FMAE
Frequently Asked Questions
Is Git or another software version control system appropriate for financial models?
Git and similar systems can be used for financial models, but they are primarily designed for text files (code) rather than binary files (Excel workbooks). Binary file versioning in Git does not allow meaningful diff comparison of formula changes. Specialised tools for Excel version control exist but are not widely adopted. For most institutional purposes, manual file archiving with a disciplined naming convention and an in-model change log provides adequate version control.
How long should archived model versions be retained?
This depends on the model's use and the relevant regulatory or contractual requirements. For project finance models, archived versions should be retained for the life of the loan plus any applicable dispute limitation period. For investment models, versions used for investment decisions should be retained for the duration of the investment and the applicable regulatory retention period.
Should every minor formatting change be recorded in the change log?
No. The change log should record material changes: those that affect the model's outputs, structure, or scope. Minor formatting changes, label corrections, and typographic fixes that do not affect calculations or outputs need not be individually recorded, though they may be noted in a summary entry.
What is the difference between version control and model documentation?
Version control manages the model's history over time — the sequence of versions, the changes between them, and the ability to recover previous states. Model documentation describes the model's current state — its assumptions, structure, and limitations. Both are required for institutional-grade model governance but they serve different functions.
Related Articles
Model Documentation Standards for Financial Models
Model documentation standards define what written records must accompany an institutional financial model to enable its outputs to be understood, verified, and relied upon by parties other than its original developer. The minimum documentation package for an institutional financial model includes an assumption log recording the source and rationale for every input, a version history recording all material changes, a model map describing the structure and purpose of each worksheet, instructions for use, and a disclosure of known limitations. The ICAEW Financial Modelling Code and the FAST Standard both establish specific documentation requirements that define institutional expectations.
Spreadsheet Engineering
Spreadsheet engineering is the application of systematic engineering principles to the construction and maintenance of spreadsheet-based financial models. It treats a financial model as a software artefact subject to design principles, structural requirements, and quality standards analogous to those applied in software engineering, rather than as an ad hoc calculation tool built without formal discipline. The core principles of spreadsheet engineering are: separation of inputs, calculations, and outputs; consistent formula construction; avoidance of circular dependencies; complete documentation; and systematic version control. These principles are codified in recognised standards including the ICAEW Financial Modelling Code and the FAST Standard.
Real Estate Financial Modelling
Real estate financial modelling spans two structurally distinct disciplines: development appraisals, built forward from land and construction cost through phased sales or leasing velocity to a gross development value, and income-producing asset models, built from stabilised net operating income to an exit value using direct capitalization or a discounted cash flow. This page is the hub for the Knowledge Centre's real estate modelling content: the two model families, how gross development value and residual land value are built, waterfall and promote mechanics, and how each major property type — residential, office, retail, industrial and logistics — specializes the base structure to its own revenue drivers.