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.
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
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.
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.
push your changes to CleverMaps with CleverMaps Shell - use
pushProject. Do not commit unfinished work.
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
commit your changes with
git commit -m "<commit_message>". Use descriptive commit messages.
push your changes with
This part of tutorial showcases how you can restore older version of CleverMaps project using Git.
Open your project repository in command line.
git checkout <commit_hash>. Every commit made has a commit hash.
You can find commit hash that you want to restore with
<user>@<device> /c/CleverMaps/Projects/<projectId> (master) $ git log commit 10e67edb0bedea12a422544cf6a49981aacab4f1 (HEAD -> master, origin/master) Author: Your Name <firstname.lastname@example.org> Date: Fri Jul 29 15:12:53 2022 +0200 removed average transaction, adjusted dashboard commit 790a5d85b1d3fcd14e55d382adf7f017d3dc8bc4 Author: Your Name <email@example.com> Date: Fri Jul 29 15:01:54 2022 +0200 Changed layout of dashboard commit 8e0ac60fa0c7c9bcd4a0e12bfeb94eee77a9b3dd Author: Your Name <firstname.lastname@example.org> Date: Fri Jul 29 14:59:28 2022 +0200 Imported First project commit 5faaed4143dda2016e93ef50fc44e1adfb995555 Author: Your Name <email@example.com> Date: Fri Jul 29 14:58:53 2022 +0200 Added gitignoreNONE
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
So we run
git checkout 790a5d85b1d3fcd14e55d382adf7f017d3dc8bc4.
<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...)) $NONE
Open CleverMaps Shell and login
Open project with
openProject --project <project_id>
Now you can run
statuscommand. 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.
Once you have recognized files you want to restore you have two options depending on what you want to restore:
restoreMetadatato restore all changes.
Or you run
restoreMetadata --objectName <object_name>to restore one object.
firstname.lastname@example.org/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 email@example.com/project:k5t8mf2a80tay2ng/dump:$NONE
After you have restored files, you should put
masterbranch back in sync. Run
git checkout master --force. Now open CleverMaps Shell and run
fetch --forceto download latest changes from server. You can now commit changes to sync master with CleverMaps.