File matching patterns reference

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.

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

What do double-asterisk (**) wildcards mean?

Double Asterisk (**)
Double Asterisk (**) matches zero or more characters across multiple segments. It is used for globbing files that are in nested directories.

Example: Tests/**/*.js

Here, the file selecting will be restricted to the Tests directory. The glob will match the files such as Tests/HelloWorld.js, Tests/UI/HelloWorld.js, Tests/UI/Feature1/HelloWorld.js.