Kart Git And TUFLOW

Notes

• This wiki page was written with Kart v0.12.2 which is still considered a pre-release version. Kart is in rapid development and some of the constraints and/or methods may no longer be valid or have changed in subsequent versions.
• The examples on the page use git bash (on Windows) which is installed with Git. A lot of the methodology can also be done throught Windows command prompt with the same syntax however on this version of Kart, for private remote repositories, Kart will not prompt for any authentication while using command prompt and will simply fail to push/pull. Git bash will prompt for authentication and is also easier to add and save ssh keys so is a lot better to use in these contexts. For consistency, it will be adopted for all examples over command prompt.
• The examples below have used SSH authentication with either Gitlab or Github. SSH authentication appears to be work better with Kart.
• It's a good idea to ensure you have hidden folders visible. Both Git and Kart use hidden folders to store information and it's nice being able to see them and access them if needed.

Software and Installation

The following software is required:

• Git git-scm.com/downloads - There is a portable version Git for Windows, therefore it doesn't necessarily require admin privileges to install. There are a lot of user installation options, you should be able to simply use the default options throughout.
• Kart kartproject.org/ - Kart will require admin privileges to install. Kart is packaged with it's own Git version, however this will not contain git bash so the above installation will be required.

Recommended software:

• QGIS with the Kart plugin (and the TUFLOW plugin for importing empty files)

Setting Up Git Bash

Git Bash is installed with Git and is similar to Windows command prompt but uses bash (linux version of command prompt). When using Git bash and Kart together you will need to use kart.exe instead of simply kart e.g.

kart.exe commit -m "commit message"

Using kart with Windows command prompt will accept simply kart and all the Kart documenation suggests just using kart, but just be aware that ".exe" will be required if using Git Bash.

Git Bash can be opened up from the start menu. The examples on this page all use the SSH authentication method as this approach appears to currently work better with Kart. You will need to set this up on the remote repository you are using (e.g. Github or Gitlab). The steps on how to set up an SSH key is linked below, the instructions are for Github, however the process is very similar for Gitlab.

• Check for existing SSH keys (if you have already set one up and need to find its name)
• Generate an SSH key
• Adding an SSH key

Each time you open a new instance of Git Bash, you will need to add the ssh key again if you do not want to repeatedly have to enter your password. The steps to add the ssh key are described below (taken from the above link) for ease of access.

eval "$(ssh-agent -s)"

and then

ssh-add ~/.ssh/id_ed25519

replacing id_ed25519 with the name of your key. To add have it so it will save it even after a restart, you can add the key to the keychain by adding -k

ssh-add -k ~/.ssh/id_ed25519

Setting up Control File Repository

Since most of the TUFLOW input files (exclduing GIS/GRID inputs and some boundary formats) are plain text files, it is possible to simply use Git to version these files. There are a number of ways to initialise this, the approach shown below is done by intialising the remote repository on Github or Gitlab first and then cloning the repository, then adding files.

1. Create Remote Repository

Create your remote repository (usually using a Blank template), setting the name and whether the repository should be public or private.

2. Clone Repository

In Git Bash, use cd to change directory to where your model is going to sit. Note: Git Bash requires forward slashes /

cd c:/projects

Use git clone to clone your newly create repository. Note: make sure to use the SSH clone link if required (will start with "git@" rather than "https"). Tip: pasting is done by Ctrl+Shift+Insert (not Ctrl+V).

git clone git@gitlab.com:ellis_symons/tutorial-model.git

Once created, you should change directory into the newly cloned project directory:

cd tutorial-model

3. Adding Files

Once the repository is cloned, you can then add files. These can be existing files or files you start creating as part of a new model build. As an example, one of the first files that can be added is a .gitignore file. The example below is a template that can be copied when needed. To create this file, simply create a new text document and rename it to ".gitignore" and save it inside the cloned project folder (next to the ".git" folder).

check*
results*
model/gis*
model/grid*
model/tin*
model/xf*
runs/log*
runs/_ TUFLOW Simulations.log
bc_dbase/xf*
*.qgz

Once created, the .gitignore file can be added via git bash, Git GUI, or any other software that has version control integration (e.g. Visual Studio Code).

git add .gitignore

4. Committing and Pusing

Once files have been added they can be committed and then pushed to the remote repository.

git commit -m "<commit message>"
git push

Setting up Kart Repository

Kart is going to be used to version control the GIS vector inputs into the model. For Kart, the approach described below starts by initialising the local version first then linking it to a remote repository.

1. Initialise Kart Locally

Setup your TUFLOW folder structure if you have not done already. If this is a brand new project you can use the "Configure Project Tool" in the TUFLOW Plugin in QGIS (make sure to select GPKG as the GIS format). This tool may create a new folder called "TUFLOW" within the model folder structure, you can copy the contents out of this folder into the root project directory if you like" In Git Bash, change directory to the "model" folder, where the "gis" folder will sit.

cd model

Initialise the Kart repository. Note that Kart will create the folder if it does not exist and the name of the GPKG that it creates will match the name of the folder. In this example, the GPKG will be called "gis_database.gpkg".

kart.exe init gis_database

At this stage you may have a folder called "gis" where you have your existing files (empty files, projection etc) and a new folder called "gis_database" which is where the kart repo has been initialised. It's a good idea to consolidate all these into a single folder now. In this example (assuming a new project) the empty folder and projection.gpkg is going to be copied into the "gis_database" folder. Once copied, the "gis" folder can be deleted and the "gis_database" folder can be renamed to "gis" to keep it consistent with TUFLOW folder naming convention. Once renamed, change directory in Git Bash to the kart repo

cd gis

2. Import Layers

GPKG layers can be added to the kart repo. If the existing layers are shp files, then they will need be imported via the Kart plugin in QGIS which converts them first before importing them. In this example the projection.gpkg will be imported using the command below:

kart.exe import projection.gpkg projection

3. Link to Remote Repository

Create a new remote repository using similar steps as the control file