Fundamental
Overview
This is the simplest strategy to adopt JadeGit for an existing system, performing a direct migration of existing schemas into a new repository.
It is recommended that developers begin with this strategy when evaluating whether JadeGit will support their existing systems. Understanding the steps below is a prerequisite to more advanced strategies that facilitate piloting new ways of working and a slow transition path.
When to Use
This strategy is appropriate when:
The team is adopting JadeGit for the first time and has no historical snapshot or repository extract history.
A pilot phase is not required prior to full adoption of JadeGit.
Deterministic, release-aligned commit history is not required.
Operational simplicity is important, with minimal overhead and no need for automated migration pipelines.
Teams are primarily focused on current development rather than preserving full release traceability.
It is best suited for new adopters who want a simple, low-friction introduction to source control.
Approach
Setup Repository
If starting from scratch, you can make a new folder and initialize a new bare repository using git init.
In practice, setting up a remote repository in advance using your preferred hosting platform is recommended (GitHub, GitLab, Azure DevOps). If already set up, use git clone --bare to create a local bare repository (JadeGit extracts schemas into bare repositories only).
Reset Branch
If this process may be repeated, and you've got some supporting configuration that needs to be added to the repository (whether that be deployment scripts or pipeline definitions), these can be added upfront in an initial commit, ahead of extracting schemas. Before repeating the extract, the branch can then be reset to the initial commit using the following commands (when the cloned repository is the current working directory), which avoids the need to repeatedly re-add configuration after extracting schemas.
This is particularly useful when repeating extract cycles during initial validation or dry runs of the migration.
Extract Schemas
As the extract can take some time, it's recommended existing schemas be extracted from a backup of production systems (or equivalent), taken immediately after the last production release.
All existing schemas can be extracted using the following commands. The extract command stages changes in-memory until they're committed. Schemas may also be extracted more selectively using a specific regex and/or list of schema names.
To extract all schemas and commit in a single step, which is needed during an automated process, you can use one of the following commands.
This command assumes the current working directory is the repository, and the JadeGit binaries have been copied to the binaries folder for the Jade database from which the extract is being performed.
Alternatively, when running from a different working directory, you can explicitly open the repository before extracting using the open command.
To perform extract in a step-by-step manner manually, schemas can be extracted and then committed using separate commands using the JadeGit shell.
Once schemas have been extracted, the changes staged need to be committed using the commit command.
When repeating an extract, if the prior extract commit is known, use the original commit extract option to preserve previously allocated entity identifiers. This minimises unnecessary differences between extract cycles.
Initialize Registry
Once existing schemas have been added to the repository, the registry can be initialized, as illustrated below.
This creates a registry file, which needs to be loaded into target databases in preparation for deploying later (including production). Code in the target databases must already be in sync with the database from which schemas were extracted.
Remote Push
Once ready, the local repository needs to be pushed to a remote repository developers can clone.
This depends on setting up a new remote repository using your preferred platform (GitHub, GitLab, Azure DevOps). Once created, it can be added to the local repository and then pushed to.
Once pushed, this repository becomes the source of truth for future development.
Advantages
Fastest path to adopting JadeGit for existing systems.
Establishes a single source of truth immediately, with all future development and deployments expected to use the new repository.
Minimal transitional overhead — no parallel processes or repeated extract cycles.
Disadvantages
No parallel transition period — existing processes are effectively replaced immediately.
Limited opportunity to pilot new workflows before full adoption.
Repeating the migration process may be disruptive if issues are discovered after teams have begun working from the new repository.
Higher risk of operational disruption for teams with large change volumes or tightly coupled deployment processes.
May expose entrenched process dependencies abruptly, requiring rapid adaptation.
Last updated