Using Git source control system

Add a workspace to Git

If your local PowerBuilder workspace has not been added to the Git source control system before, you can add the entire workspace to Git from the PowerBuilder IDE. To add a workspace to Git, you do it in two steps:

Step 1: You upload the workspace to the repository on your local computer.

Step 2: You push the workspace from the local repository to the remote repository on the Git source control server.

Below are the complete steps.

To add a PowerBuilder workspace to the Git source control system:

  1. Right-click the workspace in the System Tree and select Add to Source Control from the pop-up menu.

  2. In the Add to Source Control dialog box, select Git as the source control provider for the current workspace and click OK.

    Select Source Control Provider

  3. In the Author Information dialog box, input the author name and author email.

    Input author information

    After clicking OK, the Add to Source Control dialog box displays listing all the files for the workspace that are not currently under source control. You cannot add files that are already under source control.

    A ws_objects sub-folder is automatically created under the workspace, for managing the source code file of the PowerBuilder objects such as .srw (for window), .srm (for menu), .sru (for user object), .srd (for DataWindow), etc. ws_objects must be added to source code, in order to manage the source code at object level.

    Add to Source Control

  4. In the Add to Source Control dialog box, select the files and folders (especially ws_objects) and click OK.

    PowerBuilder adds the selected files and folders to the repository on your local computer. After the file or folder is added to the local repository, the object in the PowerBuilder System Tree will be marked with a green dot () in front of it, indicating that its source code file on the local computer is in sync with the file on the local repository. Now you can proceed to push the objects from the local repository to the remote repository on the Git source control server.

  5. Right-click the workspace in the System Tree and select Git Push from the pop-up menu.

  6. In the Git Login dialog box, input the information required by the source control system. If the login information has been input before, they will be filled in automatically.

    Input the URL of the Git server and the repository for the workspace. Make sure the repository with the same name exists on the server and the repository is empty before you push the files.

    The name of the current workspace is automatically displayed.

    Type in your user name and password for the Git source control system.

    Click Test Connection to make sure connection is successful and then click OK.

    If using proxy server

    If using the proxy server, configure the proxy server IP address and port number in the PB.ini file (by default, the INI file is located in C:\Users\<username>\appdata\local\appeon\powerbuilder 19.0\ in Windows 7 or later). Copy the following section to the INI file and set the appropriate value for the proxy server:

    [SourceControlProxy]

    Url=192.0.0.88

    Port=80

    Username=

    Password=

    Timeout=10

    Git Login

    PowerBuilder pushes the selected objects to the Git source control system.

"Reference was not fast-forwardable" error when pushing to Bitbucket

When adding the workspace to the Bitbucket server using "Git Push", you may come across the "Reference was not fast-forwardable" error, if the repository on the Bitbucket server is created with a readme (the "Include a README" option set to "Yes, ..."). To resolve this error, you can first execute a "Git Pull" (to synchronize the server repository with the local repository) and then execute "Git Push" again.

Get a workspace from Git

When PowerBuilder IDE opens without loading any workspace, you can get a PowerBuilder workspace from the source control system and open the workspace in the PowerBuilder IDE directly.

To get a PowerBuilder workspace from the Git source control system:

  1. Right-click "No Workspace" in the System Tree and select Connect to Workspace from the pop-up menu

    or

    Select Connect to Workspace from the File menu.

    The Connect to Workspace dialog box displays. If the login information has been input before, they will be filled in automatically.

  2. Select Git from the Source Control System list.

    Input the URL of the Git source control server and the name of an existing repository on the server.

    Type in your user name and password for the Git source control system.

    Type or select a path for the local root directory. All the files that you add to or get from source control must reside in this path or in a subdirectory of this path.

    Input the author name and author email.

    If using proxy server

    If using the proxy server, configure the proxy server IP address and port number in the PB.ini file (by default, the INI file is located in C:\Users\<username>\appdata\local\appeon\powerbuilder 19.0\ in Windows 7 or later). Copy the following section to the INI file and set the appropriate value for the proxy server:

    [SourceControlProxy]

    Url=192.0.0.88

    Port=80

    Username=

    Password=

    Timeout=10

    Connect to Workspace

  3. Click Test Connection, and click OK when connection is successful.

    PowerBuilder starts downloading the workspace from the Git source control system, and after the workspace is successfully downloaded, it will be loaded in the PowerBuilder IDE automatically.

    When Refresh is needed

    If you are not sure whether the PBL file on the source control server is the latest or not, it is recommended you do a Refresh manually (by right clicking the workspace and selecting Refresh from the popup menu).

Commit objects to Git

After you create a new object or change an existing object on your local workspace, you can commit the object to the Git source control system so that other developers can reach it. Similar to how you add a workspace to Git, you commit the object in two steps: 1) upload the object to the local repository; 2) push the object from the local repository to the server repository.

