Users Guide
Using Source Control

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.

   
   
   

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

   Specify the encoding format for the source code files in "ws_objects". You can select from: ANSI/DBCS, HEXASCII, and UTF8.

   
   
   

   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 including .srw (for window), .srm (for menu), .sru (for user object), .srd (for DataWindow), etc. The "ws_objects" folder must be added to the source code, in order to manage the source code at object level.

   
   
   

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.

   In the Repository URL box, 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 in the Workspace File field.

   Select Basic or Token from the Authentication Type list.

   In the User ID and Password (or Personal Access Token) boxes, type in your user name and password (or token) for the Git source control system.

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

   Note

   If your user name or password/personal access token is incorrect, you will be displayed with a third-party log-in window to directly authenticate your user credentials with the Git server. If authentication is successful, your user name and password or personal access token will be automatically filled into the Git Login dialog box. For more information, see authenticate your user credentials with the Git server.

   Note

   If using the proxy server, configure the proxy server IP address and port number in the PB.ini file. See Using proxy server for more information.

   
   
   

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

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.

3. In the Repository URL box, input the URL of the Git source control server and the name of an existing repository on the server.

4. In the Workspace File box, type in the name of the workspace file to be downloaded from the repository. Note that the workspace file name is case-sensitive.

5. In the Branch box, specify the branch from which source code will be downloaded. If not specified, it will default to the "main" branch.

6. Select Basic or Token from the Authentication Type list.

7. In the User ID and Password (or Personal Access Token) boxes, type in your user name and password (or token) for the Git source control system.

8. In the Checkout Directory box, 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.

9. In the Author Name and Author Email box, input the author name and author email.

10. Select the "Regenerate all PBLs with the source code after download" option to regenerate all PBLs after downloading the source code from workspace if you are unsure whether the PBLs are updated with the latest source code.

    Note

    If using the proxy server, configure the proxy server IP address and port number in the PB.ini file. See Using proxy server for more information.

    
    
    

11. 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.

    Note

    After you get a workspace which was added to Git using a third-party tool such as TortoiseGit (not by PowerBuilder IDE), the objects will be marked with this icon which means the objects are not yet under source control in PowerBuilder IDE, so you should commit the entire workspace from the PowerBuilder IDE to Git to add it under source control.

To authenticate your user credentials with the Git server:

You can directly get your username/password (or personal access token) from the GitHub, GitLab, BitBucket etc. in the Connect to Workspace dialog box.

1. In the Connect to Workspace dialog box, select Git from the Source Control System list.

2. In the Repository URL box, input the URL of the Git source control server and the name of an existing repository on the server.

3. In the Workspace File box, type in the name of the workspace file to be downloaded from the repository. Note that the workspace file name is case-sensitive.

4. Leave the Branch box empty if downloading from the "main" branch, or specify a branch.

5. Select Basic or Token from the Authentication Type list and leave the User ID and Password (or Personal Access Token) boxes empty.

6. Click Connect.

   
   
   

7. In the Windows Credentials window or the sign-in window for GitHub, GitLab, BitBucket etc., sign in with your user name and password.

   You will need to install the Git for Windows tool first in order to display the Windows Credentials window or the sign-in window for GitHub, GitLab, BitBucket etc..

   Take GitHub for example. In the Connect to GitHub window, click Sign in with your browser, and then sign in to GitHub with your user name and password in the browser window. When authentication succeeds, your user name and password or personal access token will be automatically filled into the Connect to Workspace dialog box.

   
   
   

8. Make sure the authentication is successful and your user name and password or personal access token are automatically filled in the Connect to Workspace dialog box.

9. Click Connect again in the Connect to Workspace dialog box to verify that the connection is successful.

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. Note that if you have only committed some (not all) of the objects, performing Refresh may remove the uncommitted objects.

   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 before you can push the object to the server repository. See the section called “Resolve conflicts” for details.

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.

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.

To specify the executable file of TortoiseGit:

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.

   
   
   

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 TortoiseGit tool displays the revision logs directly.

To edit conflicts:

• Right-click the object with the conflict sign () in the System Tree and select Git Edit Conflicts from the pop-up menu.

  The TortoiseGit tool displays the source control with the conflicts. For more details, see Resolve conflicts.

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.

   
   
   

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.

To create a branch,

1. Right-click the workspace and select Git Create Branch from the pop-up menu.

2. In the Create Branch dialog, input the branch name you want to create, select whether to base the new branch on HEAD or a chosen branch, and click OK.

   To overwrite the branch if a branch with the same name already exists, select the Force if duplicate branch name exists option.

   The branch will be created in your local repository. You can use the Git Push menu to commit the branch to the remote repository on the server, but note that the PBL file(s) will not be uploaded to the server.

To switch to a branch,

1. Right-click the workspace and select Git Switch Branch from the pop-up menu.

2. In the Switch Branch dialog, select the branch you want to switch to and click OK.

   If you switch to a remote branch (in most cases the one starting with "origin/"), you will not be able to commit changes to the remote branch.

   If you get a workspace which was added to Git using a third-party tool such as TortoiseGit, you should commit the entire workspace from the PowerBuilder IDE to Git immediately after you get it; otherwise the object or changes may be lost after you switch the branch.

To view/edit 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 of Workspace dialog box.

3. Select Git from the Source Control System list.

   Git is available from the list when 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”), or when PowerBuilder IDE detects that a .git sub-folder exists.

   
   
   

4. View or change the connection settings for the selected source control system. Note that User ID and Password are used by all workspaces, but the other settings are not.

   User ID and Password/Token: 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 can 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.

To remove/restore the connection settings from the Git source control system:

1. If you select None from the Source Control System list and click OK, PowerBuilder will remove the connection between the workspace and the source control server.

2. If you move the workspace to a new location and then select Git from the Source Control System list and click OK, PowerBuilder will restore connections between the workspace and the source control server.

   Besides that, if a workspace is under source control using a third-party tool such as TortoiseGit, you can open the workspace (make sure the .git sub-folder exists) and then select Git from the Source Control System list to establish connections between the workspace and the source control server in the PowerBuilder IDE. Notice that the objects are marked with this icon which means the objects are not yet under source control in PowerBuilder IDE, so you should commit the entire workspace to add it under source control, and so the "ws_objects" folder is successfully created and uploaded to Git. The "ws_objects" folder is essential for correctly identifying the status of the PowerBuilder objects during the source control management process.