Kart Git And TUFLOW: Difference between revisions
Content deleted Content added
Ellis Symons (talk | contribs) |
Tuflowduncan (talk | contribs) |
||
| (39 intermediate revisions by 2 users not shown) | |||
Line 1:
==Introduction==
This page describes how to setup your TUFLOW model with Git and Kart (as this tends to be the tricker part). It doesn't necessarily discuss workflows once the repositories are setup.
==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 examples below have used SSH authentication with either Gitlab or Github.
* 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==
Line 9 ⟶ 12:
* Kart <b><u>[https://kartproject.org/ kartproject.org/]</u></b> - 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). The page [[TUFLOW Setup with Kart QGIS Plugin|here]] describes how to set up a TUFLOW project with Kart and some of the benefits.
==Setting Up Git Bash==
Line 22 ⟶ 25:
* <b><u>[https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent Generate an SSH key]</u></b>
* <b><u>[https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account Adding an SSH key]</u></b>
Each time you open a new instance of Git Bash, you will need to add the ssh key again in the bash window if you do not want to repeatedly have to enter your password (to be clear, the key does not require to be generated or linked with your Gitlab or Github account each time). The steps to add the ssh key are described below (taken from the above link) for ease of access.
<pre>
eval "$(ssh-agent -s)"
</pre>
and then (replacing <tt>id_ed25519</tt> with the name of your key).
<pre>
ssh-add ~/.ssh/id_ed25519
</pre>
Line 43 ⟶ 41:
====2. Clone Repository====
In Git Bash, use <tt>cd</tt> to change directory to where your model is going to sit. Note
<pre>
cd c:/projects
</pre>
Use <tt>git clone</tt> to clone your newly
<pre>
git clone git@gitlab.com:ellis_symons/tutorial-model.git
</pre>
Once created, you should change directory into the newly cloned project directory:
<pre>
cd tutorial-model
</pre>
====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 <tt>.gitignore</tt> 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).
<pre>
check*
results*
model/gis*
model/grid*
model/tin*
model/xf*
runs/log*
runs/_ TUFLOW Simulations.log
bc_dbase/xf*
*.qgz
</pre>
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). Using Git bash is shown below:
<pre>
git add .gitignore
</pre>
====4. Committing and Pusing====
Once files have been added they can be committed and then pushed to the remote repository.
<pre>
git commit -m "<commit message>"
git push
</pre>
==Setting up Kart Repository==
Kart can be used for 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.
<pre>
cd model
</pre>
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".
<pre>
kart.exe init gis_database
</pre>
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. 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
<pre>
cd gis
</pre>
====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:
<pre>
kart.exe import projection.gpkg projection
</pre>
Once the projection layer is added to kart, the original projection.gpkg can now be deleted. It is probably a good idea to keep your kart repo clean of other input files and only have the GPKG created with the kart repo in this location (it will be created when the first layer is imported). Keeping the empty folder in this location is probably ok and convenient.
====3. Link to Remote Repository====
You will need to delete the following file to be able to push your kart repo to a remote:<br>
<tt>.kart/hooks/pre-push</tt><br>
Create a new remote repository using similar steps as the control file repository. Once created the local kart repo can be linked and pushed using the following commands:
<pre>
kart.exe remote add origin git@gitlab.com:ellis_symons/tutorial-model-gis.git
kart.exe branch -M main
kart.exe push -u origin main
</pre>
You must have something to push (at least one commit). Importing layers counts as a commit (you are not required to manually commit after importing).
==Cloning an Existing Repository==
Once your model repository is setup it is desirable to be able to clone the repository so that others can work on it. The steps below outline how this can be done, it is assumed that Git Bash has been setup and configured with an SSH key and that the user has been given access to push/pull to the remote:
====1. Clone Control File Repository====
In Git Bash, change directory to where the TUFLOW model will sit (Note: bash will require forward slashes in file paths <tt>/</tt>):
<pre>
cd c:/projects
</pre>
Use <tt>git clone</tt> to clone the repo (Note: make sure to use the SSH repository address):
<pre>
git clone git@gitlab.com:ellis_symons/tutorial-model.git
</pre>
====2. Clone GIS File Repository====
Once the main project has been cloned, change directory into the model folder (where the "gis" folder will sit)
cd tutorial-model/model
Clone the kart repository assigning it the desired GPKG name (in this case the gpkg will be called "gis_database.gpkg"):
<pre>
kart.exe clone git@gitlab.com:ellis_symons/tutorial-model-gis.git gis_database
</pre>
Rename the "gis_database" folder to "gis" to match TUFLOW folder naming convention.
====Summary====
The steps above will copy all the input text control files (and boundary files) as well as the gis layers. The grid inputs have been excluded thus far from being versioned, this is due to their size (usually very big) and the fact that they don't often change meaning they don't typically have to be versioned. So at this point in the process any grid files will have to be copied from where they are being stored into the correct directory location.
==Workflow==
Once setup, the specific workflow will be dependent on how many many modellers will be working on the project concurrently and the specific goals of the project (e.g. are there going to be a lot of mitigation scenarios etc). The use of branches may be a robust approach in complex situations with a lot of mitigation options, or even a separate repository and GPKG for mitigation options.<Br>
<Br>
For the workflow, the easiest approach is to use something like Visual Studio Code for TUFLOW control file editing as this has a version control manager which will make the stage/commit/push/pull a lot easier and skips the need to be using the CLI. For kart, using the kart plugin in QGIS is the easiest method for skipping the need to use the CLI, however for pushing/pulling it may be necessary to use Git Bash to setup the SSH authentication. The TUFLOW plugin 'import empty' tool has an option to import directly into a kart repository, skipping the need to double handle the creation of TUFLOW GIS input files.
| |||