Collaborator seamlessly integrates with the Perforce version control system. This section provides a general overview of integration preferences, ways to review files controlled by Perforce, and so on.
Using the built-in Collaborator Perforce integration, you can quickly upload various files to the Collaborator server to create a review directly from the desktop client of your choice. The types of files you can upload include:
Perforce integration uses Perforce client applications that are already installed on the client computer. That is, integration supports all protocols, authentication settings, proxies, and other configuration specifics. This includes configuration from environment variables, $P4CONFIG files,
p4 set registry values, and so on.
You can enable the integration between Collaborator and Perforce for GUI Client, Command-Line Client, Eclipse Plug-in, Collaborator server, or use the integration in the p4v and p4win client applications.
To enable the integration:
Start GUI Client.
Click Add to create a new SCM configuration.
In the subsequent SCM Configuration dialog, specify the local source code location.
Select Perforce in the SCM drop-down list.
Several options will become available. These are specifically tailored to configure Perforce integration.
|P4 Executable||A full path referring the p4 executable.|
|P4PORT||A p4port required to connect to the perforce server.|
|P4USER||A username you want Collaborator to use on connecting to the Perforce server.|
|P4PASSWD||A password you want Collaborator to use on connecting to the Perforce server.|
|P4CLIENT||A mapping string used to transfer Perforce server data to the local machine.|
|Ignore Integration History||If selected, integration will ignore the integration history wile calculating the predecessor changelist.|
|P4CHARSET||A Perforce character set used for translation of Unicode files.|
|Require empty default changelist||If selected, does not allow to upload if the default changelist contains any files.|
|Specify Perforce command charset||If selected, requires a character set to be specified on connecting to the Perforce server.|
Once ready, click Validate to make sure the integration is operational.
After that, a new configuration for Perforce will appear on the main screen of the GUI Client.
Add Pending Changelists – Upload files in a Perforce pending changelist to the Collaborator server and add these to a review.
|Note:||You cannot upload the default changelist.|
Add Submitted Changelists – Upload files in a Perforce submitted changelist to the Collaborator server and add these to a review.
Add Perforce Diffs – Upload arbitrary Perforce diffs to the Collaborator server and add these to a review.
In the Command-Line Client, you can create a review for various activities and files contolled by Perforce.
ccollab addchangelist - Attaches an atomic changelist to a review.
ccollab addp4diffs - Uploads diffs generated from
p4 diff2 command.
ccollab addversions - Attaches any 2 given versions to a review.
ccollab commit - Commit changes in the review.
ccollab addp4job - Adds all numbered local changes that fix a job to the review.
ccollab admin syncusers - Synchronizes the Perforce user list with the Collaborator server.
ccollab admin changelist update-id - Updates the changelist ID so Collaborator reflects the renumbered Perforce changelist ID.
addchangelist command will upload Perforce changelists into Collaborator. You can upload changelists either before or after they are submitted, but you cannot upload the default changelist.
In most cases, the Command-Line Client can automatically detect your Perforce configuration. Try testing your configuration to verify the configuration is detected correctly.
If the Command-Line Client is unable to detect your Perforce configuration or you want to override the detected settings, you can manually specify Perforce settings using global options.
To manually configure the Command-Line Client to use Perforce, execute the following command:
Full path to the P4 executable.
How to connect to the Perforce server.
Perforce user name.
Perforce password or ticket.
Mapping of Perforce server data to the local machine.
Ignore integration history when calculating predecessor.
Perforce character set used for translation of Unicode files.
If true, do not allow uploads if the default changelist contains files.
Should a character set be specified for communication with Perforce.
If your Perforce server requires ticket-based authentication (server security level 3), then the configured p4-password will be used to automatically issue the p4-login and acquire a new ticket as necessary.
Note for Windows users: Sometimes Perforce server uses Windows machine host name as a default name, ignoring the real Perforce client name. To avoid that issue, specify the needed Perforce client name directly in the Collaborator with the
--p4client <name> command.
You can upload locally modified Perforce files to a review directly from Eclipse Plug-in. Right-click on any changelist entry in Eclipse, either before or after it is submitted.
To learn more, please see Add to Review Wizard.
The Collaborator client installer includes an integration point with P4V and P4Win clients.
If you installed the client yourself and decided to configure addons to Perforce visual tools, then you can skip the manual configuration of the integration. However, if the Collaborator client was installed by an administrator on your computer, or the configuration failed at install time, you can manually configure them.
Go to Tools.
Click Manage Custom Tools.
In the subsequent dialog, click Import Tools.
Navigate to the Collaborator client installation directory and select one of the following files:
Go to Tools.
Navigate to the Collaborator client installation directory and select the P4Win-Tools-Import.txt file.
|The plug-ins will work only if the Perforce command-line tool (p4) is in your PATH environment variable.|
Once configured, integration allows to create Collaborator reviews for pending and submitted changelists directly from the P4V or p4Win client.
The P4V and P4Wind plugins are able to work with multiple Perforce workspaces and servers. All the Perforce connectivity parameters are taken from the UI, so whatever workspace, server, and authentication you are currently using when you right-click the item the plugin will be able to handle the integration automatically. None of this affects the behavior or configuration of the command line client, so you can freely use the plug-ins without disturbing that configuration.
For any issues with the P4V and P4Win plugins, provide a debugging log to the SmartBear support. To do this, edit the custom tool configuration (Tools > Manage Custom Tools > Edit), and add a
--debug argument to the beginning of the arguments list. This will create a log file at the following location: ~/.smartbear/log/ccollab.log on Unix platforms and %USERPROFILE%/.smartbear/log/ccollab.log on Windows platforms.
Please contact our technical support and send the log file along with a full description of what you were trying to do when the error occurred.
The Collaborator server can be configured to communicate directly with your Perforce server. This allows users to review submitted changelists completely from the browser, without having to install any client programs.
To enable this feature:
Install and configure a Perforce client on the Collaborator server.
Go to the Version Control tab of the administration interface.
Once there, create an entry for your Perforce server.
|Tip:||Entries are also appear automatically if one of the client programs uploads files from a server that does not match any of the currently configured servers.|
Please refer to the following table to configure the integration properly:
|Title||The title is displayed to users, so it should be something that everyone will understand, even if they are going through proxies, VPNs, or other such things. When a version control server entry is created automatically, this is filled in with the server address (p4port) of the server.|
|Attach changelists from browser||If enabled, this feature lets users select submitted changelists to review directly from the web browser, without having to install any client programs.|
|P4 Executable||Full path to the P4 executable.|
|P4PORT||Address to use to connect to the server. When a version control server entry is created automatically, this is filled in with the server address obtained from the client.|
|P4USER||Perforce user name.|
|P4PASSWD||Perforce password or ticket.|
|P4CHARSET||Perforce character set used for translation of Unicode files.|
The Collaborator server can be configured to check Perforce protections with the Perforce server whenever a user tries to access a file.
When enabled, Collaborator will check access permission with your Perforce server whenever a user tries to access the content of a file managed by this server. Note that this assumes that the user's Perforce username is the same as their Collaborator login.
To check Perforce protections the configured P4USER must have Perforce superuser permissions. If you do not want to provide an account with that level of permission, you can instead configure a script for Collaborator to run instead of calling
'p4 -s protects' directly.
The script will be passing arguments
"-p <p4port> -u <user> -h <host> <depotPath>". For example, this script could be implemented as a Windows batch file:
|The script must produce exactly the same stdin, stdout, and process error code as if Collaborator ran
You can supply Java-style regular expressions to map changelists uploaded from our client tools to this Perforce server. It is important to set up these regular expressions so that files uploaded by the various Collaborator client tools are correctly associated with this server-side Perforce configuration.
|P4PORT Pattern||Match on the client configured P4PORT. Using the Server Address Pattern is better, but clients before 5.0.5009 did not upload server address, so you can configure this as a fallback.|
|Server Address Pattern||
Match on the server address returned from running
To enable the integration via GUI Client and Command-Line Client, you need the Perforce command line client (p4) to communicate with the server. We support all client and server versions later than 2002.1.
Eclipse Plug-in can use the Perforce plugin for Eclipse starting from version 2009.2.234487 and later.
This section provides a reference on the triggers specific to Collaborator, added to Perforce by Collaborator Perforce Server integration package.
||Ensures that a review has been started (created in Collaborator) for the submitted changelist.|
||Ensures that a review has been completed for the submitted changelist.|
||Ensures that a review has been completed for the submitted changelist, and that the changelist was not changed after the review was over (that is, that the file contents and the file list are the same).|
||Appends or updates review-specific information in a changelist's description.|
For general information on Perforce triggers, see Perforce System Administrator's Guide.
Perforce nearly always renumbers changelists upon submission, but when you are doing pre-commit reviews, Collaborator always has the pre-submit number. We have included a script you can customize that will ask Perforce what was a number of the changelist before it was submitted, and update changelists in Collaborator to have the new number. This requires a Collaborator client and server 5.0.5005 or better, and a Perforce client and server 2007.3 or later. This script is intended to be run periodically via
cron or a similar task scheduler.
Collaborator fully supports file branching and integration semantics of Perforce.
If files in a changelist are marked for branching, they are not considered changed. The file content itself is not changed; only the file paths are being changed.
If files in a changelist are being integrated, this works just like a regular change. Many customers choose to review integrations especially carefully since the changes might interact in unexpected ways.
Collaborator fully supports file copy and move semantics of Perforce. If a file is copied or moved rather than added from scratch, it will show up that way in the various user interfaces.
Collaborator partially supports Perforce directories and correctly handles the changes you apply to these.
All files underneath the directories in question will be scanned, uploaded, and represented properly in the GUI. The directories themselves will not be shown in any GUI.
Collaborator supports adding Perforce shelvesets to reviews.
If you want to use the Mark for Delete on a file and add this file to the newly created Collaborator review, synchronize this file with the depot. Otherwise, this file can be absent from your Perforce workspace and Collaborator will return an exception.