Versioning with Git

Create history

A history can be created in the following modules:

A Git repository forms the basis for the history. For each respective module, this is created in the following directory:

  • Applications module (Portal directory internal/application/store/<Application GUID>)

  • Processes module (Portal directory internal/workflow/<Process GUID>)

  • Design module (Portal directory internal/layout/xml/layouts/<Layout name>)

Each entry in the history corresponds to a commit in the Git repository. If you publish an application, process or layout via the File menu, a dialog will open where an entry in the history can be created with Git.

Publish with history

Here, you can see the dialog that opens when you publish an application. During the versioning process of applications or processes, the scripts they contain are also versioned.

Create entry in the application history / process history / layout history.

If this setting is activated, the latest change will be added to the history. This setting is not available if the "Always create history entry when publishing applications, workflows or layouts" options is activated in the options in the portal properties.

Comment

You can add a comment to document the latest change in the application. If a comment is not specified, the default comment from the language constant "COMMIT_DEFAULT_MESSAGE" in the default portal language used. Here is a guide on how to format commit comments.

Compare version currently open with the last entry in the application history

Opens a dialog where the changes in the application can be tracked.

Open version manager

Opens a dialog where the semantic version number can be edited.

Options / Publishing

In the Extras menu / Options, you can find the settings for publishing applications, processes and layouts with or without history under each respective module. Regardless of which option is selected here, the different publishing methods can also be selected from the respective File menu. Regardless of which option is selected here, the different publishing methods can also be selected from the respective File menu.

Default settings for publishing

Optimized publish

Only the pages that have been changed will be transformed for the web when you publish an application with this option. In general, the optimized publish is recommended.

Optimized publish with history

Here as well, only the pages that have been changed will be transformed. Additionally, when the application is published, a dialog will be shown where changes can be commented and an entry can be added to the application history.

Complete publish

When publishing an application, all objects are published. An application has to be published completely, if for example XSL files were exchanged on the server - e.g. after installing a patch that contains XSL files or when developing XSL files. In this case, all pages must be republished.

Complete publish with history

Here as well, every page will be transformed. Additionally, when the application is published, a dialog will be shown where changes can be commented and an entry can be added to the application history.

Allow application to be published despite error entries in the "Problems" area

When an application is opened, Intrexx checks it for errors. Corresponding notices are displayed in the Problems area. Warning entries are displayed as a notification. The application can still be published despite these. Error entries prevent the application from being published. However, you can allow the application to be published despite these by activating this setting.

This setting may not be available in future versions of Intrexx. The best approach is to always correct reported errors.

Regardless of which option is selected here, the different publishing methods for applications can also be selected from the File menu.

With processes and layouts, you will find the following settings in the "Publish" dialog:

Default settings for publishing

Public process / layout

The process or layout is published without history.

Publish process / layout with history

When publishing the process or layout, a dialog is displayed where changes can be commented and an entry can be created in the history.

Regardless of which option is selected here, the different publishing methods for processes or layout can also be selected from the File menu.

Portal properties / Options

In the Portal menu / Portal properties, you can specify that every time applications, processes and layouts are published, a new entry is created in the history. This option makes sense, for example, for live systems so that changes in the portal can be tracked. This applies to both user and system actions. When an action, which usually does not create a new history entry (e.g. Optimized publish), the user will receive a notification that a history entry is required. When an action, which usually does not create a new history entry (e.g. Optimized publish), the user will receive a notification that a history entry is required. Following this, the dialog for creating a new entry will open.

New entry in the history

A new history entry can be created in the following ways:

  • Applications - File menu

    • Publish application

      • Optimized publish with history

      • Complete publish with history

    • Create entry in application history

  • Processes - File menu

    • Publish process with history

    • Create entry in process history

  • Design - File menu

    • Publish layout with history

    • Create entry in layout history

New history entries are also created via user or system actions.

User actions

An entry is created under the following circumstances:

System actions

For certain actions, the system will automatically create a new entry in the history, if the corresponding setting is active in the portal properties. If a repository has not been created yet, this will be created here. Each new entry receives a static English comment with the prefix "Intrexx:". The user, who is stored in the history entry, depends on the action (see below). The following system actions are supported:

Complete history

The following menus open a dialog where you can find the complete history:

Search

The search filters the list based on the search term entered. Comments, users and tags are searched through. Within tags, names, comments and users are search through.

