Tutorial 11: Project versioning with Git

In this tutorial, we’ll show you how you can integrate version control into your workflow.

As the name of this tutorial suggests we will be using Git. If you don’t have Git installed, you can follow this tutorial.

Repository setup

This part of tutorial show you how to setup empty repository, add .gitignore to your repository and setup remote repository. If you have an existing repository, folllow How to setup existing repository tutorial below.

First step is to initialize our Git repository. Dump your project using CleverMaps Shell. Open command line and go to dump of your project. You can use cd \path\to\your\dumpDirectory\projectId. Now use git init command. This will initialize your local repository.

cd \path\to\your\dumpDirectory\projectId
git init

Adding .gitignore

Next step is to add gitignore file to your project.

Shell uses dumpMetadata.json to track changes in dump. We dont want to version this file in our commits. We also don’t recommend versioning data CSV files.

Add following lines to your .gitignore or download it below.

dumpMetadata.json
/data

.gitignore

Warning: You need to save file above as “.gitignore”.
Now add your gitignore to your repository. Run following commands to commit changes.

git add .gitignore
git commit -m "Added gitignore"

Setting remote repository

We recommend saving your changes to remote repository provided by GitHub, Bitbucket or some other hosting service.

You can then add your remote repository. Then push local changes to remote branch.

git remote add <remote_name> <remote_repo_url>
git push --set-upstream <remote_name> <branch_name>

You have finished setting up your git repository. You can check you remote repositories with git remote -v.

How to setup existing repository

If you already have existing repository, you can clone it. Open command line and go to your dump directory eg. cd \path\to\your\dumpDirectory. Now use git clone <repo-url>. It will create new directory in your dump directory.

cd \path\to\your\dumpDirectory
git clone <repo-url>

Now you should have new directory in your dump directory.

Saving changes to the repository

Whenever you make changes to the project you should commit them. In this part we will show you steps to take.

1. push your changes to CleverMaps with CleverMaps Shell - use addMetadata and pushProject. Do not commit unfinished work.

2. open command line in your project repository and run git add .. This will add all the changes to be commited. (see git add). You can review added files with git status.

3. commit your changes with git commit -m "<commit_message>". Use descriptive commit messages.

4. push your changes with git push.

Restoring backup

This part of tutorial showcases how you can restore older version of CleverMaps project using Git.

1. Open your project repository in command line.

2. Run git checkout <commit_hash>. Every commit made has a commit hash.
   You can find commit hash that you want to restore with git log.
   
   Example of git log:

   NONE

   <user>@<device> /c/CleverMaps/Projects/<projectId> (master) $ git log
   commit 10e67edb0bedea12a422544cf6a49981aacab4f1 (HEAD -> master, origin/master)
   Author: Your Name <you@example.com>
   Date:   Fri Jul 29 15:12:53 2022 +0200
   
       removed average transaction, adjusted dashboard
   
   commit 790a5d85b1d3fcd14e55d382adf7f017d3dc8bc4
   Author: Your Name <you@example.com>
   Date:   Fri Jul 29 15:01:54 2022 +0200
   
       Changed layout of dashboard
   
   commit 8e0ac60fa0c7c9bcd4a0e12bfeb94eee77a9b3dd
   Author: Your Name <you@example.com>
   Date:   Fri Jul 29 14:59:28 2022 +0200
   
       Imported First project
   
   commit 5faaed4143dda2016e93ef50fc44e1adfb995555
   Author: Your Name <you@example.com>
   Date:   Fri Jul 29 14:58:53 2022 +0200
   
       Added gitignore
   

   We can see in example 4 commits in master branch. The most recent commit has commit hash 10e67edb0bedea12a422544cf6a49981aacab4f1. We would like to restore previous version with commit hash 790a5d85b1d3fcd14e55d382adf7f017d3dc8bc4.
   
   So we run git checkout 790a5d85b1d3fcd14e55d382adf7f017d3dc8bc4.

   NONE

   <user>@<device> /c/CleverMaps/Projects/<projectId> (master) $ git checkout 790a5d85b1d3fcd14e55d382adf7f017d3dc8bc4
   Note: switching to '790a5d85b1d3fcd14e55d382adf7f017d3dc8bc4'.
   
   You are in 'detached HEAD' state. You can look around, make experimental
   changes and commit them, and you can discard any commits you make in this
   state without impacting any branches by switching back to a branch.
   
   If you want to create a new branch to retain commits you create, you may
   do so (now or later) by using -c with the switch command. Example:
   
     git switch -c <new-branch-name>
   
   Or undo this operation with:
   
     git switch -
   
   Turn off this advice by setting config variable advice.detachedHead to false
   
   HEAD is now at 790a5d8 Changed layout of dashboard
   
   <user>@<device> /c/CleverMaps/Projects/<projectId> ((790a5d8...)) $

3. Open CleverMaps Shell and login
   Open project with openProject --project <project_id>
   Now you can run status command. It will show you all the files that were changed between your checked out commit and current version.
   You can also run diff. Diff will show changes in files.

4. Once you have recognized files you want to restore you have two options depending on what you want to restore:
   Run restoreMetadata to restore all changes.
   Or you run restoreMetadata --objectName <object_name> to restore one object.
   
   Example of restoreMetadata:

   NONE

   daniel.valansky@secure.clevermaps.io/project:k5t8mf2a80tay2ng/dump:$ restoreMetadata
   Restoring objects...
    
   Adding all new objects to the project...
    
   Added object average_transaction_metric.json
   Added object average_transaction_indicator.json
    
   2 new objects have been successfully uploaded to project k5t8mf2a80tay2ng
    
   Uploading modified metadata objects to the project...
    
   Uploaded object transactions_metric.json
   Uploaded object business_overview_dashboard.json
    
   Metadata of project k5t8mf2a80tay2ng successfully updated from dump
    
   daniel.valansky@secure.clevermaps.io/project:k5t8mf2a80tay2ng/dump:$

5. After you have restored files, you should put master branch back in sync. Run git checkout master --force. Now open CleverMaps Shell and run fetch --force to download latest changes from server. You can now commit changes to sync master with CleverMaps.