This section provides an overview of source control systems and describes how PowerBuilder integrates with these systems' interfaces.
What source control systems do
Source control systems (version control systems) track and store the evolutionary history of software components. They are particularly useful if you are working with other developers on a large application, in that they can prevent multiple developers from modifying the same component at the same time. You can make sure you are working with the latest version of a component or object by synchronizing the copy of the object you are working on with the last version of the object checked into the source control system.
Why use a source control system
Most source control systems provide disaster recovery protection and functions to help manage complex development processes. With a source control system, you can track the development history of objects in your PowerBuilder workspace, maintain archives, and restore previous revisions of objects if necessary.
Source control interfaces
You work with a source control system through a source control interface in the following ways.
-
PowerBuilder supports working with Subversion (SVN) and Git source control systems through proprietary interfaces provided by source control vendors in the PowerBuilder IDE.
-
PowerBuilder also provides a standard application programming interface to any source control interfaces based on the Microsoft Common Source Code Control Interface Specification, Version 0.99.0823, which means, you can use the PowerBuilder SCC API with any source control system that implements features defined in the Microsoft specification.
-
PowerBuilder also provides a basic check in/check out utility (PBNative) that installs with the product.
PowerBuilder institutes source control at the object level. This gives you a finer grain of control than if you copied your PBLs directly to source control outside of the PowerBuilder SCC API.
PowerBuilder provides native interface options of SVN and Git for directly performing source control operations and functions in the PowerBuilder IDE. After you have configured the connection settings for SVN or Git in your PowerBuilder workspace, you can directly perform the following source control functions by right-clicking the objects in the system tree. The menu item name varies depending on the source control system (SVN or Git) you selected for your current workspace.
Supported SVN and Git version and protocol
The SVN feature has been fully tested against SVN server 1.7.1 and later.
The Git feature has been fully tested against GitHub, and also tested with GitLab, Bitbucket, Bonobo, Perforce, and Team Foundation Server (TFS).
The SVN/Git client that has been fully tested to work is: SVN client 1.9.7 and later, and Git client 2.0 and later.
The protocol of SVN/Git that has been fully tested to work is: HTTP and HTTPS.
PowerBuilder supports TLS 1.1/1.2 for the Git server handshake.
Note
If you use Git repositories to host and collaborate on your code using Team Foundation Server (TFS) or Azure DevOps Server, it is unsupported to connect to your Git repositories through SSH. Please use the recommended Personal Access Token (PAT) approach, where you use your PAT as both your username and password in PowerBuilder for Git connection.
|
Source control system |
Menus available in PowerBuilder IDE |
Used in operations |
|---|---|---|
|
SVN |
Connect to Workspace |
Connects with the SVN source control server and the project, and downloads the project to the workspace. See the section called “Get a workspace from SVN” for details. |
|
Add to Source Control |
Connects with the SVN source control server and uploads the workspace to the source control server. See the section called “Add a workspace to SVN” for details. |
|
|
SVN Commit |
Adds an object to the SVN source control server if the object does not exist on the server, or commit the changes to the server if the object has already been added to the server, or delete the object from the server if the local copy has already been deleted. See the section called “Commit objects to SVN” for details. |
|
|
SVN Update |
Gets the object from the SVN source control server if the object does not exist on the local machine, or update the local copy if the object already exists on the local machine. See the section called “Get objects from SVN” for details. |
|
|
SVN Resolve |
Removes the conflicted state of the local copy and commit it again. You will have to manually resolve the conflicts before using this menu. See the section called “Resolve conflicts” for details. |
|
|
SVN Revert |
Undoes any changes to the local copy and restores to the version on the source control server. See the section called “Revert changes” for details. |
|
|
SVN Get/Release Lock |
Locks the object in the SVN source control server so that other users cannot commit changes to the object. See the section called “Lock objects” for details. |
|
|
SVN Diff |
Compare an object in your local directory with the version of the object that was last synchronized with the source control server. See the section called “Compare objects” for details. |
|
|
SVN Show Log |
Displays the revision logs that are input during commit. See the section called “Show logs” for details. |
|
|
Open Containing Folder |
Opens the folder that contains the object. |
|
|
Git |
Connect to Workspace |
Connects with the Git source control server and the project, and downloads the project to the workspace. See the section called “Get a workspace from Git” for details. |
|
Add to Source Control |
Connects with the Git source control server and uploads the workspace to the source control server. See the section called “Add a workspace to Git” for details. |
|
|
Git Commit |
Adds an object to the local repository if the object does not exist on the local repository, or commit the changes to the local repository if the object has already been added to the local repository, or delete the object from the local repository if the local copy has already been deleted. See the section called “Commit objects to Git” for details. |
|
|
Git Push |
Commits the objects from the local repository to the remote repository on the source control server. See the section called “Commit objects to Git” for details. |
|
|
Git Pull |
Gets the object from the Git source control server if the object does not exist on the local repository, or update the local copy if the object already exists on the local repository. See the section called “Get objects from Git” for details. |
|
|
Git Revert |
Undoes any changes to the local copy and restores to the version on the source control server. See the section called “Revert changes” for details. |
|
|
Git Resolve |
Removes the conflicted state of the local copy and commit it again. You will have to manually resolve the conflicts before using this menu. See the section called “Resolve conflicts” for details. |
|
|
Git Diff |
Compare an object in your local directory with the version of the object that was last synchronized with the source control server. See the section called “Compare objects” for details. |
|
|
Git Show Log |
Displays the revision logs that are input during commit. See the section called “Show logs” for details. |
|
|
Open Containing Folder |
Opens the folder that contains the object. |
The PowerBuilder SCC API works with the source control system to perform certain source control operations and functions. Other source control operations must be performed directly from the source control management tool. After you have defined a source control connection profile for your PowerBuilder workspace, you can open the source control manager from the Library painter.
To start the source control manager from PowerBuilder
-
Select Entry>Source Control>Run Source Control Manager from the Library painter menu bar.
The menu item name varies depending on the source control system you selected in the source control connection profile for your current workspace. There is no manager tool for the PBNative check in/check out utility.
For information on configuring a source control connection profile, see Setting up a connection profile.
Which tool to use
The following table shows which source control functions you should perform from the source control manager and which you can perform from PowerBuilder:
Tool or interface
Use for this source control functionality
Source control manager
Setting up a project*
Assigning access permissions
Retrieving earlier revisions of objects*
Assigning revision labels*
Running reports*
PowerBuilder SCC API
Setting up a connection profile
Viewing the status of source-controlled objects
Adding objects to source control
Checking objects out from source control
Checking objects in to source control
Clearing the checked-out status of objects
Synchronizing objects with the source control server
Refreshing the status of objects
Comparing local objects with source control versions
* You can perform these source control operations from PowerBuilder for some source control systems.
PowerBuilder also provides minimal in-the-box source control through the PBNative check in/check out utility. PBNative allows you to lock the current version of PowerBuilder objects and prevents others from checking out these objects while you are working on them. It provides minimal versioning functionality, and does not allow you to add comments or labels to objects that you add or check in to the PBNative project directory.
Connecting to PBNative
You connect to PBNative from PowerBuilder through the PowerBuilder SCC API. You use the pop-up menu items to add, check out, check in, or get the latest version of objects on the source control server. However, any menu item that calls a source control management tool is unavailable when you select PBNative as your source control system.
Because there is no separate management tool for PBNative, if you need to edit project PBG files that get out of sync, you can open them directly on the server without checking them out of source control.
For more information about PBG files, see Editing the PBG file for a source-controlled target.
PRP files
PBNative creates files with an extra PRP extension for every object registered in the server storage location. If an object with the same file name (minus the additional extension) has been checked out, a PRP file provides the user name of the person who has placed a lock on the object. PRP files are created on the server, not in the local path.
PowerBuilder also adds a version number to the PRP file for an object in the PBNative archive directory when you register that object with PBNative source control. PowerBuilder increments the version number when you check in a new revision. The version number is visible in the Show History dialog box that you open from the pop-up menu for the object, or in the Library painter when you display the object version numbers.
For more information on the Show History dialog box, see Displaying the source control version history. For information on displaying the version number in the Library painter, see Controlling columns that display in the List view.
Using Show Differences functionality with PBNative
PBNative has an option that allows you to see differences between an object on the server and an object on the local computer using a 32-bit visual difference utility that you must install separately. For information on setting up a visual difference utility for use with PBNative, see Comparing local objects with source control versions.
Any object added or checked into source control should be usable by all developers who have access permissions to that object in source control. This requires that the local paths for objects on different computers be the same in relation to the local root directory where the PowerBuilder workspace resides.
Best practices
The source control administrator should decide on a directory hierarchy before creating a source-controlled workspace. The following practices are highly recommended for each target under source control:
-
Create a top-level root directory for the local project path on each developer workstation.
This directory becomes the project path in the SCC repository. The local workspace object (PBW), the offline status cache file (PBC), the source control log file, and any Orcascript files used to rebuild and refresh the source-controlled targets should be saved to this top-level directory on local workstations
-
Create a unique subdirectory under the project path for each PBL in the source-controlled targets
This practice avoids issues that can arise if you copy or move objects from one PBL to another in the same target.
-
Instruct each developer on the team to create a workspace object in the top-level directory and, on the Source Control tab of the Properties of Workspace dialog box, assign this directory as the "Local Project Path". Each developer must also assign the corresponding top-level directory in the SCC repository in the "Project" text box of the Source Control tab for the workspace
-
Add target files (PBT) to the project path directory or create unique subdirectories under the project path for each target file
Before developers can start work on PowerBuilder objects in a workspace under source control, a project manager usually performs the following tasks:
-
Sets up source control projects (and archive databases)
-
Assigns each developer permission to access the new project
-
Sets up the directory structure for all targets in a project
Ideally, the project manager should create a subdirectory for each target. Whatever directory structure is used, it should be copied to all computers used to check out source-controlled objects.
-
Distributes the initial set of PBLs and target (PBT) files to all developers working on the project or provides a network location from which these files and their directory structure can be copied.
PowerScript and .NET targets require that all PBLs listed in a target library list be present on the local computer. For source control purposes, all PBLs in a target should be in the same local root path, although they could be saved in separate subdirectories. PBWs and PBLs are not stored in source control unless they are added from outside the PowerBuilder SCC API. They cannot be checked into or out of source control using the PowerBuilder SCC API.
If you are sharing PBLs in multiple targets, you can include the shared PBLs in a workspace and in targets of their own, and create a separate source control project for the shared objects. After adding (registering) the shared PBL objects to this project, you can copy the shared targets to other workspaces, but the shared targets should not be registered with the corresponding projects for these other workspaces. In this case, the icons indicating source control status for the shared objects should be different depending on which workspace is the current workspace.
For small projects, instead of requiring the project manager to distribute PBLs and target files, developers can create targets in their local workspaces having the same name as targets under source control. After creating a source control connection profile for the workspace, a developer can get the latest version of all objects in the workspace targets from the associated project on the source control server, overwriting any target and object files in the local root path. (Unfortunately, this does not work well for large PowerScript or .NET projects with multiple PBLs and complicated inheritance schemes.)
Ongoing maintenance tasks of a project manager typically include:
-
Distributing any target (PBT) files and PBLs that are added to the workspace during the course of development, or maintaining them on a network directory in an appropriate hierarchical file structure
-
Making sure the PBL mapping files (PBGs) do not get out of sync
For information about the PBG files, see Editing the PBG file for a source-controlled target.
Connections from each development computer to the source control project can be defined on the workspace after the initial setup tasks are performed.
Developers' tasks
Each user can define a local root directory in a workspace connection profile. Although the local root directory can be anywhere on a local computer, the directory structure below the root directory must be the same on all computers that are used to connect to the source control repository. Only relative path names are used to describe the location of objects in the workspace below the root directory level.
After copying the directory structure for source-controlled PowerScript or .NET targets to the local root path, developers can add these targets to their local workspaces. The target objects can be synchronized in PowerBuilder, although for certain complex targets, it might be better to do the initial synchronization through the source control client tool or on a nightly build computer before adding the targets to PowerBuilder. (Otherwise, the target PBLs may need to be manually rebuilt and regenerated.)
For more information about getting the latest version of objects in source control, see Synchronizing objects with the source control server.
Status determination by version number
PowerBuilder provides third-party SCC providers with an extension to the SCC API that allows them to enhance the integration of their products with PowerBuilder. Typically, calls to the SccDiff method are required to determine if an object is out of sync with the SCC repository. (This is not appropriate for Perforce or ClearCase.)
However, SCC providers can implement SccQueryInfoEx as a primary file comparison method instead of SccDiff. The SccQueryInfoEx method returns the most recent version number for each object requested. This allows PowerBuilder to compare the version number associated with the object in the PBL with the version number of the tip revision in the SCC repository in order to determine whether an object is in sync.
Since SccQueryInfoEx is a much simpler request than SccDiff, the performance of the PowerBuilder IDE improves noticeably when this feature is implemented by the SCC provider. For these providers, the SccDiff call is used as a backup strategy only when a version number is not returned on an object in the repository. Also for these providers, the version number for registered files can be displayed in the Library painter.
For more information on viewing the version number, see Controlling columns that display in the List view.
Once the new API method is implemented in an SCC provider DLL and exported, PowerBuilder automatically begins to use the SCCQueryInfoEx call with that provider. The SccQueryInfoEx method is currently used by PBNative.
Overriding the version number
For source control systems that support the SccQueryInfoEx method, you can manually override the version number of local files, but only for PowerScript objects, and only when you are connected to source control.
This can be useful with source control systems that allow you to check out a version of an object that is not the tip revision. However, the source control system alone decides the version number of the tip revision when you check a file back into source control. It is the version returned by the source control system that gets added to the PBC file for the workspace and to the PBLs in the local directory.
For more information about the PBC file, see Working in offline mode.
You change the local version number for a source-controlled PowerScript object in its Properties dialog box, which you access from the object's pop-up menu in the System Tree or the Library painter. If the source control system for the workspace supports the SccQueryInfoEx method and you are connected to source control, the Properties dialog box for a source-controlled PowerScript object (other than a PBT) has an editable SCC Version text box. The SCC Version text box is grayed if the source control system does not support the SccQueryInfoEx method or if you are not connected to source control.
Local change only
The version number that you manually enter for an object is discarded on check-in. Only the source control provider decides what number the tip revision is assigned.