"ID" column

The ID of a repository entry is generated automatically by Intrexx and displayed in the abbreviated form typical for Git.

"Comment" column

The comments entered when the application, process or layout was published are shown here.

"User" column

The user who created the last entry in the history is shown here.

"Date" column

The date when the history entry was created is shown here.

Open in Portal Manager

Opens the selected version in the corresponding module. In the Applications module, the currently opened application will be closed with this action. In the Processes and Design module, the selected entry will open in a new tab. This function is only available if the expert options have been activated. The server will not be changed with this action. If you want to use the selected state, then you need to publish the respective application, process or layout via the File menu.

If you publish a different state from the history, data could be lost, if for example the current state contains a data field that the previous state does not.

Manage tags

Entries with tags are marked with this symbol in the last column. If you have marked such an entry, click on " Manage tags" on the right. This opens a dialog where the tags for the selected entry can be managed.

Details

The tag name, the user, who created the tag, the creation date, and - where applicable - the comment are shown automatically here.

Delete tag

Removes the currently selected tag from the history.

Create tag

Opens a dialog where a new tag can be created.

New day

Name

The name of the tag must be unique, meaning it may only appear once per history. Furthermore, the tag name must conform to Git. For example, it may not contain whitespace.

Comment

You can enter one comment for each tag. Click on "OK" to save the tag and close the dialog.

You will then be back in the "Manage tags" dialog. Click on "OK" to return to the history.

Load next 25 entries / Load all entries

When opening the dialog the last 25 entries of the history are loaded. Clicking "Load next 25 entries" or "Load all entries" loads the corresponding number of additional entries.

Refresh

Reloads the current state of the history from the server, e.g. if changes have been made that are not visible in the history. This situation occurs, e.g. if an application was published on the server but without an entry in the history. If this is the case, a corresponding notification is shown at the bottom of the dialog.

Advanced options

If the expert options have been activated in the current module, the Advanced options button will be available at the bottom of the dialog. The button opens a submenu from which all of the history entries can be deleted. The Git repository will also be deleted at the same time.

Individual history entries cannot be deleted.

Info text

Appears at the bottom in special situations, e.g. when there are changes on the server without an entry in the history.

Details

You will find the details in the lower part of the dialog. This displays the ID, user (QualifiedLoginName), date and comment from the currently selected entry.

Changes

Added, edited and deleted files for the currently selected entry are shown here.

"Type" column

The change type can be recognized from the symbol:

  • Added
  • View changes
  • Deleted

"Path" column

The path of the modified file relative to the portal directory internal/application/store/<Application GUID> is shown here.

View changes

Opens a sub menu with the menu items "View changes in diff format" and "View changes in external tool".

View changes in diff format

Opens a dialog where the differences can be viewed in the diff format from Git.

Here, you can view the changes to the file in the diff format typical for Git. For binary files, e.g. images, it will only be shown that there are changes.

Lines of context

Lines of context are the lines that are output before and after the changed lines in the diff. In Git, the default value is 3. The number of lines of context can be modified here.

Reset settings

Resets the number of lines of context to the default value of 3. Click on "OK" to close the dialog again.

Show changes in external tool

The file from the selected entry will be compared with the file from the previous entry in the external tool.

The external tool is only used for viewing. The external tool is only used for viewing.

View file history

Opens the change history in an additional window which functions analogously to the current dialog. Here, only the entries are shown where changes to the file were made.

Files

For the selected entry, all of the directories and files from the respective state will be shown in a tree structure. Files which have been deleted are not shown in the file tree. The following buttons are only available for files because only files, but not directories, are versioned in a Git repository.

View file

Opens a dialog where the content of the selected file is shown. Syntax highlighting is available for files ending with xml, js, vm, vmi, groovy or css. Image files with the png, jpg, jpeg or gif file extension are shown as an image. Click "OK" to close the dialog again.

View file history

Displays the history for the selected file. Afterwards, the comparison can be made.

Compare versions

The comparison can also be accessed directly via the main menus "Comparison with last entry in the application history" and "Comparison with entry in the application history". The currently opened state can also be compared to the last state of a history entry in the dialog where the history entry can be created. The same applies to processes and layouts.

Select entry from history

Search

The search filters the list based on the search term entered. Comments, users and tags are searched through. Within tags, names, comments and users are search through.

