Git Version Control
This feature is in beta and currently only available on Holistics 4.0 (Analytics As-Code). Please reach out if you want access to Holistics 4.0.
Introduction
With all of analytics logic being described as code using AML, it is natural to be able to check them into a revision control system such as Git.
With Holistics's Git Integration, your Holistics codebase is now powered by Git. You can track every change, perform code branching, change reviews for a better analytics development workflow.
Benefits:
- Version Control: Track and manage every analytics logic change.
- Isolated Environment: Develop your work in a branch to avoid affecting other people. Deploy only when you're confident.
- Code Review (Merge Request): Have someone else double check your code before deploying to production.
- Code Backup: Back up your analytics logic into a seperate repository for backup purpose.
High-level Mechanism
Behind the scene, Holistics maintains Git repositories to host the code changes. Holistics also exposes a Git-friendly UI interface for users to commit changes and deploy to production.
There are 3 different Git repository concepts with Git Integration:
- System Repository: Git repository that Holistics maintains internally on the server for the analytics code.
- User Repository: Holistics-managed repository for each user.
- External Repository: Repository that sits on customers’ servers or Git providers (like Github or Gitlab)
You can either use Holistics' default repository, or connect to your own external Git repository:
Without External Git repository
With an external Git repository, you can choose between work on your local machine using a text editor of choice (i.e VS Code), and work on Holistics Cloud Editor:
With External Git repository - Work on your local machine
With External Git repository - Work on Holistics Cloud Editor
How it works
From the user's perspective, the workflow follows a simple 3 steps:
- Create branch: User creates a new branch (in their User Repository) to start their development.
- Make changes & commit: User makes their code changes and commit (to User Repository). It is then pushed automatically to System Repository.
- Deploy: Once happy with the changes, user presses deploy to production. Their code will then pushed to System Repository's
master
branch (production branch). Live reports and dashboards are updated with the new code logic.
Development Mode vs Production Mode
Please refer to this document to learn more about the difference between the two modes.
Managing branches for Development Mode
Create branch
To start making changes, you need to create a new branch (in Development mode). You are not allowed to make changes directly to Production environment.
When creating a new branch, you're asked to choose a base branch (aka branch to fork from). If your change is new, you should fork from master (production) branch.
Notes before creating a new branch:
- If you have a merge conflict on your current branch, you must resolve the conflict before you can create a new branch.
- If you have any uncommitted changes on the current branch, you must commit the changes on your current branch before creating a new branch.
Once you're in a new branch, go about making your changes using Holistics's Cloud IDE. Once you're happy with it, commit your changes.
You can make as many commits as you want. Similar to software development, it's recommended that you break your changes into multiple atomic, meaningful commits instead of a big one.
Delete branch
If there are branches that are no longer useful for development and you want to clean up them, you can delete them in branch management
However, do note that even if you delete a branch, if that branch still exists in another repository of another user and he (or she) pushes it back to System repository, it will be once again presented to your branch list.
The reason for this is that you can only delete branches in your user repository and system repository, you will be unable to touch other people's repository.
Deploying to Production (Go Live)
When you are happy with your changes in your development branch, you can deploy them to production. Click on "Deploy to production" on top top right corner of the page.
Changes pushed to Production (master branch) are automatically applied to the Reports, Dashboards (Reporting tab).
In order to deploy to production, your current branch needs to be ahead of the Production branch. If not, you will be asked to Pull changes from Production before proceeding with the deployment.
Resolving Merge Conflicts
A merge conflict arises when two Analysts make changes in the same line in a file, or one Analyst deletes a file but other Analyst makes edits in the same file.
When you pull changes from other branches, there is bound to be merge conflicts. Should this happen, Holistics will use the standard Git syntax conflict markers (Learn more) to display conflicts during merging.
The merge cannot be executed automatically since Git cannot determine what changes to keep so you will have to resolve the conflicts manually.
To resolve a merge conflict, follow these steps:
- Select which changes you want to keep: their branches, your branches or both. If you want to discard a change, simply delete the corresponding code section.
- Delete the conflict markers.
- Commit your changes.
Syncing with External Repository
💡 This feature is not supported yet in the Beta version. It should be supported eventually when Git Integration comes out of Beta.
Holistics supports syncing from System repository into your own external Git repository stored in Github or Gitlab. The syncing will be two ways:
- You can push from System Repository to External Repository for backup and external viewing purpose.
- You can make your own commits to External Repository, and push to System Repository to "deploy production"
Using your own IDE editor: Once support for syncing with External Repository is released, you can use your own code editors (e.g VS Code) to do analytics development on your local environment, and deploy by simply pushing to System Repository.
Reverting to a previous version
The following section is a workaround as Holistics 4.0 does not support revert feature natively. You should preferably have basic Git proficiency before following this guide.
To revert an AML project to a previous version, you will need to go through these steps:
Step 1: Pull the production branch from the remote host to your local machine
Run Git pull
command to pull the code from the production branch to your local machine.
Typically, you will have either master
or main
branch as your production branch.
git pull origin <your_production_branch_name_here>
Step 2: Revert the code to the desired version using Git
First, check Git history to find the SHA-1 hash of the version you would like to revert. You can use Git log
command to do this.
// in your local AML folder
git log
Then, you can use either Git revert
or reset
to revert the code.
git revert $commit_hash OR git reset HEAD~$commit_head
Below are the fundamental differences between the two commands:
git revert $commit_hash
creates a new commit that undoes the changes from$commit_hash
. It does not modify the existing history tree.git reset --hard HEAD~$commit_head
will update your branch to point to the$commit_hash
. It will discard the commits succeeding$commit_hash
.
Because of their differences, we would advise that:
You should use
git revert $commit_hash
if you have found some “bad” commits in your code and want to remove them without affecting other commits.For example, if your working tree looks like this:
commit A -> B -> C -> D
Let’s say the production branch is pointing to commit D. You have decided that commit A is bad. Executing
git revert commit_A
will create another commit to undo the changes made in commit A, while keeping B, C, D intact.You should use
git reset --hard HEAD~$commit_hash
if you want to undo all the changes up to a particular version.For example, if your working tree looks like this:
commit A -> B -> C -> D
Let’s say the production branch is pointing to commit D. You have decided that commit B,C,D is wrong, and you want to reset everything back to commit A. Executing
git reset --hard HEAD~commit_A
will reset the code back to where it was at commit A, and remove B, C, D in the process. Additionally, the HEAD would now be pointed at commit A.We can see that
git reset
is more “dangerous” thangit revert
, and have the potential to remove other people’s works from the project if we aren’t careful. Therefore, please use it responsibly!
Step 3: Push the reverted code back to the remote host
You can use Git push
to publish the changes to your remote production branch.
git push origin <your_production_branch_name_here>
Step 4: In Holistics, pull the new code from the remote host
After you have made changes to your External Repository, the System Repository in Holistics will detect the changes and prompt you to pull the new changes to keep the two repository in sync.
To fetch the new code, click Pull changes from remote to sync the new code to your working repository.