Git Version Control

info

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

You should know

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:

1. 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.
2. Delete the conflict markers.
3. Commit your changes.

Syncing with External Repository

info

💡 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

info

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

What is the differences between git revert and git reset?

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” than git 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.