using ‘Tuttle’ - the Git version control extension

This chapter is about ‘Tuttle’, the Git version control application.

What is Tuttle?

git tuttle
Tuttle adds version control to data collections in eXist-db applications such as TEI Publisher. It is part of and published by the e-editiones society and can be used alongside TEI Publisher to allow synchronization of data collections between TEI Publisher instances and a Git repository. Tuttle wraps the APIs of the Git service providers under a common OpenAPI in TEI Publisher allowing projects to seemlessly add version control to their data.

What is needed to use Tuttle?

requirements setup Github Gitlab
1. Access to a repository To use Tuttle access to a repository on Github or Gitlab is necessary. This can be public or private repositories. On-premise servers will of course also work. 2. Access token In order to authenticate to the VCS (version control system) and being allowed to access its API a ‘personal access token’ is needed. This can be obtained from the respective service-provider. See ‘how to get an auth token’

How to configure Tuttle?

git tuttle github gitlab configuration
If Tuttle is integrated within another application like e.g. TEI Publisher the configuration needs to be added to modules/config.xqm in the TEI Publisher instance. Otherwise for running Tuttle in ‘Git to DB’ mode Tuttle is configured in modules/config.xqm in the TEI Publisher instance. Below is an example configuration that shows an example for either Github and Gitlab. Due to the different API of these services the configuration differs sligtly. See parameter description below.

How to use it for versioning annotations?

git tuttle github gitlab use case
in the pictures below the Github Logo is used but Gitlab can be used the same way Versioning Annotations Tuttle can be used to add versioning to the Annotations module. In TEI Publisher annotation view, authors have the option to push their changes to the repository directly from document view. In the upper right toolbar there will be a button to push your changes to the repository. Clicking the highlighted icon will pop up a dialog to specify a message for the changes.

What are the limitations?

git tuttle limitations
‘DB to Git’ does not support concurrent working on a single document. This mode is targetted towards the common use case of one person editing a document exclusively. As concurrent access to the same resource may cause conflicts in version control this should generally be avoided for seemless operation. Even if conflicts occur the data are always safe and can be retrieved all the time by a technical person with Git knowledge.