Collaborator seamlessly integrates with the Subversion version control system. This section provides a general overview of integration preferences, ways to review files controlled by Subversion, and so on.

About Integration

Using the built-in Collaborator Subversion 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:

Locally changed files from a working copy.
Files from revisions.
Arbitrary Subversion diffs.
Differences between revisions.
Differences between branches or tags.
Differences between dates.

Subversion integration uses Subversion client applications that are already installed on the client computer. That is, integration supports all protocols, authentication settings, proxies, and other configuration specifics.

Supported Versions

To enable the integration via GUI Client and Command-Line Client, you need the Subversion command line client (svn.exe) to communicate with the Subversion server. We support Subversion 1.4.x - 1.14.2. For versions 1.3.x and earlier, only the ccollab addsvndiffs command is supported.

The TortoiseSVN client is not supported without the Command line client tools option.

Eclipse Plug-in integrates with the Subclipse and Subversive plugins. The following versions are supported:

Subclipse 1.6.x
Subclipse 1.4.x
Subversive 4.x (SVN Connector 6.x)

Ways of Integration

You can enable the integration between Collaborator and Subversion for GUI Client, Command-Line Client, Eclipse Plug-in or Collaborator server.

GUI Client

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. This step is obligatory if you plan to use the Add Changes functionality.
Select Subversion in the SCM drop-down list.

Several options will become available. These are specifically tailored to configure Subversion integration.

Option	Description
svn Executable	A full path referring the Subversion executable (svn.exe).
Repository URL	An URL of the Subversion repository.
Username	A user-name you want Collaborator to use on connecting to the Subversion repository.
Password	A password you want Collaborator to use on connecting to the Subversion repository.
Require Client Certificate Password	If selected, asks for the SSL Client Certificate password on connecting to the Subversion repository.
Automatically add unversioned files	If selected, treats the unversioned files as added to the repository.
Recurse in to 'externals' directories	If selected, recurses the files in the svn:externals directories as if these are part of the same repository.

Once ready, click Validate to make sure the integration is operational.

After that, a new configuration for Subversion will appear on the main screen of the GUI Client.

Select it, then click on the corresponding button depending on what you want to do next:

Add Changes – Upload files in a Subversion working copy to the Collaborator server and add these to a review.

Add Revisions – Upload committed revisions to the Collaborator server and add these to a review. All modified files in the selected revisions will be uploaded.

In the dialog, you can select whether you want it to display all available Revisions, input IDs of specific Revisions, Revisions within a specific range or date interval.

Filter will return 100 newest Revisions for ID and date range requests.

Add Subversion Diffs – Upload arbitrary Subversion diffs to the Collaborator server and add these to a review.

On the Revisions tab, you can upload the difference between two revisions.

On the Branches tab, you can upload the difference between two branches or tags.

On the Dates tab, you can upload the difference between two dates.

Command-Line Client

In the Command-Line Client, you can create a review for various activities and files controlled by Subversion.

Commands recommended for Subversion

ccollab addchanges - Attaches locally-modified files to a review.

ccollab addchangelist - Attaches an atomic changelist to a review.

ccollab addsvndiffs - Uploads diffs generated from the svn diff command.

ccollab commit - Commit changes in the review.

The addchanges command will upload local changes to files controlled by Subversion before they are checked into version control.

The addchangelist command will upload committed Subversion revisions. The changelist ID is the Subversion Revision number. All the files involved in the Revision are uploaded.

In most cases, the Command-Line Client can automatically detect your Subversion configuration. Try testing your configuration to verify the configuration is detected correctly.

If the Command-Line Client is unable to detect your Subversion configuration or you want to override the detected settings, you can manually specify Subversion settings using global options.

To manually configure the Command-Line Client to use Subversion, execute the following command:

ccollab set scm subversion

Subversion-specific Options

Option	Description
--svn-exe <value>	Full path to the "svn" command-line executable.
--svn-look-exe <value>	Full path to the "svnlook" command-line executable (used by Subversion triggers).
--svn-repo-url <value>	Subversion repository URL.
--svn-user <value>	Subversion user name.
--svn-passwd <value>	Subversion password.
--svn-require-client-certificate-password <value>	Use this if you have a non-empty and unsaved password for your SSL Client Certificate.
--svn-auto-add	Treat unversioned files as if they had been added to Subversion.
--svn-recurse-externals	Recurse in the "svn:externals" directories as if they were part of the same repository.
--svn-repo-path <value>	Full path to the repository (used by Subversion Triggers).

