Configuring VCS Settings

This section provides notes on configuring the following VCS Settings:

Configuring VCS Roots

A VCS Root is a description (a number of connection settings) of a version control system where project sources are located.

VCS roots are configured on the 2.Version Control Settings page of a build configuration.

Shared VCS Roots

By default, the same VCS root(s) can be used by all of the project's build configurations. They can also be used by different projects when VCS Roots Sharing is enabled on the New Edit VCS Roots page. Sharing VCS roots saves the administrator's time and the hassle of creating and maintaining identical VCS roots in the repository.

If someone attempts to modify a VCS root that is shared, TeamCity will issue a warning that the changes to the VCS root could potentially affect more that one project. The user is then prompted to either save the changes and apply them to all the projects using the VCS root, or to make a copy of the VCS root for use by either a specific build configuration or project.

VCS Checkout Mode

The VCS Checkout mode is a configuration that sets how project sources reach an agent. Agents do not need any additional software for automatic checkout modes.

TeamCity has three different VCS checkout modes:

VCS Checkout Rules

VCS Checkout Rules allow you to exclude paths and/or map paths (copy directories and all their contents) to a different location on the Build Agent during checkout.

To add a checkout rule click the edit checkout rules link on the build configuration's Version Control Settings page and a pop-up window will appear where you can enter the rule.

The general syntax of a single checkout rule is as follows:

+|- : VCSPath [=> AgentPath]

When entering rules please note the following:

• To enter multiple rules, each rule should be entered on a separate line.

• For each file the most specific rule will apply if the file is included, regardless of what order the rules are listed in.

• If you don't enter an operator it will default to +:

Rules can be used to perform the following operations:

An example with three VCS checkout rules:

In the above example, the first rule excludes the src/help directory and its contents from checkout. The third rule is more specific than the second rule and maps the scr/samples path to the samples path in the Build Agent's default Agent Working Directory. The second rule maps the contents of the scr path to the production/sources on the build agent, except src/help which was excluded by the first rule and scr/samples which was mapped to a different location by the third rule.

VCS Labeling Support

TeamCity can optionally add a label into the version control system for the sources used for a particular build. This is useful if you need to collect all of the sources for a specific build in order to recreate it. You can choose to apply the VCS label for all builds or only for successful ones. You can also manually invoke VCS labeling action for a finished build: Check Label this build sources in the VCS revisions and labels section of the Changes tab of the build results.

The labeling process takes place after the build finish and doesn't affect the build status. If the label fails it will not change the build status.

VCS labeling is supported for ClearCase, CVS, Perforce, StarTeam and Subversion.

Subversion

Subversion VCS roots need additional configuration for VCS labeling to work. The Subversion need to be specified to define the SVN repository structure.

Labeling rules are specified as newline-delimited rules each of uses the following format:

TrunkOrBranchRepositoryPath => tagDirectoryRepositoryPath

The repository paths can be relative and absolute (starting from "/"). Absolute paths are resolved from the SVN repository root, relative paths are resolved from the VCS root.

When creating a label, the sources residing under TrunkOrBranchRepositoryPath will be put into the tagDirectoryRepositoryPath/<tagName> directory, where <tagName> is the name of the label as defined by the 2.Version Control Settings of the build configuration. If no sources match the TrunkOrBranchRepositoryPath, then no label will be created. The path tagDirectoryRepositoryPath should already exist in the repository. If tagDirectoryRepositoryPath directory already contains subdirectory with the current label name, the labeling process will fail, and the old tag directory won't be deleted or affected.

For example, there is a VCS root with the URL svn://address/root/project where svn://address/root is the repository root, and the repository has the structure:

In this case the labeling rules should be:

VCS Labeling Failure Notifications

TeamCity starts the VCSLabelingSupport process, when the build is finished. Thus VCS Labeling does not affect the build status, and therefore is not a standard Notification Conditions. However, TeamCity allows notifying about labeling failure. If the labeling process failed due to some reason, TeamCity sends notification to all users, that have subscribed for Notification Conditions of the current build configuration.