To commit an object to the Git source control system:

  1. Right-click the object (or the library that contains the object) in the System Tree and select Git Commit from the pop-up menu.

  2. In the commit dialog box that displays, input a comment and click OK to confirm committing the object.

    PowerBuilder uploads the object to the repository on the local computer. After the object is uploaded successfully, the icon in front of the object will change from a plus sign () to a green dot (), indicating that the object on the local computer is in sync with the object on the local repository.

    Now you can proceed to push the objects from the local repository to the server repository.

    To push objects to the server repository, you can only push from the workspace, as described in the next step.

  3. Right-click the workspace in the System Tree and select Git Push from the pop-up menu.

    PowerBuilder pushes the new or changed objects from the local repository to the server repository.

    If conflicts are detected, you will be prompted in the output view and will have to resolve the conflict manually. See the section called “Resolve conflicts” for details.

If you remove an object from your local workspace, you use the same instructions as above to commit the change and remove the object from the Git source control server.

The output (including error and warning) of a variety of operations (Git Commit, Git Pull, Git Revert, and Refresh) displays in the Output window. Currently, lines in the Output window provide no links to open the object when you double-click on that line, and although the pop-up menu provides the options Edit and Edit Source, they will not open an object in a painter or the Source editor.

Get objects from Git

For objects that are changed or added by other developers to the Git source control server but not yet synchronized to your local workspace, you can get these objects from the source control system.

To get objects from the Git source control system:

  • Right-click the workspace (that contains the object to be downloaded) in the System Tree and select Git Pull from the pop-up menu.

    Git Pull menu is only available at the workspace level, and is not available at the target or library levels.

    PowerBuilder starts downloading the new objects or changed objects from the Git source control system to the local workspace. After the object is downloaded successfully, the object will be marked with a green dot () in front of it, indicating that the object on the local computer is in sync with the object on the server.

    If conflicts are detected, you will be prompted in the output view and will have to resolve the conflict using a Git client. See the section called “Resolve conflicts” for details.

    When "Compile failure" error occurs

    When "Compile failure" error occurs during the download process, clicking OK will still download and import the object with the error (and you will need to fix the error later), or clicking Cancel will terminate the download process of all objects and revert back to the object on the local computer.

    When to do a full build

    When the following problems happen, a full build may help to fix them:

    • If both the parent object and the child object have been changed on the source control server, the parent object or the child object may not display correctly after downloaded from the server to the local computer.

    • After the object is downloaded from the server to the local computer, PowerBuilder IDE crashed when trying to open the object.

    • After the object is downloaded from the server to the local computer, the application crashed when running from the PowerBuilder IDE.

Resolve conflicts

If more than one developer are making changes to the same object and committing the object at the same time, conflicts will occur when synchronizing the object. When conflicts are detected, the object in the library tree will be marked by a "!!" sign () and you will be prompted in the output view and will have to resolve the conflict manually.

The following steps walk you through how to resolve the conflicts and merge the changes (Suppose developer A and B make changes to the same PowerBuilder object at the same time):

Step 1: Developer A commits the object to the source control server successfully.

Step 2: When developer B tries to commit the object, he receives a message requiring him to update the object first, so developer B performs Git Pull, then the object in the library tree will be marked by a "!!" sign () which means there is a conflict, and the changes made by Developer B, the original code, and the changes made by Developer A will be listed together in the object's source code.

Step 3: Developer B looks into the object's source code and decides which changes to keep (the changes made by Developer B, the original code, or the changes made by Developer A). He manually removes the unwanted changes from the object's source code.

Note

After you merge the changes, make sure the object can be compiled successfully by PowerBuilder, otherwise, the object may be missing or fail to open in the PowerBuilder IDE, or may cause the PowerBuilder IDE to crash.

Step 4: Developer B performs Git Resolve for the object to refresh the object status (clears the conflict sign) and then commit the object to the server.

Revert changes

For objects that are changed locally but not yet synchronized to the Git source control system, you can give up the local changes and restore to the version in the server repository.

To revert objects from the Git source control system:

  • Right-click the object in the System Tree and select Git Revert from the pop-up menu.

    PowerBuilder downloads the object from the server repository and replaces the copy in the local repository.

Refresh objects

After the object is loaded into the PowerBuilder IDE, it might be changed outside of the PowerBuilder IDE, for example, the developer merges the changes from the other version using a Git client, and such changes will not be detected by the PowerBuilder IDE, you will need to right click the object and select Refresh from the pop-up menu to reload the object in the PowerBuilder IDE.

The "Refresh" menu is also used when the PBL file on the source control server is not the latest when you first download the entire workspace from the source control server. In such case, after you download the PBL file, you will need to select the Refresh menu to refresh the objects and reload the latest objects in the PowerBuilder IDE.

Upload PBL

The PBL file will be uploaded to the source code server automatically when the workspace is first added to source control, and the PBL file will be downloaded automatically when the workspace is first downloaded from source control to a local machine. After that, it will not need to be uploaded or downloaded again whenever new or changed objects are uploaded or downloaded. Instead, the PBL file on the local machine will be updated automatically whenever objects are created or changed.

The "Upload PBL" menu is used only when you need to separately upload the PBL file to the source control server, in scenarios like you add a new PBL to the workspace and the PBL has not been uploaded to the source control server before, or the PBL file is removed from the workspace, or the PBL file has been changed dramatically since it is first uploaded, or the workspace is compiled with related errors.

