Users Guide
Using Source Control

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

1. Right-click the workspace/solution 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/solution and click OK.

   
   
   

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

   For the workspace, you can also 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/solution that are not currently under source control. You cannot add files that are already under source control.

   For the workspace, 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. (For the solution, there is no "ws_objects" sub-folder created.)

   
   
   

4. In the Add to Source Control dialog box, select the files and folders (and also ws_objects if it is a workspace) 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.

   Note

   When you add files to the Git source control server, and encounter the following error, you can follow instructions in the section called “Failed to add files to Git repository” in PowerBuilder Troubleshooting Guide to resolve the error.

   Git detail error info: Repository path 'C:/Users/Public/Documents/Appeon/PowerBuilder 25.0/Code Examples/Example Sales App/' is not owned by current user
   Git client error code: -36
   Failed to add files to repository.

5. Right-click the workspace/solution 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/solution. 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/solution is automatically displayed in the Workspace/Solution 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/solution from the Git source control system:

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

   or

   Select Connect to Workspace/Solution from the File menu.

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

2. Select the Workspace or Solution tab.

3. Select Git from the Source Control System list.

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

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

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

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

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

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

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

11. In the Workspace tab, you can also 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.

    
    
    

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

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

    Note

    After you get a workspace/solution 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/solution 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/Solution dialog box.

1. In the Connect to Workspace/Solution 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 or Solution File box, type in the name of the workspace/solution file to be downloaded from the repository. Note that the workspace/solution 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/Solution 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/Solution dialog box.

9. Click Connect again in the Connect to Workspace/Solution 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/solution, as described in the next step.

3. Right-click the workspace/solution 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/solution (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/solution level, and is not available at the target/project or library levels.

  PowerBuilder starts downloading the new objects or changed objects from the Git source control system to the local workspace/solution. 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.

  Note

  In the solution format, it is unsupported to revert the OLE of a deleted object (you can only use the SVN or Git tool to revert the corresponding .bin file).

  Be sure to revert the .pblmeta file at the same time, and merge the file properly whenever necessary.

To specify the executable file of TortoiseGit:

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

2. In the Properties of Workspace/Solution 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/solution, target/project, 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/solution in the System Tree and select Properties from the pop-up menu.

2. In the Properties of Workspace/Solution 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/solution 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 before clicking OK.

   To switch to this branch after creation, select the Switch to new branch option before clicking OK. This will automatically change your working directory to the newly created branch, allowing you to start making changes right away without needing to switch branches manually later.

   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) in the workspace will not be uploaded to the server.

   
   
   

To switch to a branch,

1. Right-click the workspace/solution 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 want to create a new branch while switching, you can select the Create new branch option in the dialog. This allows you to specify a name for the new branch and choose whether to base it on the current branch or another existing branch. Once you click OK, the new branch will be created, and your working directory will automatically switch to this new branch. If you encounter a situation where a branch with the same name already exists, you can select the Force if duplicate branch name exists option. This will overwrite the existing branch with the new one you are trying to create, ensuring you can proceed without conflicts.

   If you get a workspace/solution which was added to Git using a third-party tool such as TortoiseGit, you should commit the entire workspace/solution 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 merge branches,

Once you have completed work on a feature branch and are ready to integrate those changes, follow these steps to merge branches:

1. Switch to the branch you want to merge changes into (e.g. master).

2. Ensure your target branch is up to date with the remote repository (by right-clicking the workspace/solution and select Git Pull from the pop-up menu).

3. Now you can merge the feature branch into the target branch. Right-click the workspace/solution and select Git Merge from the pop-up menu.

4. In the dialog box that appears, choose the feature branch (local or remote) you want to merge.

   You can input a message summarizing the changes being merged in the Merge message text field.

   You can also select the Squash option to combine all commits from the feature branch into a single commit on the target branch. This can keep the commit history clean and focused, as it merges multiple changes into one cohesive commit.

5. Resolve conflicts (if necessary). If there are conflicts, the affected objects will be marked with a "!" sign () in the library tree. You will need to manually resolve these conflicts by right-clicking the conflicted object and selecting Edit Conflicts.

6. After resolving any conflicts, commit the changes by right-clicking the target branch and selecting Git Commit.

7. Finally, push the merged changes to the server repository by right-clicking the target branch and selecting Git Push from the pop-up menu.

   
   
   

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

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

2. Select the Source Control tab in the Properties of Workspace/Solution dialog box.

3. Select Git from the Source Control System list.

   Git is available from the list when the current workspace/solution is under the Git source control, for example, after the workspace/solution is uploaded to Git using the Add to Source Control menu (see the section called “Add a workspace/solution to Git”), or after the workspace/solution is downloaded from Git using the Connect to Workspace/Solution menu (see the section called “Get a workspace/solution 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/solutions, 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/solution and the source control server.

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

   Besides that, if a workspace/solution is under source control using a third-party tool such as TortoiseGit, you can open the workspace/solution (make sure the .git sub-folder exists) and then select Git from the Source Control System list to establish connections between the workspace/solution 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/solution to add it under source control, and so the "ws_objects" folder (required by the workspace) is successfully created and uploaded to Git. The "ws_objects" folder is essential for the workspace to correctly identify the status of the PowerBuilder objects during the source control management process.