Share via

File matching patterns reference

  • Article

TFS 2017 | TFS 2015

Pattern syntax

A pattern is a string or list of newline-delimited strings. File and directory names are compared to patterns to include (or sometimes exclude) them in a task. You can build up complex behavior by stacking multiple patterns. See fnmatch for a full syntax guide.

Match characters

Most characters are used as exact matches. What counts as an "exact" match is platform-dependent: the Windows filesystem is case-insensitive, so the pattern "ABC" would match a file called "abc". On case-sensitive filesystems, that pattern and name would not match.

The following characters have special behavior.

  • * matches zero or more characters within a file or directory name. See examples.
  • ? matches any single character within a file or directory name. See examples.
  • [] matches a set or range of characters within a file or directory name. See examples.
  • ** recursive wildcard. For example, /hello/**/* matches all descendants of /hello.

Extended globbing

  • ?(hello|world) - matches hello or world zero or one times
  • *(hello|world) - zero or more occurrences
  • +(hello|world) - one or more occurrences
  • @(hello|world) - exactly once
  • !(hello|world) - not hello or world

Note, extended globs cannot span directory separators. For example, +(hello/world|other) is not valid.

Comments

Patterns that begin with # are treated as comments.

Exclude patterns

Leading ! changes the meaning of an include pattern to exclude. You can include a pattern, exclude a subset of it, and then re-include a subset of that: this is known as an "interleaved" pattern.

Multiple ! flips the meaning. See examples.

You must define an include pattern before an exclude one. See examples.

Escaping

Wrapping special characters in [] can be used to escape literal glob characters in a file name. For example the literal file name hello[a-z] can be escaped as hello[[]a-z].

Slash

/ is used as the path separator on Linux and macOS. Most of the time, Windows agents accept /. Occasions where the Windows separator (\) must be used are documented.

Examples

Basic pattern examples

Asterisk examples

Example 1: Given the pattern *Website.sln and files:

ConsoleHost.sln
ContosoWebsite.sln
FabrikamWebsite.sln
Website.sln

The pattern would match:

ContosoWebsite.sln
FabrikamWebsite.sln
Website.sln

Example 2: Given the pattern *Website/*.proj and paths:

ContosoWebsite/index.html
ContosoWebsite/ContosoWebsite.proj
FabrikamWebsite/index.html
FabrikamWebsite/FabrikamWebsite.proj

The pattern would match:

ContosoWebsite/ContosoWebsite.proj
FabrikamWebsite/FabrikamWebsite.proj

Question mark examples

Example 1: Given the pattern log?.log and files:

log1.log
log2.log
log3.log
script.sh

The pattern would match:

log1.log
log2.log
log3.log

Example 2: Given the pattern image.??? and files:

image.tiff
image.png
image.ico

The pattern would match:

image.png
image.ico

Character set examples

Example 1: Given the pattern Sample[AC].dat and files:

SampleA.dat
SampleB.dat
SampleC.dat
SampleD.dat

The pattern would match:

SampleA.dat
SampleC.dat

Example 2: Given the pattern Sample[A-C].dat and files:

SampleA.dat
SampleB.dat
SampleC.dat
SampleD.dat

The pattern would match:

SampleA.dat
SampleB.dat
SampleC.dat

Example 3: Given the pattern Sample[A-CEG].dat and files:

SampleA.dat
SampleB.dat
SampleC.dat
SampleD.dat
SampleE.dat
SampleF.dat
SampleG.dat
SampleH.dat

The pattern would match:

SampleA.dat
SampleB.dat
SampleC.dat
SampleE.dat
SampleG.dat

Recursive wildcard examples

Given the pattern **/*.ext and files:

sample1/A.ext
sample1/B.ext
sample2/C.ext
sample2/D.not

The pattern would match:

sample1/A.ext
sample1/B.ext
sample2/C.ext

Exclude pattern examples

Given the pattern:

*
!*.xml

and files:

ConsoleHost.exe
ConsoleHost.pdb
ConsoleHost.xml
Fabrikam.dll
Fabrikam.pdb
Fabrikam.xml

The pattern would match:

ConsoleHost.exe
ConsoleHost.pdb
Fabrikam.dll
Fabrikam.pdb

Double exclude

Given the pattern:

*
!*.xml
!!Fabrikam.xml

and files:

ConsoleHost.exe
ConsoleHost.pdb
ConsoleHost.xml
Fabrikam.dll
Fabrikam.pdb
Fabrikam.xml

The pattern would match:

ConsoleHost.exe
ConsoleHost.pdb
Fabrikam.dll
Fabrikam.pdb
Fabrikam.xml

Folder exclude

Given the pattern:

**
!sample/**

and files:

ConsoleHost.exe
ConsoleHost.pdb
ConsoleHost.xml
sample/Fabrikam.dll
sample/Fabrikam.pdb
sample/Fabrikam.xml

The pattern would match:

ConsoleHost.exe
ConsoleHost.pdb
ConsoleHost.xml