|You are viewing documentation of TeamCity 6.5.x, which is not the most recent released version of TeamCity. Please refer to the listing to choose another version.|
In TeamCity a plugin for Version Control System (VCS) is seen as a set of interface implementations grouped together by instances ofjetbrains.buildServer.vcs.VcsSupportContext
(server-side part) andjetbrains.buildServer.agent.vcs.AgentVcsSupportContext
There are also optional parts:
Personal builds require corresponding support in IDE. Chances are we will eliminate this dependency in the future.
The agent-side part is optional and only responsible for checking out and updating project sources on agents. In contrast to server-side checkout it offers a traditional approach to interacting between a CI system and VCS – when source code is checked out into the same location where it's built. For pros & cons of both solutions see VCS Checkout Mode.
A Version is unambiguous representation of a particular snapshot within a repository pointed at by a VCS Root. The current version represents the head revision at the moment of obtaining.
The current version is taken by callingjetbrains.buildServer.vcs.VcsSupportCore#getCurrentVersion(jetbrains.buildServer.vcs.VcsRoot)
. The version here is an arbitrary text. It can be a representation of a transaction number, a revision number, a date, whatever suitable enough for getting a source snapshot in a particular VCS. Usually format of the version depends on a version control system, the only requirement which comes from TeamCity — it should be possible to sort changes by version in order of their happening (seejetbrains.buildServer.vcs.VcsSupportConfig#getVersionComparator()
TeamCity does not show Versions in the UI directly. For UI TeamCity converts a Version to its display name usingjetbrains.buildServer.vcs.VcsSupportConfig#getVersionDisplayName(String,jetbrains.buildServer.vcs.VcsRoot)
A Change is an atomic modification of a single file within a source repository. In other words a Change corresponds to a single increment of a file version.
A Modification is a set of Changes made by some user at a certain time interval. It most closely corresponds to a single checkin transaction, when a user commits all his modifications made locally to the central repository. A Modification also contains the Version of the VCS Root right after the corresponding Changes have been applied.
A Patch is ... TODO
A Checkout Rule is a way of changing default file layout.
Checkout rules allow to map path in repository to another path on agent or to exclude some parts of repository, read more.
Checkout rules consist of include and exclude rules. Include rule can have "from" and "to" parts ("to" part allows to map path in repository to another path on agent). Mapping is performed by TeamCity itself and VCS plugin should not worry about it. However a VCS plugin can use checkout rules to speedup changes retrieval and patch building since checkout rules usually narrow a VCS Root to some its subset.
Patch Building and Change Collecting Policies
Suppose, we have a VCS Root pointing to
Then after collecting all changes for all the include rules
Although being quite simple
Assume both changes in the example above are done by the same user within the same commit transaction. Logically, both corresponding
Another limitation is complete ignorance of exclude rules. As it said before this doesn't cause showing unneeded information in the UI. So an implementation can safely use
All above is applicable to building patches using
By default server caches clean patches created by VCS plugins, because on large repositories clean patch construction can take significant time. If clean patches created by your VCS plugin must not be cached, you should return true from the method VcsSupport#ignoreServerCachesFor(VcsRoot).
Agent part of VCS plugin is optional, if it is provided then checkout can also be performed on the agent itself. This kind of checkout usually works faster but it may require additional configuration efforts, for example, if VCS plugin uses command line client then this client must be installed on all of the agents.
To enable agent-side checkout, be sure to include
jetbrains.buildServer.agent.vcs.AgentVcsSupportContext into agent plugin part and also enable agent-side checkout via