Note: If you want to review committed Subversion revisions but you do not have a working copy checked out, you must configure your Subversion URL using svn-repo-url.

Eclipse Plug-in

You can upload locally modified Subversion files to a review directly from Eclipse Plug-in, since it integrates with the Subclipse and Subversive plugins.

To learn more, please see Add to Review Wizard.

Web Client

Collaborator administrator can configure the Collaborator server to communicate directly with Subversion repositories. Server-side integration allows users to upload committed atomic changelists (revisions in terms of Subversion) from the Web Client without having to install and configure client-side tools.

To upload changelists:

Log in to Web Client.
Create a new review, or open an existing one.
Scroll to the Review Materials section of the Review Screen.
Click Upload button and then select the item corresponding to the desired repository.

Note: Item titles are specified by your Collaborator administrators and they will vary from those in the image below.
In the ensuing dialog, specify the IDs of desired changelists. Separate multiple IDs by space character.
Click Attach to upload the specified changelists to the review.

Configure Server-Side Integration

To enable the feature, your Collaborator administrator will need to perform the following actions:

Install and configure a Subversion client on the Collaborator server.
Log in to Collaborator server.
On the Collaborator main toolbar, click ADMIN, and then select Version Control from the tree on the left. Then switch to the Version Control Servers tab.

This tab lists available version control server configurations. They could be created manually, as described bellow, or could be created automatically when one of the client programs uploads files from a server that does not match any of the currently configured servers.
Select "Subversion" from the SCM System drop-down list and click Create.

Specify the values for the following properties:

Option	Description
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 URL the client used to connect to the Subversion server.
Attach changelists from browser	If enabled, this feature lets users select committed revisions to review directly from the web browser, without having to install any client programs.
svn Executable	Full path to the svn.exe executable.
Repository URL	Subversion repository URL. When a version control server entry is created automatically, this is filled in with the URL the client used to connect to the Subversion server.
Username	The username to use when querying the specified Subversion server. Collaborator will use this account no matter who is logged in.
Password	The password to use.

Click Test Connection to verify that the connection between Collaborator server and your Subversion server is established successfully and is trusted. For example, you might need to generate and/or accept trust certificates and so forth.

If you get the Untrusted certificate authority error, this is probably because your Subversion server is using a self-signed certificate. You can click Accept Certificate to tell Collaborator to permanently accept the certificate.

The Client Configuration Mapping section defines correspondence between files uploaded by the various Collaborator clients and this server-side Subversion configuration.

Specify Java-style regular expressions to map changelists uploaded from our client tools to this Subversion server:

Option	Description
Repository URL Pattern	Match on the configured repository URL of the client. This is not very reliable because clients may have various network configurations that make the URL look different. It is usually far better to use the Repository UUID Pattern.
Repository UUID Pattern	Match on the `Repository UUID` returned from running the `svn info` command. This is a unique ID generated by every Subversion repository, and usually works perfectly for identifying uploads to this Subversion server. When a version control server entry is created automatically, this is filled in with `Repository UUID` obtained from the client.

Press Save to create configuration and enable server-side integration with this Subversion repository.

Subversion Triggers

This section provides a reference on the triggers specific to Collaborator, added to Subversion by Collaborator Subversion integration package.

Triggers recommended for Subversion

ccollab admin trigger ensure-review-started - Changelist cannot be submitted until review of this changelist exists.

ccollab admin trigger ensure-reviewed - Changelist cannot be submitted until review of this changelist has been completed.

ccollab admin trigger create-review - Creates a new Review for a changelist if no Review already exists.

The ensure-review-started and ensure-reviewed hooks ensure that files cannot be committed unless certain conditions are met. If a user attempts to commit files that do not meet those conditions, an error message describing the unfulfilled conditions will be displayed and the files will not be committed. If the conditions are met, the commit will be allowed to continue normally. The ensure-review-started hook requires that the review exist; ensure-reviewed requires that the review be completed.

