Applies to Collaborator 11.4, last modified on December 3, 2018

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

About Integration

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

  • Arbitrary Git diffs.
  • Git branches as diff arguments.
  • Local changes to files from the Git index.

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

Ways of Integration

You can enable the integration between Collaborator and Git for GUI Client, Command-Line Client or Collaborator server.

GUI Client

To enable the integration:

  1. Start GUI Client.

  2. Click Add to create a new SCM configuration.

  3. In the subsequent SCM Configuration dialog, specify the local source code location. For Git, this is not optional.

  4. Select Git in the SCM drop-down list.

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

    Option Description
    Git Executable A full path referring the Git command line client (git.exe).
    Skip changes Defines whether the changes you upload should be taken from the working tree instead of the index. This is an analogue of the git commit -a command.
    Client configuration for Git
  6. Once ready, click Validate to make sure the integration is operational.

After that, a new configuration for Git 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 to Review buttons
  • Add Changes – Upload the modifications that are currently in the index. This action is an analog of the git commit command.

    Add Changes_2
  • Add Unpushed Commits – Select all commits on your local branch that have not been pushed to the tracking branch.

    Note: This option assumes you have configured branch tracking in Git. On any errors – for example, Error initializing local changelists – make sure your current branch has a tracking branch set. To create an initial setup for this, run the git config branch.autosetupmerge always command. To use the existing branch for tracking, run git branch --set-upstream my-branch my-upstream, replacing my-branch and my-upstream with your parameters.
    The Add Unpushed Commits dialog
  • Add Commits – Upload commits, whether these have been pushed or not. To add a specific commit, specify its ID and click Add in the dialog.

    The Add Commits dialog
  • Add Git Diffs – Upload arbitrary Git diffs to the Collaborator server for review.

    Upload arbitrary Git diffs

    On the Branches tab of the dialog, you can also upload the differences between two branches to a review. Specify the branches in the Before and After drop-down lists.

    Upload the difference between two branches

Command-Line Client

In the Command-Line Client, you can create a review for arbitrary Git diffs and changes to files that are present in the Git index.

For example, to create a new review and add all changes in the current directory and below, plus the foo.txt file, you can use the following command:

ccollab addchanges new . foo.txt

Commands recommended for Git

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

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

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

Git-specific Options

Option

Description

--git-exe <value>

Full path to the "git" command line client.

--git-skip-index

Should changes be uploaded from the working tree instead of from the index (like git commit -a).

Collaborator Server

The Collaborator server can be configured to communicate directly with a Git repository. This allows users to review commits completely from the browser, without having to install any client programs. To enable this feature, first install and configure a Git client on the Collaborator server and then create an entry for your Git repository in the Version Control tab of the administration interface. Version control server entries are also created automatically if one of the client programs uploads files from a repository that does not match any of the currently configured servers.

Git Version Control Server

To enable the integration, you need to specify the following settings:

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 Git.
Attach changelists from browser If enabled, this feature lets users select commits to review directly from the web browser, without having to install any client programs.
Git Executable Full path to the Git command line client (git.exe).
Git Repository Full path to a Git repository. This is only necessary if you enable the Attach changelists from browser option. The repository can be bare.

Click Test Connection to make sure Collaborator can contact your Git repository.

Client configuration mapping

You can use Java-style regular expressions to map changelists from this Git repository uploaded from our client tools. 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 Git configuration.

Repository Host Pattern Match on the configured remote origin URL of the client (remote.origin.url).
Note: Clients may have various network configurations that make the URL look different.
First Commit Hash Pattern Match on the first commit hash returned from running git rev-list --max-parents=0 HEAD.

Supported Versions

To enable the integration via GUI Client and Command-Line Client, you need a Git command line client (git.exe) to generate differences for review. We require Git v1.7.4 or later.

Note: If you plan to add unpushed commits, you must have an upstream tracking branch set. You can tell Git and Collaborator which upstream branch to compare against by running the following command:

git branch --set-upstream [localbranch] [upstreambranch]

Remote Repositories Support

If your Git repository is located on one of the popular source hosting services – such as GitHub or GitLab – you may want to automatically create and update reviews when changes occur in your remote repositories. For that purpose, you can use the built-in Collaborator integration with these services. To learn more about possible options for integration, see Integration With Repository Hosting Services.

Submodule Support

Currently, Collaborator clients ignore submodule changes when adding changelists or diffs from the super project. Unlike clients, the server-side repository hosting integrations can display changes in the submodules of tracked repositories. So, to add the submodule differences you must either use repository hosting integration, or navigate into the submodule itself and add the files from there.

Git Server Hooks

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 must be completed.

If you are familiar with Gerrit (an open source Git-focused review package), you can implement a similar workflow for your engineering staff using Collaborator and Git triggers. To learn more, check the SmartBear blog: Gerrit-Style Code Review With Collaborator.

Link reviews with commits

To use the ensure-review-started and ensure-reviewed hooks, you must require developers to put the review ID somewhere in the Git commit message. 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. These 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 Git hooks in general, see the Git documentation.

See Also

Integration With Repository Hosting Services
SCM Configuration
Source Control Integrations

Highlight search results