Git integration

Checking in changes made on modules in OpenCms to a version control system can be quite cumbersome. The OpenCms Git integration tackles that problem. You simply configure where your repository is and which modules you want to check in or check out and install from the repository. Then the workplace app "Git integration" provides an easy way to check in or check out and install modules.

The tool only works on Linux systems, since it uses a shell script for the git actions. Furthermore, git must be installed independently from OpenCms.

Via the Git integration you can perform check in and (re-)installation of modules from within the OpenCms and in just a few clicks. The figure shows the dialog for the tool when configured correctly.

Since OpenCms 11, the tool is only shown if a valid configuration is present. To get more control on the checked-in changes, we recommend to use the feature from the shell for most scenarios.

Module check-in

Via the workplace app "Git integration" you can select the modules you want to check in. The modules appearing in the list are pre-configured, but you can also add new modules via the drop-down left of the "Deselect all" button. Moreover, you can set your user information for the commit and the commit message. There are other options available. Via these, you specify copy, unzip, pull and push options. The options checked by default are configurable. Therefore, you typically do not have to alter these options. For example, you can only copy and unzip the module to your local repository and perform checkin manually. This will provide you more fine-grained influence on what is checked in. But you can also automatically check in and push your changes.

When directly checking in to the repository and pushing changes, you can only replace the whole module, i.e., all changes you made to the module are checked in.

Module import from the git repository

Besides checking in changes to your git repository, you can reimport modules directly from the repository. Choose the "Import"-tab in the settings panel shown in the git integration app and select the module you want to import. Moreover, you can choose if you want to fetch the remote state of the repository and reset to the remote head before you import the module, or if you just import the current local version.

Import basically zips the module resources. It does not compile any Java code.

Git configuration

The backend of the Git integration app a is a shell script and a configuration file placed under {webapp home}/WEB-INF/git-scripts/. The script module-checkin.sh is used to perform the git operations and the configuration is read from module-checkin.conf. A good starting point for writing your configuration is to copy the module-checkin.conf.demo file and adjust it to your needs. In particular, you should correctly configure your repository home and structure. Descriptions are found in module-checkin.conf.demo.

The options you set in module-checkin.conf can be overwritten in most cases. You can overwrite them by passing parameters to module-checkin.sh. That's what the Git integration app does. It reads the default options from module-checkin.conf and then passes the possibly changed options as parameters.

If you use environment variables in the module-checkin.conf file, make sure that the Git app (i.e., Tomcat or alike) has these variables set.

Using the Git integration via the command line

For many purposes, the OpenCms app "Git integration" will provide the suitable way to check in changes. But you can also call module-checkin.sh directly from the command line. If you work in your favorite IDE using a network share this might be an option as well.

The script expects all parameters first and then the configuration file. To get an overview on the parameters, please refer to the script itself and search for "read commandline arguments".

For using the script directly, you need to import and export modules via the network share. The reason is, that the Git integration app triggers module import and export directly in OpenCms, but the script cannot use that functionality.

A typical scenario for using the script directly could be, that you export and unzip modules to a repository you have present in a project in your IDE. You check the changes and commit via the IDE and then build the module again and copy it to the module import folder of the network share.

In summary, you have a lot of control on what is done automatically, and where you take action manually. Of course, all this can also be achieved using the Git integration app.