使用功能分支
Feature branches 在分布式版本控制系统（DVCS）中允许您独立于主开发流程工作，并将所有的功能变更提交到该分支中，在功能完成后将变更融入主分支。 这种方法为软件开发团队带来了许多优势；然而，在没有专门支持的持续集成服务器中，也引发了一些问题，如持续的构建配置复制、可见性差，最终导致无法控制整个过程。
TeamCity 对功能分支的支持持续扩展，并包括在每次 TeamCity 检测到构建配置的 VCS 根的特定分支中有变化时， Branch Remote Run Trigger 开始新的个人构建，以及在成功构建后将一个分支合并到另一个分支的 Automatic Merge 等其他功能。
Git 和 Mercurial 功能分支得到了支持，同样还支持 Perforce branch streams support。
要开始使用 DVCS 分支，您需要设置分支规范。 这些规范指定了应监视哪些分支的更改。
一旦您配置了分支规范，TeamCity 将开始监视这些分支的变化。 如果您的构建配置有 一个 VCS 触发器并且在某个分支中找到了变更 ，TeamCity 将在此分支中触发构建。 从构建配置主页，您也可以按分支名称过滤历史记录、更改日志、挂起的更改和问题日志。 分支名称也会出现在自定义构建对话框中，因此您也可以在分支上手动触发自定义构建。
要设置分支规范，请打开常规 VCS 根设置并向下滚动到 分支规范 字段。 每个规范是一行新内容，以 +: 或 -: 开头，用于包含或排除特定分支，后跟完全解析的分支名称。 +: 部分可以省略。
- +:refs/heads/development
跟踪“development”分支
- -:refs/heads/sandbox
忽略“sandbox”分支
tip
note
默认分支 会隐式包含在分支规范中，因此您无需手动输入。
* 通配符允许您引用具有相似名称的多个分支：
- refs/heads/*
默认规则跟踪所有现有的存储库功能分支。
- refs/heads/dev-*
跟踪名称以“dev-”开头的功能分支：“dev-2024.2”、“dev-2025.1”等。
星号（* ）通配符匹配的分支名称部分将变为在 TeamCity 用户级界面中显示的短分支名称（也称为 逻辑分支名称）。 该行也可以包含可选的括号，当出现时，表示该部分的模式将被用作逻辑名称，而不仅仅是*-匹配的符号。
warning
*通配符必须至少解析为一个符号。 例如，如果分支规范是+:refs/heads/feature*：
refs/heads/feature1分支将被匹配
refs/heads/feature-JohnDoe分支将被匹配
refs/heads/feature分支将不会被匹配
当一个单一的 VCS 分支被分支规格的多行匹配时，最具体的（模式匹配的字符最少的）最后一条规则适用。
也就是说，如果规格中包含一个与分支完全匹配的模式（即，没有使用 * 通配符的模式），那么会使用最后一个这样的模式。 所以，如果您有像这样的规格：
+:refs/heads/release-v1
-:refs/heads/release-v1那么最后一个模式将会胜出，此分支将会被排除。
如果两个包含通配符的规则匹配同一分支但发生冲突，则生成最短逻辑名称的规则优先。 例如：
+:refs/heads/*/hotfix
-:refs/heads/v1/*对于 refs/heads/v1/hotfix 分支，这些规则是模棱两可的：
在逻辑名称
v1下包含v1/hotfix在逻辑名称
hotfix下排除v1/hotfix
v1 逻辑名称比 hotfix 更短，这意味着 TeamCity 需要解析的通配符字符更少。 这使得第一个规则更具体，并将被优先考虑。 因此， refs/heads/v1/hotfix 分支将被包含。
tip
要在 GitHub 和 GitLab 的拉取请求分支上运行构建，请使用 Pull Requests 构建功能。
分支规格也支持以 # 字符开头的表达式。 与定义应包含或排除到（来自）规格的分支名称的常规表达式相反，这些是为特定任务设计的特别制作的“服务”行。
以
#开头的任何行都被视为常规注释。+:refs/heads/main # Exclude legacy branch. DO NOT REMOVE! -:refs/heads/release-v1#! 转义：<您的字符>表达式定义了一个转义字符，允许您在分支名称中使用特殊字符。 例如，要为 "release-(7.1)" 分支编写分支规格规则，您需要转义圆括号。 在 TeamCity 中，默认的转义符号是反斜杠 (\)，所以您的分支规范应如下所示：+:release-\(7.1\)如果您想使用不同的转义字符，请按如下所示定义：
#! escape: ! +:release-!(7.1!)#! fallbackToDefault: false表达式允许您在找不到必需的分支时，禁止 TeamCity 使用一个 默认分支。 例如，当您使用 TeamCity REST API 启动一个不存在的分支的构建时（默认情况下，TeamCity 会在这种情况下为默认分支运行新的构建）。#! fallbackToDefault: false +:included_branch -:excluded_branch
在为 DVCS 配置 VCS 根时，您需要指定要用作默认的分支名称。 默认分支具有特殊含义：
这是一个回退分支，用于在未指定分支或指定的分支未被分支规范包含时使用（例如，当有人仅点击 运行 而未选择分支时）。
在显示构建和更改的序列并且到达分支创建的那一刻时，可以使用它。
默认分支允许在不同的 VCS 根目录（例如，一个根目录是 Git ，另一个是 Mercurial ）以及在它们通过快照依赖关系链接时的不同构建中使用不同的分支。 当在默认分支中触发顶链构建时，其所有依赖项也将在各自的默认分支中构建。
除非通过 分支过滤器 禁用，否则默认分支总是隐式包含在分支规格中。 在 TeamCity UI 中， 默认分支以更深颜色标记的分支标记进行标记。
tip
请注意，与 分支规格 字段不同， 默认分支 不支持圆括号。
TeamCity 能够根据当前 TeamCity 用户的提交来识别并分组分支。
在分支筛选器中选择 My Branches 群组，以显示所有最后100次更改包含您的提交的活动分支，这是基于定义的 VSC 用户名。
逻辑分支名称是在构建和构建配置级别的用户界面中显示的分支名称。 逻辑分支名称通常是完整的 VCS 特定分支名称的一部分。 它是通过将 分支规格应用于版本控制中的分支名称来计算的。
例如，如果分支规格定义如下：
+:refs/heads/*那么，由 * 匹配的部分（例如， master ）是一个逻辑分支名称。
如果分支规格模式使用了括号，逻辑名由括号内的名字部分组成；要在 VCS 分支 refs/heads/v8.1/feature1 的 UI 中查看 v8.1 / feature1 逻辑名，请使用这个：
+:refs/heads/(v8.1/*)您无需将默认分支包含在分支规格中，因为它已经被隐式地包含在其中了。 然而，如果您希望在用户界面中为默认分支设置一个简短的逻辑分支名称，例如， master ，您可以将其包含在分支规格中并使用括号：
+:refs/heads/(master)您可以通过以下两种方式之一在特定分支上手动运行构建：
单击 运行 ，位于构建列表中所需分支的对面。
打开 自定义运行 对话框，转到 更改 选项卡，并在 "构建分支" 下拉菜单中选择所需分支。
要自动从特定分支或一组分支运行构建，配置 构建触发器。
分支构建在 TeamCity 用户界面中很容易被识别出来，因为它们会被标记上一个特殊的标签：
如果您对某个特定的分支感兴趣，您也可以按分支名称过滤历史记录。 TeamCity 也会为来自默认分支的构建分配一个分支标签。
对于每个构建，TeamCity 都会显示其中包含的更改。 对于来自分支的构建，更改的计算过程会考虑分支，并向您展示与构建分支相关的更改。 在分支中的构建所做的更改将计算为从构建的修订版到分支中的上一个构建或默认分支中的构建的更改。
提交记录的更改日志及其图形会帮助您理解正在监视的分支中正在发生的情况。
启用默认的 显示图表 选项后，TeamCity 会在图表上显示构建标记。
在配置了分支的构建配置中，大多数 UI 页面默认显示活动分支。
一个 活跃分支 是具有最近活动的分支：它有最近的构建或者在带有最近提交的仓库中存在。
活动的阈值可以通过构建配置参数进行配置。 参数可以在构建配置（这将仅影响一个构建配置）、项目中更改，或者在 内部属性 中更改（这将为整个服务器定义默认值）。 在配置中的参数会覆盖 内部属性 中的参数。
如果满足以下条件，分支将被视为活动状态：
它存在于 VCS 仓库中，并且有近期的提交（即，提交的时间小于整数参数
teamcity.activeVcsBranch.age.days的值，默认为 7 天）。或者它有最近的构建（即，构建的时间小于整数参数
teamcity.activeBuildBranch.age.hours的值，默认为24小时）。
具有构建的已关闭 VCS 分支在最后一次构建后的 24小时内仍将显示为活动状态。 要从显示中移除已关闭的分支，请设置teamcity.activeBuildBranch.age.hours=0。
TeamCity 试图在构建中检测新的失败测试，对于那些并非新的测试，您可以看到测试在哪个构建中开始失败。 此功能也能识别分支，即当计算第一个构建时，TeamCity 会遍历同一分支的构建。
此外，在测试详情页上提供了一个 branch filter ，您可以在单个分支中查看测试通过或失败的历史记录。
如果一个 构建失败条件 被如下配置： 构建度量与上一次成功/完成/固定构建相比有所改变 ，TeamCity 将尝试将当前构建与同一分支的构建进行比较。 如果同一分支中没有合适的构建，它将使用默认分支中的构建，并将相应的消息添加到构建日志中。 请注意，如果默认分支被 分支过滤器 禁用，那么 TeamCity 将无法正确处理构建失败的条件（参见相关问题 TW-74884）。
VCS 触发器完全了解分支，并且一旦在分支中检测到检入，就会触发构建。 所有的 VCS 触发器选项，如每次检入触发、静默周期和触发规则，都直接用于从分支构建。 默认情况下，“Schedule and Finish”构建触发器仅监视默认分支中的构建。
另外，可以为 VCS 、计划和完成构建触发器指定一个 分支过滤器。
如果带有分支的构建配置对其他带有分支的构建配置有快照依赖，那么当在一个分支中触发构建时，链中的其他构建也将获得关联的分支，前提是这些构建中 VCS 根的分支有相同的 逻辑名称 ，并且该分支没有被分支规范排除。 构建的 VCS 根可以指向不同的存储库，但逻辑分支名称必须相同。
如果满足此条件，将检出具有此名称的分支，并将链下所有构建（构建触发取决于）和链上所有构建（取决于触发的构建）标记为同一分支。 否则，将检出默认分支。
您可以配置构件依赖性，以从特定分支的构建中检索构件：构件依赖性将使用来自指定分支的构建。 同样适用于 Schedule 和 Finish Build 触发器。
除了 "My changes"，所有的通知规则只会在来自默认分支的构建中通知您。 与此同时，"我的更改"规则将适用于所有可用分支的构建。
构建配置状态是根据默认分支的构建计算的。 因此，针对默认分支的构建，每个配置的调查都能够顺利进行。 例如，来自非默认分支的成功构建不会移除每个配置的调查，但来自默认分支的成功构建将会移除。
如果一个构建配置有两个（或更多）设定了分支过滤器的 VCS 根，触发行为可能会变得更复杂。
VCS 触发器按照它们的 逻辑分支名称 对多个根的分支进行分组。 当某个根节点从另一个根节点没有分支时，将使用其默认分支。
例如：2个 VCS 根具有相同的默认分支 refs/heads/master。 Root1 具有分支规范 refs/heads/7.1/* ，并在分支 refs/heads/7.1/feature1 和 refs/heads/7.1/feature2 中有新的提交。 Root2 具有规格 refs/heads/devel/* ，并且在分支 refs/heads/devel/feature1 中有新的提交。
在这里， feature1 是相关于两个路径不同的分支的逻辑名称： .../7.1/feature1 和 .../devel/feature1。
在这种情况下，VCS 触发器将运行 3 次构建，这些构建来自以下分支组合的修订：
Build number（构建号） | root1 | root2 | 描述 |
|---|---|---|---|
1 |
|
| 默认分支会被 隐式添加到每个规格中。 |
2 |
|
|
|
3 |
|
| 在 root1 的规范中存在 |
如果您需要在构建脚本中获取分支名称，或者将其作为参数在其他构建配置设置中使用，请参考 预定义的构建参数。
在 TeamCity 中，您可以手动合并分支，例如，如果您希望在代码审查/批准后才合并分支，或者尽管分支中的测试失败，您仍希望执行合并。
手动合并来源:
打开 构建结果页面 ，单击右上角的 操作 菜单，然后选择 合并此构建来源。
出现的对话框允许您选择目标分支并添加提交消息（必填）。
也可以 自动合并分支。
感谢您的反馈！