Git for IRIS is a Source Control package that aims to facilitate a native integration of the Git workflow with the InterSystems IRIS platform.
Similar to Caché Tortoize Git and Port, Git for IRIS keeps a code directory in sync with the internal packages that can be put under source control with Git. However, it is designed to work as a transparent link between IRIS and Git that, once setup, requires no user interaction in IRIS.
To use it, either run the docker example or install Git for IRIS on an existing IRIS instance.
git *: commit, push/pull, branch switching, merge.
/csp/user/sc) is now secured by an IRIS user and a (randomly generated) password. A new password is generated every time the source control is (re-)activated and the git hooks are installed.
To install Git for IRIS on an existing IRIS instance, do the following:
SourceControl/Gitinto a database of your choice. In this guide,
USERwill be assumed.
USERinto the namespaces that will use source control. To use it globally, the package can be mapped into
USERinto the namespaces that will use source control. It can be mapped into
Note: It is safe to map the package and Global into
%All even when Source Control will only be used in some namespaces for some packages. Unless there is a specific reason to use independent packages or
Git.* Globals among namespaces, mapping into
%All is recommended for its simplicity.
To specify the packages that will be under source control use these API methods:
do ##class(SourceControl.Git.Utils).AddPackageToSourceControl(<package name>, <namespace>)
do ##class(SourceControl.Git.Utils).RemovePackageFromSourceControl(<package name>)
For each package, a
<namespace> must be specified into which the package will be imported (since the namespace of a class may be ambiguous through mappings).
In the Management Portal go to System Administration > Configuration > Additional Settings > Source Control
For all namespaces that should be set up for Source Control, choose SourceControl.Git.Git and save.
Note: If classes are shared among namespaces through package mappings, it is practical to set up Source Control for all relevant namespaces. Each package will always be imported and exported from and to its 'home namespace' as defined in
AddPackageToSourceControl, so there will be no conflicts by having source control enabled in multiple namespaces at the same time.
Git.Configwill open on the View Global Data page and can be edited there. There is no dedicated settings GUI at the moment.
CodeDirectory|/opt/iriscode/|The directory to save the code files to. Usually the directory that is put under Git. Use OS-specific slashes.|
CompileFlags|cuk|Flags to compile the classes with after import|
Enabled|0|Enable or disable source control (accessible through the Source Control Menu > Enable/Disable Source Control)|
HooksEnabled|0|Whether to enable the git hooks and install git hooks into
<CodeDirectory>/.git dir. The
SourceControlResource settings can be ignored if hooks are disabled.
0 = error /
1 = important /
2 = info
RESTUrlPath|/csp/user/sc|Path of the web application the git hooks will call
RESTUrlPrefix|http://localhost:52773/|The base URL of this IRIS instace for the git hooks
RESTUsername|git|The username the git hooks use for authentication. Git for IRIS will assign a random password to this user upon installing the git hooks which is not stored anywhere except inside the git hooks scripts.
SourceControlResource|SourceControl|The security resource needed to access the web application
CodeDirectorysetting points to a valid folder.
Enable Source Control.
Enabling source control will:
- Enable OnAfterSave, OnAfterCompile and OnAfterDelete hooks which export the modified class or lookup table from IRIS to the code directory.
- Install the git hooks (if setting
HooksEnabled = 1) which import classes from the code directory into IRIS (see section Git Hooks below).
- Run Export all changed: exports all classes and lookup tables currently under source control to the code directory.
If the code directory has gone out-of-sync in the meantime, IRIS still exports the current internal state of all classes, and potential conflicts shall, by design, be managed through Git (
Now, with source control enabled, classes will be written to the code directory upon every save, compile or delete event. The code directory is designed to be put under source control with Git.
Git hooks can bee used to automatically trigger Import all changed upon
git checkout and
iris.script(or do so manually).
module.xml. The path and the required resource may be changed as desired and must match the
Note: Git hooks are optional; the same functionality can be achieved by running Import all changed manually in the source control menu when files in the code directory have been updated.
Clone repo, build and run the docker image from a terminal window:
git clone https://github.com/MW-de/git-for-iris.git
docker-compose up -d
Go to Management Portal in http://localhost:9092/csp/sys/UtilHome.csp (Login with
_system:SYS) and activate the source control class:
Go to System Administration > Configuration > Additional Settings > Source Control
For namespace USER, choose SourceControl.Git.Git and save.
Access the source control menu, e. g. in a production, and click Enable Source Control.
The source control output window can be opened by clicking on the second item:
Git for IRIS is used with a Git client. You may use the command line Git client or an IDE like VSCode (optionally with Remote SSH). In this docker example, the
git client will be used within the docker image. In the terminal window, run:
docker-compose exec -u 52773 iris-git /bin/bash
You may now edit some code in IRIS. As an example, go to Interoperability > Business Process Designer and create a new BPL process. Save it in package
SampleBPLProcess. Since the
dc.PackageSample package is under source control, it will be exported to
/opt/iriscode. In the docker terminal, run:
git add .
git commit -m "add new BPL process"
Now let's create a branch:
git checkout -b testing-branch
Back in the BPL editor, make some changes in
dc.PackageSample.SampleBPLProcess, like adding a BPL element to it, and save the BPL process.
git commit -a -m "change BPL process"
Now let's switch back to the master branch:
git checkout master
... and refresh the browser window. The BPL will be reverted to the state in
master. Switching branches again ...
git checkout testing-branch
... will get the newer version back.
This workflow extends to all other actions in Git, including working with remote repos and pull/merge.
1in the Settings to enable.
Git.*among multiple namespaces makes them share the same source control configuration.
Git.Config|The settings as described above
Git.Data.PackagesD|The packages and their "home" namespaces that are under source control
Git.Data.Items|For each item (= class) under source control, the internal timestamp, file timestamp and file size to determine whether and item has changed in IRIS or in the code directory.
Git for IRIS is currently in beta. The core features are implemented and ready to use. Known limitations are:
git stash, so IRIS will not be notified about stashing.
Export All Changedafter importing classes.
Import All Changedimmediately imports all classes from the Git directory to IRIS. If the directory has gone out of sync with the IRIS codebase (e.g. upon an import via Management Portal), changed will be overwritten without notice.
This project is based on Caché Tortoize Git by Alexander Koblov. This project started as a fork of the original project, however, most of the code has been rewritten.
IRIS for Windows compatibility, update ZPM module desc
v0.2: Add compile, add REST security