The create-review hook automatically creates a review in Collaborator after the revision is committed to the Subversion server. Because you can supply the regular expression for identifying reviews, you can provide users with the ability to review before check-in without having an additional review automatically created after the check-in. This way some groups (or just some check-ins arbitrarily) can use pre-commit review and others post-commit, and either way you know all code has been reviewed or at least that a review of all code exists in the system.

Linking reviews with commits

To use the ensure-review-started and ensure-reviewed hooks, you must first require developers to put the review ID somewhere in the Subversion commit message (also optionally for the create-review hook). The format of this text is completely up to you; you will need to supply a Java-style regular expression that identifies this text and specifically calls out the review ID inside that text. The regular expression is specified using the --review-id-regex hook command option.

Here are some common ways of specifying the review ID and the corresponding regular expressions. Note that regular expressions are case-insensitive and you must identify the review ID portion with parenthesis:

`Text`	`--review-id-regex`
`Review: 4233`	`review:\s*(\d+)`
`rID4233`	`rid(\d+)`
`(review 4233)`	`\(review (\d+)\)`

This text can appear in-line with other text or in a more formal "form-style" layout. Because you control the regular expression, you can control exactly what this looks like.

For more information about Subversion hooks in general, see the Subversion documentation.

Support for Directories

Collaborator partially supports concept of directories (not just files) being altered that Subversion provides.

All the files in directories in question will be scanned, uploaded and represented properly in the Collaborator GUI. The directories themselves will not be shown, or even in the file list confirmation screen presented by the command-line client.

This works correctly even in cases, when you move a parent directory and change, add or delete a file in that directory. In the review, you will get the correct content for the file, but the directory itself will not be listed.

Note:

This limitation affects commit functionality. If a directory and a file in it were included in a review and then modified, the Collaborator client will not be able to commit them automatically. The workaround is to commit the changes manually and then dismiss the commit action item.

Support for SVN+SSH

The Collaborator clients support running Subversion over SSH (the svn+ssh:// protocol). On some systems, especially those under Unix, Mac OS X, or Cygwin/Windows, this will probably work correctly.

If your SSH connection displays a banner, this will interfere with the client being able to parse the Subversion output correctly. We would recommend suppressing banner output by adding the -q option to your SSH executable:

svn_ssh = ssh -q

You can also try to create a local SSH configuration file and add the following line to it:

LogLevel QUIET

On some Windows computers, you might have to configure Subversion to default to your SSH client. To do this:

Go to the <Documents and Settings>\username\Application Data\Subversion folder, and open the config file for editing.
In the [tunnels] section of this file, find a line that starts with ssh=.
In the line, specify your SSH client. For example:

ssh = "C:\\Program Files\\PuTTY\\Plink.exe" -l <your username>

Note: It is important to use double slashes.

Support for Symlinks

Collaborator partially supports versioning symlinks in Subversion. If a committed revision contains a symlink, and you attached this revision to a review, Collaborator will be able to display the symlink contents correctly. However, if a symlink was added to a review before you commit the changes to Subversion, Collaborator displays an incorrect content for the symlink (the symlink will be traversed).

Changes to Properties

Collaborator does not support reviews of the changes made to Subversion properties.

Technical Details and Limitations

Review Screen, Diff Viewer, Eclipse Plug-in and Visual Studio Extension display atomic changelists (revisions in terms of Subversion) in chronological order (from older to newer), regardless the order in which they have been uploaded to review.

Collaborator does not guarantee that Diff Viewer will display correct comparison results for the following cases:

If you have "gaps" while adding subsequent atomic changelists (revisions in terms of Subversion) to the same review. For example, add changelists 1, 2, and 4, but forget to add changelist 3.
If you add several diffs (non atomic changelists) to the same review.

Known Issue

Error messages about inconsistent line ending style indicate that the files being processed on have mixed line endings (typically Unix and DOS-style) and that one or more of them has the subversion property svn:eol-style set to native. This is a fatal error, as Subversion stops processing when the condition is found.

The fix is to either force the line endings to a consistent state (that is, typically either all unix or all DOS-style) or set the svn property to the proper value if there is a need for mixed line endings. A variety of methods are available to automate conversion of line ending styles – for example, the free unix2dos/dos2unixutility utility.

Subversion Integration