Filename Matching

Filename matching is a pattern-matching feature implemented in certain Ruby methods:

• File.fnmatch.

• Pathname#fnmatch.

Each fnmatch method matches a pattern against a string path; these methods operate only on strings, and do not access the file system.

These are quite different from filename globbing methods (not discussed here), which match patterns against string paths found in the actual file system:

• Dir.glob.

• Pathname.glob.

• Pathname#glob.

Patterns

These are the basic elements of filename matching patterns; see the sections below for details:

There are two other patterns that are disabled by default:

• Directory-like substring ('**'); see File::FNM_PATHNAME below.

• Alternatives ('{ , }'); see File::FNM_EXTGLOB below.

Simple String

A “simple string” is one that does not contain special filename-matching patterns; see the table above.

A simple string matches itself:

File.fnmatch('xyzzy', 'xyzzy')                 # => true
File.fnmatch('one_two_three', 'one_two_three') # => true
File.fnmatch('123', '123')                     # => true
File.fnmatch('Form 27B/6', 'Form 27B/6')       # => true
File.fnmatch('bcd', 'abcde')                   # => false  # Must be exact.

By default, the matching is case-sensitive:

File.fnmatch('abc', 'ABC') # => false

Case-sensitivity may be modified by flags:

• File::FNM_CASEFOLD.

• File::FNM_SYSCASE.

By default, the alternatives pattern is disabled:

File.fnmatch('R{ub,foo}y', 'Ruby') # => false

It may be enabled by flag File::FNM_EXTGLOB.

By default, the Windows short name pattern is disabled:

File.fnmatch('PROGRAM~1', 'Program Files') # => false

It may be enabled by flag File::FNM_SHORTNAME.

Any Sequence of Characters ('*')

The asterisk pattern ('*') matches any sequence of characters:

File.fnmatch('*', 'foo')            # => true
File.fnmatch('*', '')               # => true
File.fnmatch('*', '*')              # => true
File.fnmatch('\*', 'foo')           # => false  # Escaped.

By default, the asterisk pattern does not match a leading period (as in a dot-file):

File.fnmatch('*', '.document') # => false

That matching may be enabled by flag File::FNM_DOTMATCH.

By default, the asterisk pattern matches across file separators:

File.fnmatch('*.rb', 'lib/test.rb') # => true

That matching may be disabled by flag File::FNM_PATHNAME.

Single Character ('?')

The question-mark pattern ('?') matches any single character:

File.fnmatch('?', 'f')                 # => true
File.fnmatch("foo-?.txt", "foo-1.txt") # => true
File.fnmatch('?', 'foo')               # => false
File.fnmatch('?', '')                  # => false
File.fnmatch('\?', 'f')                # => false  # Escaped.

By default, pattern '?' matches the file separator:

File.fnmatch('foo?boo', 'foo/boo') # => true

That matching may be disabled by flag File::FNM_PATHNAME.

Single Character from a Set ('[abc]', '[^abc]')

Characters enclosed in square brackets define a set of characters, any of which matches a single character:

File.fnmatch('[ruby]', 'r')      # => true
File.fnmatch('[ruby]', 'u')      # => true
File.fnmatch('[ruby]', 'y')      # => true
File.fnmatch('[ruby]', 'ruby')   # => false
File.fnmatch('\[ruby]', 'r')     # => false  # Escaped.

The character set may be negated:

File.fnmatch('[^ruby]', 'r') # => false
File.fnmatch('[^ruby]', 'u') # => false

Single Character from a Range ('[a-c]', '[^a-c]')

A range of characters enclosed in square brackets defines a set of characters, any of which matches a single character:

File.fnmatch('[a-c]', 'b')           # => true
File.fnmatch('[a-c]', 'd')           # => false
File.fnmatch('[a-c]', 'abc')         # => false
File.fnmatch('R[t-v][a-c]y', 'Ruby') # => true   # Multiple ranges allowed.
File.fnmatch('\[a-c]', 'b')          # => false  # Escaped.

The range may be negated:

File.fnmatch('[^a-c]', 'b') # => false
File.fnmatch('[^a-c]', 'd') # => true

