Advanced
Overview
This strategy enables repositories to be built or rebuilt from stored code-only snapshots captured at release boundaries.
Code-Only Snapshot A copy of a database taken at a release boundary with application data purged. It represents the complete application code state at that point in time and can be used to reconstruct a repository deterministically.
Unlike the Incremental strategy, which updates an existing repository following each release, this strategy allows a repository to be reconstructed from historical snapshots, producing a clean, release-aligned commit history. For early adopters, this approach was necessary because changes to the JadeGit repository extract format could be applied retrospectively, mitigating the impact of breaking changes.
This strategy is most valuable when teams have a collection of snapshots available and want to:
Rebuild repositories with complete, release-aligned history.
Preserve traceability of past releases.
Establish a clean repository baseline without relying solely on incremental extracts.
While highly flexible, it requires greater operational discipline and careful automation than the Fundamental or Incremental strategies.
When to Use
This strategy is appropriate when:
Release-boundary snapshots are available (from production or staging environments).
A deterministic, release-aligned commit history is required.
The repository may need to be reconstructed due to changes in the repository extract format.
The team has the operational maturity to manage automated migration pipelines, which may temporarily disrupt active development when the main branch is rewritten.
It is not recommended for new adopters without any snapshot history, as simpler strategies are sufficient for initial adoption. However, new adopters are encouraged to review the examples provided, as certain advanced aspects may still be relevant when using simpler strategies.
This strategy is best suited to teams treating repository history as a long-term asset rather than a simple deployment mechanism.
Approach
Snapshot Capture Retain a code-only snapshot at each release boundary. These snapshots serve as authoritative rebuild points. For each release, an initial snapshot may be taken from a staging database during release preparation and later replaced with a production snapshot taken post-release.
Trigger Migration Pipeline After new snapshots have been captured, the repository can be reconstructed. Due to the complexity and potential impact of this process, it should be automated using a manually triggered pipeline. The pipeline should begin by cloning the existing repository, ready for isolated reconstruction.
Migration Branch Reset Before replaying snapshots, switch to and reset the migration branch to the initial commit. If the migration branch does not already exist, create it from the repository’s initial commit on the main branch. This ensures a clean starting point for the rebuild.
Sequential Snapshot Replay For each snapshot in chronological order:
Identify any original commits in the main branch corresponding to the snapshot to preserve entity identifiers. This can be achieved using a snapshot index containing a unique description per release. That description is used as the commit message during extraction, allowing the commit to be located at this stage.
Extract the snapshot, specifying the original commit if it is found in the main branch. If no changes are detected throughout the rebuild, original commits are preserved without modification.
Initialize Registry After the last snapshot has been extracted, re-initialize the registry to match the reconstructed repository. If a new commit has been created, the updated registry must be applied to production (or equivalent). If the last snapshot replayed was taken from a staging database, it may be included in the pending release.
Remote Push Once all snapshots have been replayed and the migration branch reflects the reconstructed history, this needs to be pushed to the remote repository where it can be reviewed.
Review and Promotion After the migration branch has been updated:
Review the migration branch for correctness.
If approved, update the main branch to match the migration branch. This step can be automated with the use of a pipeline that is triggered manually following review.
Transition Handling As with the Incremental strategy, changes may continue to be double-handled during the transition period (with the help of patch extracts) until JadeGit is fully adopted as the authoritative source for ongoing development. Beyond full adoption, new snapshots are no longer required, as the repository will not need to be rebuilt.
Advantages
Deterministic rebuild of the repository from known snapshots.
Produces a clean, release-aligned commit history.
Preserves traceability across releases.
Supports reconstruction without relying solely on incremental extracts.
Enables retrospective application of repository extract format changes across historical releases.
Disadvantages
Highest operational complexity among the three strategies, with potential for temporary disruption to active feature branches.
Requires disciplined snapshot capture and storage.
Increased operational coordination and automation overhead.
Not necessary if snapshot history does not exist.
Last updated