The Seven Steps to Using OpenInsight Git
You should follow these simple steps when using a Git repository with OpenInsight. Depending on the Git client you use, some of these steps may be combined together, e.g. Pull and Merge. Also, the first step, Push your updates from OpenInsight, is automatically done for you in OpenInsight v10.0 and above.
1. Push your updates from OpenInsight to your local Git repository.
2. Commit your updates to your local Git repository.
3. Pull updates from remote Git repositories.
4. Merge updates pulled from remote Git repositories with your local Git repository.
5. Resolve any conflicts.
6. Push updates to remote Git repositories.
7. Pull updates from your local Git repository into OpenInsight.
Pushing updates from OpenInsight to Git
From OpenInsight v10.0 and above, OpenInsight Git is fully integrated into the OpenInsight repository. Whenever you add, modify or delete an OpenInsight entity, the update is automatically pushed to your local Git working directory. Git tracks changes, or deltas, only. If you save an entity without making any changes, Git will not recognize any changes and Git will ignore the save.
From OpenInsight v10.0 and above, updates are automatically pushed to Git. Therefore, there is usually no need to perform a manual “Push” of updates to Git. However, there are some scenarios where you must perform a manual “Push”.
1. When you first start using Git for your source code management.
2. If your local Git repository becomes corrupted.
3. If you think that something has been missed by the automatic repository processing.
To perform a manual “Push” from OpenInsight to Git, from the OpenInsight IDE choose Git, and select OI Source Control…
Figure 68 – OI Source Control to perform a manual push from OpenInsight to your local Git repository
This will open the OpenInsight Git Interface window. On the Operation dropdown choose Perform Push to GIT.
Figure 69 – Perform Push to Git
The default Git repository for the current OpenInsight application will be automatically selected. See “Setting Up OpenInsight Git” for further details about maintaining the available Git repositories.
Push Filter By
Figure 70 – Filter By: OpenInsight repository type
Entities can be filtered by OpenInsight repository type. In this example we will select OpenInsight stored procedures.
Choose the entities you want to manually push from the left list box. You can use the buttons between the list boxes to move entities in the left list box to and from the right list box. The entities listed in the right list box will be the ones “pushed” out to your local Git working directory. To push the selected entities click on the “Apply” button. If you “push” an entity that is identical in OpenInsight and Git, Git will ignore the “push” for the entity.
Figure 71 – Perform Push to Git
If you wish, you can compare the selected entities in the left list box with the corresponding copy in your Git repository by clicking on the Compare button.
How to commit changes to your local Git repository
You can check if there are any changes that require committing by opening Git Commit… from the Git menu on the OpenInsight IDE or opening your Git Extensions software and clicking on the Commit button.
Figure 72 – Git Commit menu option form OpenInsight
Figure 73 – Git Commit from Git Extensions
The Git Commit menu will only be enabled when there are uncommitted changes in your local Git working directory. The number of uncommitted changes will be displayed inside the square brackets.
Choose this menu option when you are ready to commit the changes to your local Git repository. This will open the Git Commit window.
The example window below is from the Git Extensions UI. Most Git UI tools will follow the same pattern.
Figure 74 – Git Extensions Commit Window
1. The upper left box contains a list of unstaged changes to your local Git repository, most commonly referred to as your “working directory”. You must stage the changes you wish to commit.
2. The lower left box contains a list of the changes you have staged and are ready to commit. Only the items in the staged box will be committed your main Git repository.
3. The upper right box displays the contents of the file currently selected in either the unstaged or staged boxes. When the item is in the staged box, this box contains the complete source code. When selected from the staged box, only the changes or deltas are displayed.
4. The lower right box is where you type a short description of the contents of this commit. e.g. updated Git to support Git Extensions client. The comment is optional but we strongly recommend that you write something short and meaningful. Other users will be able to read this comment, which will help them identify what changes occurred in the commit.
5. When you are happy with the selected changes and have typed in your comment, click on the Commit button. This will commit your changes to your local Git repository, commonly referred to as your “Master” branch.
You can also click on the “Commit & Push button”. This will commit your changes locally and then push them to your designed remote repository, commonly referred to as “origin”. But, it is recommended that you always pull changes from the remote repository first. When you pull first, you resolve any conflicts locally, before you push your changes to the remote repository.
Pulling updates from a remote Git repository
It is recommended that you always push and commit your OpenInsight changes to your local Git repository before pulling changes from a remote Git repository.
If you are not using a remote Git repository, then you can skip this step.
To pull updates from a remote repository select the Git Pull… option from the Git menu on the OpenInsight IDE or open your Git Extensions software and select Pull.
Figure 75 – Git Pull from the OpenInsight Git menu
Figure 76 – Git Pull from Git Extensions
The Git Pull window will appear. This example is from the Git Extensions UI.
Figure 77 – Git Extensions Pull Window
(1) “Pull from” will automatically default to “origin”, which is the remote repository you cloned from your local Git repository. You can change this to pull from any other remote repository using the Manage button.
(2) Select the “Merge remote branch into current branch” option, which is the default. This will pull updates from the remote Git repository and automatically merge them into your local repository. You will be notified if there are any conflicts during the merge process. You will need to resolve them before you can push/pull any changes from your local Git repository into OpenInsight or back out to any remove repository. See “Resolving conflicts” for more information.
(3) Click the Pull button to begin the Pull and Merge operation.
Once the Pull and Merge operation is complete and any conflicts are resolved, your local Git repository master branch will contain the latest version of the source code, including any changes pulled from remote repositories and any changes you made in your local copy of OpenInsight.
You are now ready to push your changes back to remote repositories.
Merge updates from remote repository with your local repository
When you pull updates from a remote repository Git does not automatically incorporate the updates into the master branch of your local repository. You must perform a “Merge” process to do this.
Some Git client tools, such as Git Extensions, can automatically merge the changes at the end of the “pull” process. This is a handy shortcut that saves you from performing a manual “merge” yourself.
The purpose of the merge process is to check for any conflicts between your local repository and the remote repository. Conflicts occur when the same line of code is changed in both your local repository and the remote repository copy of a file. If a conflict is found, none of the updates from the remote repository will be integrated with your local repository until the conflicts are resolved.
Below is an example of a conflict
| Local Git copy | Remote Git Copy |
|---|---|
| // loop to check a date table.eof = false$ old.flag = false$ Loop readnext id else table.eof = true$ while id do old.flag = false$ read record from table.handle,id then if record<17> < '18233' then old.flag = true$ end end repeat | // loop to check a date table.eof = false$ old.flag = false$ Loop readnext id else table.eof = true$ while id do old.flag = false$ read record from table.handle,id then if record<17> < '18598' then old.flag = true$ end end repeat |
In the above code, the highlighted line has been changed in both the local copy and the remote copy of the file. During the merge process, this will be identified as a conflict. Any files containing conflicts will be listed in the merge conflict resolution window.
You must then resolve all conflicts using the Git client compare tool. Once all conflicts have been resolved you can then rerun the merge process.
Resolving conflicts
If any conflicts are found during the “merge” process, you will be required to manually resolve the conflicts before continuing.
Different Git clients offer different conflict resolution tools. Git Extensions offers a great tool called KDiff. KDiff presents both versions of the file side by side. You have the option of choosing either one as the master copy or you can merge parts of each file into a new file. See your Git client for further details on conflict resolution. You will not be able to perform any further commit, pull or push operations from Git until all conflicts are resolved.
Push updates to remote repositories
You should only push your changes to remote repositories once:
a) You have pushed and committed your changes from your OpenInsight system.
b) You have pulled and merged updates from the remote repositories and resolved any conflicts.
To push your changes to remote Git repositories select the Git Push option from Git menu on the OpenInsight IDE or open Git Extentsions and select Push.
Figure 78 – Git Push from OpenInsight IDE
Figure 79 – Git Push from Git Extensions
This will open the Git Push client window. The example below is from the Git Extensions UI.
Figure 80 – Git Extensions – Push Window
(1) Select the remote Git repository you wish to push changes to. The default is “origin”, this is the remote repository you cloned your local Git repository from. You can change this to push to any other remote repository using the Manage button.
(2) “Push Branches” should be set to master and master
(3) Click the Push button to push your changes to the remote Git repository. You will be notified if there any conflicts. Conflicts will need to be resolved before you make any further changes to your Git repository.
Once the Push operation is complete and any conflicts are resolved, the remote Git repository master branch will contain the latest version of the source code, including any changes you made in your local copy of OpenInsight and push and committed to your local Git repository.
Pulling updates from Git into OpenInsight
Pulling updates in from your local Git repository into OpenInsight is the final step in the seven step process. To do this select the OI Pull from Git… menu option from the Git menu on the OpenInsight IDE.
Figure 81 – OI Pull from Git
This will open the standard OpenInsight Git window with the Pull operation preselected. It will also examine your local Git repository and identify and updates that need to be “pulled” into OpenInsight.
Figure 82 – OpenInsight Git – Pull changes
All Git entities that are different from their OpenInsight repository versions will be listed in the left listbox. Remember that this only means that they are different. In normal use, this usually means that the Git copy has been updated and you need to pull this update into OpenInsight.
However there may be times when your OpenInsight copy is more up to date than the Git copy, or you do not wish to pull in the copy from Git. In any case, you can select items in the left listbox and then click the Compare button to compare the OpenInsight version and the Git version.
Select the entities you wish to pull by moving them into the right listbox. Once you have selected all the entities you wish to pull, click the Go button. This will pull the selected entities into OpenInsight.
Note: Please ensure that you do not have any entities you wish to pull open in the editor or some other OpenInsight development tool. These entities will be locked and thus will not be available for update.
The icons next to each entity in the list have the following means during a Pull operation
Does not exist in your OpenInsight repository, so it will be added
This OpenInsight entity has been deleted from the Git repository, so it will be removed from your OpenInsight repository (including any debug and executable versions)
Exists in both Git and OpenInsight repositories, but the source in Git does not match the source in OpenInsight. You can use the compare button to compare these two versions.
The file in Git is identical to the source in OpenInsight. These items are ignored during a manual pull.
Any OpenInsight windows, stored procedures and inserts pulled in will trigger a recompilation. In the case of inserts, all stored procedures in your OpenInsight repository that use the insert, regardless of where they have been updated or not, will be recompiled.
If a stored procedure in an inherited application uses the insert, it will be flagged as requiring recompilation. The next time you login to that application, you can select the Recompile menu option from the OI Git Menu.
If a recompilation fails, the item will be flagged as requiring recompilation. You can then perform a manual recompilation at a later time.
Note: Any OpenInsight procedures that are currently running (in the program stack) cannot be recompiled. Instead these will be marked as in need of recompilation.
Any errors that occur during the pull process will be displayed at the end of the pull process. Typical errors include:
a) The entity is open in an OpenInsight development tool and thus is locked. Locked entities cannot be updated.
b) Recompilation failed – the compilation error code and description will be listed in the error log.
If a source entity fails to be pulled in successfully, check the error log for the error code and description. Once you resolve the error, you can try the Pull process again.
Recompiling procedures and windows
Usually when you pull in stored procedure, insert or window updates from your local Git repository, the necessary entities will be automatically recompiled. However, sometimes the recompilation may fail or it may not be possible to recompile at the time the updates are pulled in. For example:
a) The stored procedure is currently running in the program stack.
b) The stored procedure is in an inherited application.
c) The stored procedure failed recompilation for some reason.
d) The window failed to compile because the corresponding data tables were not attached or a dictionary field is missing.
When the automatic recompilation fails or is not possible, the entity is flagged as requiring recompilation. To check if you need to manually recompile entities, click on the OI Source Control… option from the Git menu on the OpenInsight IDE and choose Perform Recompile from the Operation drop down list.
Figure 83 – OI Source Control
Figure 84 – OI Source Control – Perform Recompile option
This lists all the entities in the current application that require a recompilation. Select the entities you wish to recompile and click the Apply button.
An error log will be generated if any of the entities fail to recompile. The failed entities will remain flagged as requiring recompilation.
The Seven Steps to Using OpenInsight Git
You should follow these simple steps when using a Git repository with OpenInsight. Depending on the Git client you use, some of these steps may be combined together, e.g. Pull and Merge. Also, the first step, Push your updates from OpenInsight, is automatically done for you in OpenInsight v10.0 and above.
1. Push your updates from OpenInsight to your local Git repository.
2. Commit your updates to your local Git repository.
3. Pull updates from remote Git repositories.
4. Merge updates pulled from remote Git repositories with your local Git repository.
5. Resolve any conflicts.
6. Push updates to remote Git repositories.
7. Pull updates from your local Git repository into OpenInsight.
Pushing updates from OpenInsight to Git
From OpenInsight v10.0 and above, OpenInsight Git is fully integrated into the OpenInsight repository. Whenever you add, modify or delete an OpenInsight entity, the update is automatically pushed to your local Git working directory. Git tracks changes, or deltas, only. If you save an entity without making any changes, Git will not recognize any changes and Git will ignore the save.
From OpenInsight v10.0 and above, updates are automatically pushed to Git. Therefore, there is usually no need to perform a manual “Push” of updates to Git. However, there are some scenarios where you must perform a manual “Push”.
1. When you first start using Git for your source code management.
2. If your local Git repository becomes corrupted.
3. If you think that something has been missed by the automatic repository processing.
To perform a manual “Push” from OpenInsight to Git, from the OpenInsight IDE choose Git, and select OI Source Control…
Figure 68 – OI Source Control to perform a manual push from OpenInsight to your local Git repository
This will open the OpenInsight Git Interface window. On the Operation dropdown choose Perform Push to GIT.
Figure 69 – Perform Push to Git
The default Git repository for the current OpenInsight application will be automatically selected. See “Setting Up OpenInsight Git” for further details about maintaining the available Git repositories.
Push Filter By
Figure 70 – Filter By: OpenInsight repository type
Entities can be filtered by OpenInsight repository type. In this example we will select OpenInsight stored procedures.
Choose the entities you want to manually push from the left list box. You can use the buttons between the list boxes to move entities in the left list box to and from the right list box. The entities listed in the right list box will be the ones “pushed” out to your local Git working directory. To push the selected entities click on the “Apply” button. If you “push” an entity that is identical in OpenInsight and Git, Git will ignore the “push” for the entity.
Figure 71 – Perform Push to Git
If you wish, you can compare the selected entities in the left list box with the corresponding copy in your Git repository by clicking on the Compare button.
How to commit changes to your local Git repository
You can check if there are any changes that require committing by opening Git Commit… from the Git menu on the OpenInsight IDE or opening your Git Extensions software and clicking on the Commit button.
Figure 72 – Git Commit menu option form OpenInsight
Figure 73 – Git Commit from Git Extensions
The Git Commit menu will only be enabled when there are uncommitted changes in your local Git working directory. The number of uncommitted changes will be displayed inside the square brackets.
Choose this menu option when you are ready to commit the changes to your local Git repository. This will open the Git Commit window.
The example window below is from the Git Extensions UI. Most Git UI tools will follow the same pattern.
Figure 74 – Git Extensions Commit Window
1. The upper left box contains a list of unstaged changes to your local Git repository, most commonly referred to as your “working directory”. You must stage the changes you wish to commit.
2. The lower left box contains a list of the changes you have staged and are ready to commit. Only the items in the staged box will be committed your main Git repository.
3. The upper right box displays the contents of the file currently selected in either the unstaged or staged boxes. When the item is in the staged box, this box contains the complete source code. When selected from the staged box, only the changes or deltas are displayed.
4. The lower right box is where you type a short description of the contents of this commit. e.g. updated Git to support Git Extensions client. The comment is optional but we strongly recommend that you write something short and meaningful. Other users will be able to read this comment, which will help them identify what changes occurred in the commit.
5. When you are happy with the selected changes and have typed in your comment, click on the Commit button. This will commit your changes to your local Git repository, commonly referred to as your “Master” branch.
You can also click on the “Commit & Push button”. This will commit your changes locally and then push them to your designed remote repository, commonly referred to as “origin”. But, it is recommended that you always pull changes from the remote repository first. When you pull first, you resolve any conflicts locally, before you push your changes to the remote repository.
Pulling updates from a remote Git repository
It is recommended that you always push and commit your OpenInsight changes to your local Git repository before pulling changes from a remote Git repository.
If you are not using a remote Git repository, then you can skip this step.
To pull updates from a remote repository select the Git Pull… option from the Git menu on the OpenInsight IDE or open your Git Extensions software and select Pull.
Figure 75 – Git Pull from the OpenInsight Git menu
Figure 76 – Git Pull from Git Extensions
The Git Pull window will appear. This example is from the Git Extensions UI.
Figure 77 – Git Extensions Pull Window
(1) “Pull from” will automatically default to “origin”, which is the remote repository you cloned from your local Git repository. You can change this to pull from any other remote repository using the Manage button.
(2) Select the “Merge remote branch into current branch” option, which is the default. This will pull updates from the remote Git repository and automatically merge them into your local repository. You will be notified if there are any conflicts during the merge process. You will need to resolve them before you can push/pull any changes from your local Git repository into OpenInsight or back out to any remove repository. See “Resolving conflicts” for more information.
(3) Click the Pull button to begin the Pull and Merge operation.
Once the Pull and Merge operation is complete and any conflicts are resolved, your local Git repository master branch will contain the latest version of the source code, including any changes pulled from remote repositories and any changes you made in your local copy of OpenInsight.
You are now ready to push your changes back to remote repositories.
Merge updates from remote repository with your local repository
When you pull updates from a remote repository Git does not automatically incorporate the updates into the master branch of your local repository. You must perform a “Merge” process to do this.
Some Git client tools, such as Git Extensions, can automatically merge the changes at the end of the “pull” process. This is a handy shortcut that saves you from performing a manual “merge” yourself.
The purpose of the merge process is to check for any conflicts between your local repository and the remote repository. Conflicts occur when the same line of code is changed in both your local repository and the remote repository copy of a file. If a conflict is found, none of the updates from the remote repository will be integrated with your local repository until the conflicts are resolved.
Below is an example of a conflict
| Local Git copy | Remote Git copy |
| // loop to check a date table.eof = false$ old.flag = false$ Loop readnext id else table.eof = true$ while id do old.flag = false$ read record from table.handle,id then if record<17> < '18233' then old.flag = true$ end end repeat | // loop to check a date table.eof = false$ old.flag = false$ Loop readnext id else table.eof = true$ while id do old.flag = false$ read record from table.handle,id then if record<17> < '18598' then old.flag = true$ end end repeat |
In the above code, the highlighted line has been changed in both the local copy and the remote copy of the file. During the merge process, this will be identified as a conflict. Any files containing conflicts will be listed in the merge conflict resolution window.
You must then resolve all conflicts using the Git client compare tool. Once all conflicts have been resolved you can then rerun the merge process.
Resolving conflicts
If any conflicts are found during the “merge” process, you will be required to manually resolve the conflicts before continuing.
Different Git clients offer different conflict resolution tools. Git Extensions offers a great tool called KDiff. KDiff presents both versions of the file side by side. You have the option of choosing either one as the master copy or you can merge parts of each file into a new file. See your Git client for further details on conflict resolution. You will not be able to perform any further commit, pull or push operations from Git until all conflicts are resolved.
Push updates to remote repositories
You should only push your changes to remote repositories once:
a) You have pushed and committed your changes from your OpenInsight system.
b) You have pulled and merged updates from the remote repositories and resolved any conflicts.
To push your changes to remote Git repositories select the Git Push option from Git menu on the OpenInsight IDE or open Git Extentsions and select Push.
Figure 78 – Git Push from OpenInsight IDE
Figure 79 – Git Push from Git Extensions
This will open the Git Push client window. The example below is from the Git Extensions UI.
Figure 80 – Git Extensions – Push Window
(1) Select the remote Git repository you wish to push changes to. The default is “origin”, this is the remote repository you cloned your local Git repository from. You can change this to push to any other remote repository using the Manage button.
(2) “Push Branches” should be set to master and master
(3) Click the Push button to push your changes to the remote Git repository. You will be notified if there any conflicts. Conflicts will need to be resolved before you make any further changes to your Git repository.
Once the Push operation is complete and any conflicts are resolved, the remote Git repository master branch will contain the latest version of the source code, including any changes you made in your local copy of OpenInsight and push and committed to your local Git repository.
Pulling updates from Git into OpenInsight
Pulling updates in from your local Git repository into OpenInsight is the final step in the seven step process. To do this select the OI Pull from Git… menu option from the Git menu on the OpenInsight IDE.
Figure 81 – OI Pull from Git
This will open the standard OpenInsight Git window with the Pull operation preselected. It will also examine your local Git repository and identify and updates that need to be “pulled” into OpenInsight.
Figure 82 – OpenInsight Git – Pull changes
All Git entities that are different from their OpenInsight repository versions will be listed in the left listbox. Remember that this only means that they are different. In normal use, this usually means that the Git copy has been updated and you need to pull this update into OpenInsight.
However there may be times when your OpenInsight copy is more up to date than the Git copy, or you do not wish to pull in the copy from Git. In any case, you can select items in the left listbox and then click the Compare button to compare the OpenInsight version and the Git version.
Select the entities you wish to pull by moving them into the right listbox. Once you have selected all the entities you wish to pull, click the Go button. This will pull the selected entities into OpenInsight.
Note: Please ensure that you do not have any entities you wish to pull open in the editor or some other OpenInsight development tool. These entities will be locked and thus will not be available for update.
The icons next to each entity in the list have the following means during a Pull operation
| | Does not exist in your OpenInsight repository, so it will be added |
| | This OpenInsight entity has been deleted from the Git repository, so it will be removed from your OpenInsight repository (including any debug and executable versions) |
| Exists in both Git and OpenInsight repositories, but the source in Git does not match the source in OpenInsight. You can use the compare button to compare these two versions. |
| | The file in Git is identical to the source in OpenInsight. These items are ignored during a manual pull. |
Any OpenInsight windows, stored procedures and inserts pulled in will trigger a recompilation. In the case of inserts, all stored procedures in your OpenInsight repository that use the insert, regardless of where they have been updated or not, will be recompiled.
If a stored procedure in an inherited application uses the insert, it will be flagged as requiring recompilation. The next time you login to that application, you can select the Recompile menu option from the OI Git Menu.
If a recompilation fails, the item will be flagged as requiring recompilation. You can then perform a manual recompilation at a later time.
Note: Any OpenInsight procedures that are currently running (in the program stack) cannot be recompiled. Instead these will be marked as in need of recompilation.
Any errors that occur during the pull process will be displayed at the end of the pull process. Typical errors include:
a) The entity is open in an OpenInsight development tool and thus is locked. Locked entities cannot be updated.
b) Recompilation failed – the compilation error code and description will be listed in the error log.
If a source entity fails to be pulled in successfully, check the error log for the error code and description. Once you resolve the error, you can try the Pull process again.
Recompiling procedures and windows
Usually when you pull in stored procedure, insert or window updates from your local Git repository, the necessary entities will be automatically recompiled. However, sometimes the recompilation may fail or it may not be possible to recompile at the time the updates are pulled in. For example:
a) The stored procedure is currently running in the program stack.
b) The stored procedure is in an inherited application.
c) The stored procedure failed recompilation for some reason.
d) The window failed to compile because the corresponding data tables were not attached or a dictionary field is missing.
When the automatic recompilation fails or is not possible, the entity is flagged as requiring recompilation. To check if you need to manually recompile entities, click on the OI Source Control… option from the Git menu on the OpenInsight IDE and choose Perform Recompile from the Operation drop down list.
Figure 83 – OI Source Control
Figure 84 – OI Source Control – Perform Recompile option
This lists all the entities in the current application that require a recompilation. Select the entities you wish to recompile and click the Apply button.
An error log will be generated if any of the entities fail to recompile. The failed entities will remain flagged as requiring recompilation.