Build TFVC repositories

  • Article

TFS 2017 | TFS 2015

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.

Choose the repository to build

While editing a pipeline that uses a TFVC repo, you have the following options.

Feature Azure Pipelines, TFS 2018, TFS 2017, TFS 2015.4 TFS 2015 RTM
Clean Yes Yes
Specify local path Yes No
Label sources Yes No

Note

Azure Pipelines, TFS 2017.2 and newer: Click Advanced settings to see some of the following options.

Repository name

Ignore this text box (TFS 2017 RTM or older).

Mappings (workspace)

Include with a type value of Map only the folders that your build pipeline requires. If a subfolder of a mapped folder contains files that the build pipeline does not require, map it with a type value of Cloak.

Make sure that you Map all folders that contain files that your build pipeline requires. For example, if you add another project, you might have to add another mapping to the workspace.

Cloak folders you don't need. By default the root folder of project is mapped in the workspace. This configuration results in the build agent downloading all the files in the version control folder of your project. If this folder contains lots of data, your build could waste build system resources and slow down your build pipeline by downloading large amounts of data that it does not require.

When you remove projects, look for mappings that you can remove from the workspace.

If this is a CI build, in most cases you should make sure that these mappings match the filter settings of your CI trigger on the Triggers tab.

For more information on how to optimize a TFVC workspace, see Optimize your workspace.

Clean the local repo on the agent

You can perform different forms of cleaning the working directory of your self-hosted agent before a build runs.

In general, for faster performance of your self-hosted agents, don't clean the repo. In this case, to get the best performance, make sure you're also building incrementally by disabling any Clean option of the task or tool you're using to build.

If you do need to clean the repo (for example to avoid problems caused by residual files from a previous build), your options are below.

Azure Pipelines, TFS 2018, TFS 2017.2

If you want to clean the repo, then select true, and then select one of the following options:

  • Sources: The build pipeline performs an undo of any changes and scorches the current workspace under $(Build.SourcesDirectory).

  • Sources and output directory: Same operation as Sources option above, plus: Deletes and recreates $(Build.BinariesDirectory).

  • Sources directory: Deletes and recreates $(Build.SourcesDirectory).

  • All build directories: Deletes and recreates $(Agent.BuildDirectory).

TFS 2017 RTM, TFS 2015.4

If you select True then the build pipeline performs an undo of any changes and scorches the workspace.

If you want the Clean switch described above to work differently, then on the Variables tab, define the Build.Clean variable and set its value to:

  • all if you want to delete $(Agent.BuildDirectory), which is the entire working folder that contains the sources folder, binaries folder, artifacts folder, and so on.

  • source if you want to delete $(Build.SourcesDirectory).

  • binary If you want to delete $(Build.BinariesDirectory).

CI triggers

Select Enable continuous integration on the Triggers tab to enable this trigger if you want the build to run whenever someone checks in code.

CI trigger.

Batch changes

Select this check box if you have many team members uploading changes often and you want to reduce the number of builds you are running. If you select this option, when a build is running, the system waits until the build is completed and then queues another build of all changes that have not yet been built.

You can batch changes and build them together.

Path filters

Select the version control paths you want to include and exclude. In most cases, you should make sure that these filters are consistent with your TFVC mappings. You can use path filters to reduce the set of files that you want to trigger a build.

Tips:

  • Paths are always specified relative to the root of the workspace.
  • If you don't set path filters, then the root folder of the workspace is implicitly included by default.
  • If you exclude a path, you cannot also include it unless you qualify it to a deeper folder. For example if you exclude /tools then you could include /tools/trigger-runs-on-these
  • The order of path filters doesn't matter.

Gated check-in

You can use gated check-in to protect against breaking changes.

By default Use workspace mappings for filters is selected. Builds are triggered whenever a change is checked in under a path specified in your source mappings.

Otherwise, you can clear this check box and specify the paths in the trigger.

How it affects your developers

When developers try to check-in, they are prompted to build their changes.

Gated check-in prompt

The system then creates a shelveset and builds it.

For details on the gated check-in experience, see Check in to a folder that is controlled by a gated check-in build pipeline.

Option to run CI builds

By default, CI builds are not run after the gated check-in process is complete and the changes are checked in.

However, if you do want CI builds to run after a gated check-in, select the Run CI triggers for committed changes check box. When you do this, the build pipeline does not add ***NO_CI*** to the changeset description. As a result, CI builds that are affected by the check-in are run.

A few other things to know

FAQ

I get the following error when running a pipeline:

The shelveset <xyz> could not be found for check-in

  • Is your job authorization scope set to collection? TFVC repositories are usually spread across the projects in your collection. You may be reading or writing to a folder that can only be accessed when the scope is the entire collection. You can set this in organization settings or in project setting under the Pipelines tab.

I get the following error when running a pipeline:

The underlying connection was closed: An unexpected error occurred on a receive. ##[error]Exit code 100 returned from process: file name 'tf', arguments 'vc workspace /new /location:local /permission:Public

  • This is usually an intermittent error caused when the service is experiencing technical issues. Please re-run the pipeline.

What is scorch?

Scorch is a TFVC power tool that ensures source control on the server and the local disk are identical. See Microsoft Visual Studio Team Foundation Server 2015 Power Tools.