"ID" column

Displays the ID of the repository entry.

"Comment" column

Displays the comments that were entered when the application, process or layout was published.

"User" column

The user who created the last entry in the history is shown here.

"Date" column

The date when the history entry was created is shown here.

Select the version for comparison. When you click on "OK", the differences between the two versions will be displayed.

Comparison

"Type" column

The change type can be recognized from the symbol:

  • Added
  • View changes
  • Deleted

"Path" column

The path of the modified file relative to the portal directory internal/application/store/<Application GUID> is shown here.

View changes

Opens the following submenu:

  • View changes in diff format

    Opens a dialog where the differences can be viewed in the diff format from Git.

  • View changes in external tool

    The file from the selected entry will be compared with the file from the previous entry in the external tool.

    The external tool is only used for viewing. The external tool is only used for viewing.

  • Furthermore, the state which should be compared needs to be open in the Portal Manager.

    This sub menu is only available if the expert options have been activated. Changed files will be marked in the list with a *. Changes to the selected files can be merged interactively between the currently opened version and the selected history entry. Furthermore, the version which should be compared needs to be open in the Portal Manager. Only changes to files from the currently opened version in the local working directory can be applied. The selected file will be compared in the external tool using the two-window view.

    All changes in this area are carried out under own respsonsibility. Support cannot be provided for the editing of files and the resulting consequences. The action allows you to directly edit files and should therefore only be performed by users with the required specialized knowledge. Validate files in current working directory With this action, changes to the selected files can be completely reset from the currently opened version to a different, selected history entry.

Reset changes

This action is only available if the expert options have been activated. Furthermore, the version which should be compared needs to be open in the Portal Manager. Changed files will be marked in the list with a *. This action is only available if the expert options have been activated. Furthermore, the version which should be compared needs to be open in the Portal Manager.

All changes in this area are carried out under own respsonsibility. Support cannot be provided for the editing of files and the resulting consequences. The action allows you to directly edit files and should therefore only be performed by users with the required specialized knowledge. Validate files in current working directory With this action, changes to the selected files can be completely reset from the currently opened version to a different, selected history entry.

Changes to files may not be compatible with the patch level of the current portal. Please note: The patch level of individual files cannot be modified and may cause errors.

Validate files in current working directory

Opens a dialog where the files from applications, processes and layouts can be validated.

Validation

A click on the "Validate" button triggers the validation of the files in the working directory. During this, the schema of XML files is checked. Validating is a good idea if files were changed. This action is available for applications and processes.

Output

Displays the result.

Show details

This link is available if an error occurred during the validation. Clicking on this link opens a dialog where the error details can be viewed.

Details

Hide system files

This option filters the table. System files are files that are normally generated automatically by the system, e.g. when creating a new application or when publishing an existing one.

"History" area

In the "Applications", "Processes" and "Design" modules, you will find the "History" tab at the bottom. The complete history of the current application, process or layout is shown here.

Open detailed history

Opens a dialog where the entire history is shown. The entry selected on the tab is preselected.

Load next 25 entries / Load all entries

When the area is opened, the last 25 history entries are loaded. Clicking "Load next 25 entries" or "Load all entries" loads the corresponding number of additional entries.

Refresh

Reloads the history from the server. The view is automatically refreshed after the following actions:

Use tags

History entries can be marked as important using tags; this makes the specific entry easier to find. A tag is often used to denote a new version. In principle, every entry which is important to the Development can be marked with a tag. Intrexx automatically connects with Intrexx version number to tags in the history. If, for example, a new application version number is created and the application is then published, a tag with this version number is created for this commit.

Tags for the history of applications, processes and layouts can be created in the dialog which displays the complete history. Any number of tags can be added to a history entry. Tags can also be deleted. Every tag is constructed as follows:

  • Name

  • User (QualifiedLoginName) – is automatically determined in the "User" module. This is composed of the username and domain.

  • Date

  • Comment (optional)

The name of the tag must be unique, meaning it may only appear once per history. Furthermore, the tag name must conform to Git - for example, it may not contain whitespace. Rules for tag names can be found here. Optionally, each tag can be commented on. If no comment is defined, the comment stays empty. A tag is created automatically upon publishing, if the semantic version number has been changed. The tag name corresponds to the semantic version number and if necessary, a suffix is added to prevent duplicate entries.