Escape ('\')

The backslash character ('\') may be used to escape any of the characters that filename matching treats as special:

File.fnmatch('[a-c]', 'b')  # => true
File.fnmatch('\[a-c]', 'b') # => false
File.fnmatch('[a-c\]', 'b') # => false
File.fnmatch('[a\-c]', 'b') # => false

File.fnmatch('{a,b}', 'b', File::FNM_EXTGLOB)  # => true
File.fnmatch('\{a,b}', 'b', File::FNM_EXTGLOB) # => false
File.fnmatch('{a\,b}', 'b', File::FNM_EXTGLOB) # => false
File.fnmatch('{a,b\}', 'b', File::FNM_EXTGLOB) # => false

Use a double-backslash to represent an ordinary backslash:

File.fnmatch('\\\\', '\\') # => true

By default escape pattern '\' is enabled; it may be disabled by flag File::FNM_NOESCAPE.

Flags

Optional argument flags (defaults to 0) may be the bitwise OR of the constants File::FNM*.

These are the constants for filename-matching patterns; see the sections below for details:

Constant File::FNM_CASEFOLD

By default, filename matching is case-sensitive; use constant File::FNM_CASEFOLD to make the matching case-insensitive:

File.fnmatch('abc', 'ABC')                     # => false
File.fnmatch('abc', 'ABC', File::FNM_CASEFOLD) # => true

Constant File::FNM_DOTMATCH

By default, filename matching does not allow pattern '*' to match a dotfile name (i.e, a filename beginning with a dot); use constant File::FNM_DOTMATCH to enable the match:

File.fnmatch('*', '.document')                     # => false
File.fnmatch('*', '.document', File::FNM_DOTMATCH) # => true

Constant File::FNM_EXTGLOB

By default, filename matching has the alternative notation disabled; use constant File::FNM_EXTGLOB to enable it:

File.fnmatch('R{ub,foo}y', 'Ruby')                    # => false
File.fnmatch('R{ub,foo}y', 'Ruby', File::FNM_EXTGLOB) # => true

The alternatives pattern consists of zero or more unquoted strings, separated by commas, and enclosed in curly braces:

File.fnmatch('R{ub,foo,bar}y', 'Ruby')                     # => false  # Not enabled.
File.fnmatch('R{ub,foo,bar}y', 'Ruby', File::FNM_EXTGLOB)  # => true
# Whitespace matters.
File.fnmatch('R{ub ,foo,bar}y', 'Ruby', File::FNM_EXTGLOB) # => false
File.fnmatch('R{ ub,foo,bar}y', 'Ruby', File::FNM_EXTGLOB) # => false
# Special characters remain in force:
File.fnmatch('{*,?}', 'hello', File::FNM_EXTGLOB)          # => true
File.fnmatch('{*ello,?}', 'hello', File::FNM_EXTGLOB)      # => true
File.fnmatch('{*ELLO,?}', 'hello', File::FNM_EXTGLOB)      # => false
File.fnmatch('{*ELLO,?????}', 'hello', File::FNM_EXTGLOB)  # => true
# With the flag not given.
File.fnmatch('R{ub,foo,bar}y', 'Ruby')                     # => false

Constant File::FNM_NOESCAPE

By default filename matching has escaping enabled; use constant File::FNM_NOESCAPE to disable it:

File.fnmatch('\*\?\*\*', '*?**')                     # => true
File.fnmatch('\*\?\*\*', '*?**', File::FNM_NOESCAPE) # => false

Constant File::FNM_PATHNAME

Flag File::FNM_PATHNAME affects patterns '**', '*', and '?'.

By default, the double-asterisk pattern ('**') is equivalent to pattern '*', and matches any sequence of directory-like substrings:

File.fnmatch('**', 'a/b/c') # => true
File.fnmatch('*', 'a/b/c')  # => true

When flag File::FNM_PATHNAME is given, the pattern matches only one component of a file path:

File.fnmatch('**', 'a/b/c')                       # => true   # Matches 'a/b/c'.
File.fnmatch('**', 'a/b/c', File::FNM_PATHNAME)   # => false  # Matches only 'a'.
File.fnmatch('**', 'a/b/c', File::FNM_PATHNAME)   # => false  # Matches only 'a/b'.
File.fnmatch('**/*', 'a/b/c', File::FNM_PATHNAME) # => true   # Matches 'a/b', then 'c'.

By default, filename matching enables pattern '*' to match at or across the file separator (File::SEPARATOR); use constant File::FNM_PATHNAME to disable such matching:

File::SEPARATOR                                          # => "/"
File.fnmatch('*.rb', 'lib/test.rb')                      # => true
File.fnmatch('*.rb', 'lib/test.rb', File::FNM_PATHNAME)  # => false

By default, filename matching enables pattern '?' to match at or across the file separator (File::SEPARATOR); use constant File::FNM_PATHNAME to disable such matching:

File.fnmatch('foo?boo', 'foo/boo')                       # => true
File.fnmatch('foo?boo', 'foo/boo', File::FNM_PATHNAME)   # => false

Constant File::FNM_SHORTNAME

By default, Windows shortname matching is disabled; use constant File::FNM_SHORTNAME to enable it (on Windows only).

Using that constant allows patterns to match short names in filename matching on Windows, which can be useful for compatibility with legacy applications that rely on these short names; see 8.3 filename. This feature helps ensure that file operations work correctly even when dealing with files that have long names.

File::FNM_SHORTNAME.zero? # => false  # On Windows, not zero; may be enabled.
File::FNM_SHORTNAME.zero? # => true   # Elsewhere, always zero; may not be enabled.

File.fnmatch('PROGRAM~1', 'Program Files') # => false
# This will be true if and only if on Windows and short name 'PROGRAM~1' exists.
File.fnmatch('PROGRAM~1', 'Program Files', File::FNM_SHORTNAME) # => true

Constant File::FNM_SYSCASE

By default, filename matching uses Ruby’s own case-sensitivity rules; use constant File::FNM_SYSCASE to use the case-sensitivity rules of the underlying file system:

File::FNM_SYSCASE.zero? # => false  # On Windows, not zero; may be enabled.
File::FNM_SYSCASE.zero? # => true   # Elsewhere, always zero; may not be enabled.

File.fnmatch('abc', 'ABC')                    # => false  # Ruby; case-sensitive.
File.fnmatch('abc', 'ABC', File::FNM_SYSCASE) # => true   # Windows; case-insensitive.
File.fnmatch('abc', 'ABC', File::FNM_SYSCASE) # => false  # Linus; case-sensitive.