Show logs

You can view the file revision log messages. PowerBuilder IDE provides no log viewer utility; it supports only TortoiseGit (or TortoiseSVN for SVN) and you must specify the executable file of TortoiseGit first.

To specify the executable file of TortoiseGit for viewing log messages:

  1. Right-click the workspace in the System Tree and select Properties from the pop-up menu.

  2. In the Properties of Workspace dialog box, select the Source Control tab, and then click the Advanced button.

  3. In the Source Control Advanced Settings dialog box, select Show Log in the left panel, and then specify the executable program of TortoiseGit.

  4. Click OK.

    Source Control Advanced Settings

To show the revision log:

  • Right-click the workspace, target, library, or object in the System Tree and select Git Show Log from the pop-up menu.

    The log viewer utility displays the revision logs directly.

Compare objects

You can compare an object in your local directory with the version of the object that was last synchronized with the source control server. If the object you want to compare has not been added to the source control server, or the local object is not changed since last sync, the Git Diff menu item is not available.

PowerBuilder IDE provides no difference utility, but it allows you to select one that you have already installed. Please make sure the utility itself is compatible with Git client 2.0 or later. The recommended utilities and versions are:

  • TortoiseGit 2.6.0.0

  • Araxis Merge 2018.4988

  • Beyond Compare 4.2.4

  • DiffMerge 4.2.0

  • ExamDiff Pro 9.0.1.8

  • KDiff3 0.9.98

  • SemanticMerge 2.0.120.0

  • UltraCompare 18.00.0.47

  • WinMerge 2.14.0.0

To select a utility for object comparison:

  1. Right-click the workspace in the System Tree and select Properties from the pop-up menu.

  2. In the Properties of Workspace dialog box, select the Source Control tab, and then click the Advanced button.

  3. In the Source Control Advanced Settings dialog box, select Diff Viewer in the left panel, then select the tool name from the list, specify the executable program of the tool, and change the arguments if necessary.

  4. Click OK.

    Source Control Advanced Settings

Method 1: To compare the local object with the version last sync with source control:

  • Right-click the object in the System Tree and select Git Diff from the pop-up menu.

    The difference utility displays the objects directly.

Method 2: To compare the local object with the version last sync with source control:

  1. Right-click the object in the System Tree and select Git Commit (Revert, or Resolve) from the pop-up menu.

  2. In the Git Commit (Revert, or Resolve) dialog, double click an item from the object list to view the differences.

    You can view the differences of the item which is added, modified, locked, or conflicted (but not deleted).

    The difference utility displays the objects and highlights the differences directly.

You can also compare the workspace file (.pbw) by right-clicking the workspace and selecting Git Diff, or compare the target file (.pbt) by right-clicking the target and selecting Git Diff, but you cannot compare the binary file such as the library file (.pbl).

Use branches

PowerBuilder IDE provides no direct option for creating or switching to a branch; but you can create and switch to the branch using the feature of a Git client (such as TortoiseGit). The process of switching to the branch is as below (Take TortoiseGit as an example):

  1. Create a branch in TortoiseGit.

  2. Switch to the branch in TortoiseGit.

  3. (Important) Restart PowerBuilder IDE so PowerBuilder IDE can automatically switch to the branch.

  4. (Important) Right-click the workspace and select Refresh to synchronize the object and the PBL file.

  5. Get/Commit objects to the branch using the same options as before (as the master) in PowerBuilder IDE.

View the connection settings

The Git connection settings can be viewed in the Properties of Workspace dialog box, only after you add the workspace to Git using the Add to Source Control menu or get the workspace from Git using the Connect to Workspace menu.

To view the connection settings of the Git source control system:

  1. Right-click the workspace in the System Tree and select Properties from the pop-up menu.

  2. Select the Source Control tab in the Properties for Workspace dialog box.

  3. Select Git from the Source Control System list.

    Git is available from the list only after the current workspace is under the Git source control, for example, after the workspace is uploaded to Git using the Add to Source Control menu (see the section called “Add a workspace to Git”), or after the workspace is downloaded from Git using the Connect to Workspace menu (see the section called “Get a workspace from Git”). You will need to provide the detailed connection settings when using the Add to Source Control menu or the Connect to Workspace menu.

    Source Control

  4. View the connection settings for the selected source control system:

    User ID and Password: User credentials for logging into the source control system. These settings can be changed here.

    Repository URL: A URL that points to the repository on the source control server. This setting is read-only and cannot be changed here.

    Local Root Directory: A local path where all the files that you add to or get from source control must reside. This setting is read-only and cannot be changed here.

    Author and Email: Author information that will be used when committing objects. These settings can be changed here.

  5. Click OK.

View the status of source-controlled objects

After a workspace is successfully added to the Git source control, icons in the PowerBuilder System Tree display the source control status of all objects in the workspace.

The icons and their meanings are described in the following tables.

Icon

Git source control status of object displaying icon

The object resides only locally and is not under source control.

The object is under source control. The object on the local computer is in sync with the object on the server.

The object is under source control. The object on the local computer is changed, and is not committed to the server.

The object is under source control. The object on the local computer conflicts with the object on the server.