Quick Guide
Installing
Windows
Download the .msi installer from the release page.
macOS
Download the .pkg installer from the release page.
Or use Homebrew to install:
brew install koordinates/kart/kart --cask
Linux
For Debian/Ubuntu-based distributions, download the .deb package from
the release page and
install via dpkg -i kart_*.deb
For RPM-based distributions, download the .rpm package from the release page and install via
rpm -i kart-*.rpm
Quick Start
See the documentation for tutorials and reference.
💡 If you’re new to git
Configure the identity you will use for Kart commits with:
$ kart config --global user.email "you@example.com" $ kart config --global user.name "Your Name"
Export a GeoPackage from Koordinates with any combination of vector layers and tables.
Create a new Kart repository and import the GeoPackage (eg.
kx-foo-layer.gpkg
).$ kart init myproject --import GPKG:kx-foo-layer.gpkg $ cd myproject
Use this repository as the directory to run all the other commands in. This will also create a working copy as
myproject/myproject.gpkg
to edit.Editing the working copy in QGIS/etc:
will track changes in the internal
kart
tablesadditions/edits/deletes of features are supported
changing feature PKs is supported
schema changes should be detected, but aren’t supported yet (will error).
Use F5 to refresh your QGIS map after changing the underlying working-copy data using
kart
.
With your working copy,
kart
commands should work if run from themyproject/
folder. Check--help
for options, the most important ones are supported. In some cases options are passed straight through to an underlying git command:kart diff
diff the working copy against the repository (no index!)kart commit -m {message}
commit outstanding changes from the working copykart log
review commit historykart branch
&kart checkout -b
branch managementkart fetch
fetch upstream changes.kart status
show working copy state.kart merge
merge. Supports--ff
/--no-ff
/--ff-only
from one merge source.kart switch
switch to existing or new branches.kart reset
&kart restore
discard changes in the working copy.kart tag ...
kart remote ...
. Remember simple remotes can just be another local directory.kart push
/kart pull
kart clone
initialise a new repository from a remote URL,
Create a new repository & import dataset
Start with a GeoPackage dataset (my.gpkg
), and create an empty
folder for your new kart project:
$ mkdir myproject
$ cd myproject
$ kart init --import /path/to/my.gpkg
Use this repository as the directory to run all the other commands in.
This will also create a working copy as myproject/myproject.gpkg
to
use for editing.
Workflow
Your repository consists of two “trees” maintained by kart. The first one is your working copy which is a GeoPackage holding the features you access & edit with your data tools. The second one is the HEAD which points to the last commit you’ve made.
Using the Working Copy
Editing with QGIS/ArcGIS/GDAL/etc:
Will track all changes made to layers and tables in the repository.
Additions/edits/deletes of features are supported
Editing of a feature’s primary key value is supported
Creating new fields or deleting existing fields is supported
In QGIS, use F5 to refresh your map after changing the underlying working-copy data using
kart
.
Commit
To commit changes you’ve made to your working copy, use:
kart commit -m "Commit message"
Now the file is committed to the HEAD.
Before committing changes, you can also preview them by using
kart diff
Branching
Branches are used to make changes isolated from each other. The master branch is the “default” branch when you create a repository. Use other branches for editing and merge them back to the master branch upon completion.
Create a new branch named “edit_x” and switch to it using:
kart checkout -b edit_x
Switch back to master: kart checkout master
And delete the branch again: kart branch -d edit_x
Merge
To merge another branch into your active branch (e.g. master), use
kart merge <branch>
Kart tries to auto-merge changes.
Tagging
it’s recommended to create tags for data releases. You can create a new
tag named 2019.11
by executing
kart tag 2019.11 1b2e1d63
the 1b2e1d63ff
stands for the first few characters of the commit id
you want to reference with your tag. You can get the commit id by
looking at the…
Log
in its simplest form, you can study repository history using
kart log
kart show
will show the latest HEAD commit
kart status
shows a summary of your branch state and working copy
changes.
Switch back to an old revision
Find the commit id (or tag or branch) you want to reference from
kart log
, then switch your working copy to it using
kart checkout 1b2e1d63
Replace working copy changes
You can replace edits to your working copy using the command
kart reset HEAD
. This replaces the changes in your working copy with
the last content in HEAD.