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.
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:
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.
You can enable the integration between Collaborator and Git for GUI Client, Command-Line Client or Collaborator server.
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. For Git, this is not optional.
Select Git in the SCM drop-down list.
Several options will become available. These are specifically tailored to configure Git integration.
A full path referring the Git command line client (git.exe).
Defines whether the changes you upload should be taken from the working tree instead of the index. This is an analogue of the
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.
Add Changes – Upload the modifications that are currently in the index. This action is an analog of the
git commit command.
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,
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.
Add Git Diffs – Upload arbitrary Git diffs to the Collaborator server for review.
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
ccollab addchanges – Attaches locally-modified files to a review.
ccollab addchangelist – Attaches an atomic changelist to a review.
ccollab addgitdiffs – Uploads differences generated by git diff command.
ccollab gitaddbranch – Uploads all differences between the specified branch and the remote-tracking branch.
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:
Full path to the "git" command line client.
Should changes be uploaded from the working tree instead of from the index (like
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.
To enable the integration, you need to specify the following settings:
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
|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.
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
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:
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.
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.
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.
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:
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.