Concepts

Even if you have little or no experience with Git, we made it very easy to use Git from inside Hackolade Studio, without compromise on the power of Git in more advanced situations. You just need to become familiar with the concepts below.

 

Note: as with any new technology, concepts may be different than what you've been used to with other vendors.  Maybe you are used to doing "checkout" of a data model and lock it so other users cannot make any changes until you "checkin" that model.  Git works differently, so you may need to adjust your habits.  But you'll quickly realize that it is much more flexible, letting different users make changes simultaneously, then reconciling them at a later stage, most often without manual intervention. 

 

Warning: some terms used in a Git context may have a different meaning than in other technologies, e.g. checkout.

 

 

Clone 

Cloning a repository is the action of creating a copy of that repository.  The most typical use case is for a user to clone a "remote" repository into a "local" folder.

 

Note that every clone of a repository contains the full content and history of that repository.  This makes it possible for you to explore and work in your local repository while being offline.  You only need a network connection when you decide to upload your changes to the remote repository, or to download the changes made by other users.

 

You can clone as many repositories as you want.  You can open each of them individually in Hackolade Studio.  If you start multiple instances of Hackolade Studio, each instance can have a different repository open, or the same one.

 

Cloning a remote repository should normally happen only once, whereas the other actions below typically happen on a regular basis. 

 

Note: we skipped on purpose the concept of creating a repository.  In most cases, you will work with existing repositories, created by the administrator in your organization.  If you need to create a new repo, you should create it first on your provider's platform (GitHub, GitLab, Bitbucket, Azure Repos, AWS CodeCommit, Google Cloud Source Repositories), then clone it in Hackolade Studio as described here.

 

Commit

Once you have your local clone of a repository, you can start making changes in the files that it contains, mainly Hackolade data models in our case.  You may also create new data models and save them into your local repository folder and sub-folders.

 

When you save your changes to a data model, they are, as usual, written to your file system.  However, at this stage, they are not tracked by Git yet.  You need one extra step to add your changes to the Git history: you need to commit them.  Once you have committed your changes, they appear as an atomic modification in the history of your local repository.

 

The changes that you commit are not immediately available to other users in your team. The next step is to push your commits to the remote repository.

 

Note that a commit can contain multiple changes, possibly in multiple files. It is a good practice to include, in a single commit, file changes that relate to one another, and to give every commit a meaningful description.

 

It is important to note that a commit, once it has been pushed to the remote repo, is a fairly immutable piece of Git history.  For integrity reasons, Hackolade Studio does not let users erase or cancel a commit from the Git history.  It can only be discarded undone via a revert operation.  If more specific actions are required, only experts should rewrite history, and perform these actions outside of Hackolade Studio.

 

Prior to being pushed, a commit can be discarded, or stashed.

Pull

Pulling remote commits is the action of downloading from the remote repository the commits that have been pushed by other users.  As long as you don't pull these commits, those changes are not available to you.

 

Push

Pushing your local commits is the action of publishing them to the remote repository to make them available to other users.  As long as you don't push your local commits, changes are only available to you.

 

Note that you need to commit your changes prior to pushing them. Uncommitted changes will not be pushed.  Also, you may make several local commits before pushing them to the remote repository (e.g. after working in offline mode for a while.)

 

Conflict

Conflicts can happen when pulling remote commits, in case you modified a line in a file that has also been modified differently by someone else. Hackolade Studio assists you in solving conflicts in data model files through an interactive merge dialog.

 

Chances for conflicts are minimized by the structure of Hackolade data model files, whereby each property, of each attribute, of each entity, of each container is its own line in a data model file. 

 

Best practice: to reduce the risks of facing conflicts, we recommend that you regularly pull remote commits.  This will ensure that your local repository is up-to-date with all the changes that have been recently pushed by other team members to the remote repository.  If you are about to start modifying a data model, then you should definitely pull first from the remote repository. 

 

It is also a good idea to regularly push your commits to the remote so other team members are aware of your changes. 

 

Branch

Git does more than tracking a linear sequence of commits. It supports branching to create independent sequences of commits that belong together. Such a sequence is called a branch.

 

A branch can be short-lived, to track small fixes for example. A branch could also be open for awhile, for example when developing the features of a new major version.

 

The picture below is an example of what the history of a repository can look like. Every circle represents one commit. There are sometimes multiple distinct sequences of commits (branches) running in parallel.

 

 

When you open a repository, what you see is the content of the repository on the branch that is currently active (there is always at least one branch in a repository).

 

When you commit your changes, you commit them on the active branch.

 

You can create as many branches as you need. You can switch from one branch to another.  In Git terms, these actions are both called "checkout".  This term is not to be confused with the concept of checkout in other technologies. The term checkout in a Git context means selecting a branch, whether the branch is an existing one or a new one. 

 

When you checkout a branch, it becomes the active branch.  Every change you make only affects that branch.  Other branches remain untouched.

 

When you checkout a new branch, it is only available to you in your local repository.  It becomes available for other people only after you push the commits that you made on that branch to the remote repository.

 

You can merge a branch into another one.

 

You can delete a branch (after merging it, or not merging it.)

 

Note: you should should choose carefully the basis for your new branch, if that basis is any other branch than main/master.  This is because a new branch inherits all the history and content of the branch on which it is based. This article explains Git branches with a LEGO analogy.

 

 

Creation of change/merge/pull requests

The peer review feature is a very popular collaboration extension to Git, supported by most of the repository hubs.  It allows changes made by a user to be submitted for review and approval by another user before being merged into a target branch.  

 

Changes to data models are proposed in a branch, to ensure that the target branch only contains finished and approved work.  Anyone with read access to a repository is allowed to submit changes for review.

 

Note:  the naming conventions differ slightly between repository hub providers.  GitHub, for example, uses the terminology pull requests, whereas GitLab uses merge requests.  Both refer to the same concept.  Hackolade Studio takes into account the specific terminology of the hub provider.  However, in this documentation, we abstract them and refer to the more generic "change requests".

 

 

Review of change/merge/pull requests

Peers may comment a change request and solicit adjustments to be made to the data models in the branch.  Designated reviewers may approve or reject change requests.