VCS Checkout Rules
VCS checkout rules allow you to check out a part of the configured VCS root and to map directories from the version control to subdirectories in the build checkout directory on a build agent. Thus, you can define a VCS root for the entire repository and instruct each build configuration to check out only the relevant part of it.
The checkout rules affect what build changes are displayed in the UI and what files are checked out for a build on the agent. If a commit does not match any of the checkout rule patterns of the build's VCS root, TeamCity will completely ignore it. Such change will not be displayed as pending and will not be able to trigger any builds in the current configuration.
To display changes but not to trigger a build on a commit, use VCS trigger rules.
tip
Watch our video guide on the difference between the checkout and trigger rules.
tip
If a dependent build (1) has a VCS trigger that monitors changes in its snapshot dependency build and (2) shares a VCS root with this dependency, its checkout rules' scope should cover the scope of rules of this dependency. That is, each commit relevant for a dependency must be also relevant for the dependent build.
The general recommendation is to keep a number of VCS roots, pointing to the root of the repository, as small as possible and define what is checked out by a specific build configuration via checkout rules.
Go to Administration and click the project you want to configure.
From the project's General Settings page, click the relevant build under Build Configurations
Select Version Control Settings from the sidebar.
Locate the VCS root in the list, and click Edit checkout rules to open a form for entering the rules.
Use the VCS repository browser
to select a directory to check out.
Note that Perforce support in TeamCity treats checkout rules as case-sensitive. Case-insensitivity for Perforce-based build configurations can be enabled on the Version Control Settings page by adding the following comment in the Edit Checkout Rules form: ##teamcity ignore-case
.
note
Checkout rules can only be set to directories, files are not supported.
In the examples below the paths in the repository (VCSPath
) are relative to the configured VCS root, the paths on the agent (AgentPath
) are relative to the build checkout directory.
The general syntax of a single checkout rule is as follows:
+|-: VCSPath [=> AgentPath]
tip
Here, the pipe symbol
|
represents the OR command, as in regular expressions: use+
for including, OR-
for excluding.
If no rule is specified, all files are included.
When you start entering a rule, note that as soon as you enter any +:
rule, TeamCity will remove the default "include all" setting.
To include all the files explicitly, use the +:.
rule.
Note that exclude checkout rules (in the form of -:
) will generally only speed up server-side checkouts, unless you use Perforce and TFS agent-side checkout, where exclude rules are processed effectively.
With other version control systems, agent-side checkouts may emulate the exclude checkout rules by checking out all the root directories mentioned as include rules and deleting the excluded directories. With such systems, exclude checkout rules should generally be avoided for the agent-side checkout. Refer to the VCS Checkout Mode page for more information.
With Git agent-side checkout, TeamCity translates some checkout rules to the sparse checkout patterns, which limits the set of supported VCS checkout rules.
If there are multiple VCS roots with intersecting checkout rules (for example, two VCS roots have the checkout rule +: foo => bar
) attached to a build configuration and the files are checked out on the agent, some files might be skipped during the checkout. The following warning will be shown in the UI:
The paths specified in the checkout rules of one VCS root conflict (intersect) with checkout rules of another VCS root. This may cause problems in "checkout on agent" mode.
To work around this issue, resolve the conflicts between the checkout rules or change the checkout mode to " server-side ".
When entering rules, 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:
Syntax | Explanation |
---|---|
| Checks out the root into the |
| Excludes |
| Maps the |
| Maps the |
| Maps the |
An example with three VCS checkout rules:
-:src/help
+:src=>production/sources
+:src/samples=>./samples
In the above example, the first rule excludes the src/help
directory and its contents from the checkout. The third rule is more specific than the second rule and maps the src/samples
path to the samples
path in the build agent's default work directory. The second rule maps the contents of the src
path to the production/sources
on the build agent, except src/help
which was excluded by the first rule and src/samples
which was mapped to a different location by the third rule.
The Git plugin uses git sparse-checkout
to check out Git files on an agent. The plugin is able to perform only simple file mapping operations which limits the set of supported VCS checkout rules for Git.
The following rules are supported:
+:dirA/dirA1
-:dirA/dirA1/dirA2
+:. => dirA/dirA1/dirA2
+:dirA => dirA
+:dirA/dirA1 => dirA/dirA1
+:dirA/dirB/dirC => dirD/dirE/dirA/dirB/dirC
Note that rules must not remap files. That is, the following rule is not supported: +:dirA/dirA1 => dirA/dirA2
.
If you specify multiple checkout rules for one root, make sure their checkout directories (the right part of the rule) have a common parent directory ([prefix/]
). Only the rules +:dirA => [prefix/]dirA
are supported for agent-side checkout, and the [prefix/]
must be the same for all rules.
For example:
+:dirA/dirB/dirC => [prefix/]dirA/dirB/dirC
+:dirD/dirE/dirF => [prefix/]dirD/dirE/dirF
Note that the following rule is not supported: +:dirA=>[prefix/]dirA/postfix
. If you append [/postfix]
to the checkout directory path and the configuration's VCS checkout mode is set to "Always checkout files on agent", new builds will be unable to start.
![Checkout directory path error Checkout directory path error](https://resources.jetbrains.com/help/img/teamcity/2024.12/dk-postfixCheckoutError.png)
Thanks for your feedback!