Information about current state

You can see which version is currently open in the respective modules in the following places:

External tools

External tools can also be used when versioning with Git, these can be integrated here.

Misc

Applications, processes and layouts can be saved locally using the File menu. A locally saved application does not contain Git information. The same applies to locally saved processes and layouts. If you open a locally saved object in the corresponding module, you can view the history of the object if an application, process with the same GUID or layout with the same directory name has been published on the server.

Git configuration files

Configuration files are created when a Git repository is created. Depending on the object type (application, process, layout), not every configuration file is required.

  • .gitattributes

    This file contains the definitions for line endings for different file types.

  • .gitignore

    This file contains directories and files that should not be versioned.

Import / Export

When importing or exporting applications, processes or layouts, you can set how to proceed with version management.

Import

The dialog for version management is available in the import dialog by clicking on "Version management".

Options

If the setting "Create history entry when publishing" is active, an entry in the history will be created when the import is performed. Under "Comment" the entry "Import" can be replace by your own comment. Here is a guide on how to format commit comments.

History

History in the export

All history entries contained in the export are listed here. In the list you can find the ID of the corresponding entry, the comment, the user, who created the entry, and the date, when the record was created.

History on the server

All history entries for the import object, which are currently on the portal server for the import object, are listed here.

Compare export with the newest entry in the history on the server

Opens a dialog where the export can be compared with the newest entry in the history on the server. This action is only available if both the export and the server contain a history for the import object.

In the import dialog information about the version can be opened by clicking on "Version information".

Version information

The version number and the date are shown here. Under "System requirements" the minimum version of Intrexx that is required to implement the object is shown.

Export

In the export dialog the version management can be opened by clicking on "Version management".

Version information

Here the ID, the comment, the user, who caused the record in the history and the date, when the record was created, are shown. Furthermore you will be informed in the lower area of the dialog if changes have been made that are not yet visible in the history.

Also in the export dialog information about the version can be opened by clicking on "Version information".

The version number and the date are shown here. Under "System requirements" the minimum version of Intrexx that is required for the use of the export object is shown.

Options - History

The history options are available via the main menu "Extras / Options / General".

To view and merge changes in the History, you can enter paths to external tools here. The tools need to be installed on the same server where the Portal Manager is. Tools that can compare and merge two files in a two-window view are supported. The program path must support parameters for the file paths to be compared. To do this, the placeholders ${file1} and ${file2} can be used in the program path. ${file1} stands for the file that is taken as the basis for the comparison, ${file2} stands for the file for which the comparison is made. The placeholders are optional. If they are not specified, then they are attached programmatically to the program path.

The external tool is only used for viewing. Changes to files will not be applied.

Use external tool for viewing changes in the history

With this setting, a path to an external tool for viewing the changes can be entered.

Examples:

  • WinMerge (Windows)

    "C:\Program Files (x86)\WinMerge\WinMergeU.exe" /wl /wr ${file1} ${file2}

  • KDiff3 (Windows)

    "C:\Program Files\KDiff3\kdiff3.exe" ${file1} ${file2}

  • KDiff3 (Linux)

    kdiff3 ${file1} ${file2}

  • KDiff3 (Mac)

    /Applications/kdiff3.app/Contents/MacOS/kdiff3 ${file1} ${file2}

  • OpenDiff (Mac)

    /usr/bin/opendiff ${file1} ${file2}

Select

Opens a dialog where the tool can be selected.

Double-clicking on change opens external tool

Means that changes can be double-clicked on to view them in the history. If this option is not activated, the change will be shown in Diff format.

Use external tool for merging changes in the history

With this setting, a path to an external tool for merging the changes can be entered.

Examples:

  • WinMerge (Windows)

    "C:\Program Files (x86)\WinMerge\WinMergeU.exe" /wr ${file1} ${file2}

  • KDiff3 (Windows)

    "C:\Program Files\KDiff3\kdiff3.exe" ${file1} ${file2}

  • KDiff3 (Linux)

    kdiff3 ${file1} ${file2}

  • KDiff3 (Mac)

    /Applications/kdiff3.app/Contents/MacOS/kdiff3 ${file1} ${file2}

  • OpenDiff (Mac)

    /usr/bin/opendiff ${file1} ${file2}

More information

Versioning in general

Semantic versioning