glob

glob is a file and directory globbing library that supports both checking whether a path matches a glob and listing all entities that match a glob.

A "glob" is a pattern designed specifically to match files and directories. Most shells support globs natively.

Usage

To construct a glob, just use Glob(). As with RegExps, it's a good idea to keep around a glob if you'll be using it more than once so that it doesn't have to be compiled over and over. You can check whether a path matches the glob using Glob.matches():

import 'package:glob/glob.dart';
                
                final dartFile = Glob("**.dart");
                
                // Print all command-line arguments that are Dart files.
                void main(List<String> arguments) {
                  for (var argument in arguments) {
                    if (dartFile.matches(argument)) print(argument);
                  }
                }
                

You can also list all files that match a glob using Glob.list() or Glob.listSync():

import 'package:glob/glob.dart';
                import 'package:glob/list_local_fs.dart';
                
                final dartFile = Glob("**.dart");
                
                // Recursively list all Dart files in the current directory.
                void main(List<String> arguments) {
                  for (var entity in dartFile.listSync()) {
                    print(entity.path);
                  }
                }
                

Syntax

The glob syntax hews closely to the widely-known Bash glob syntax, with a few exceptions that are outlined below.

In order to be as cross-platform and as close to the Bash syntax as possible, all globs use POSIX path syntax, including using / as a directory separator regardless of which platform they're on. This is true even for Windows roots; for example, a glob matching all files in the C drive would be C:/*.

Globs are case-sensitive by default on Posix systems and browsers, and case-insensitive by default on Windows.

Match any characters in a filename: *

The * character matches zero or more of any character other than /. This means that it can be used to match all files in a given directory that match a pattern without also matching files in a subdirectory. For example, lib/*.dart will match lib/glob.dart but not lib/src/utils.dart.

Match any characters across directories: **

** is like *, but matches / as well. It's useful for matching files or listing directories recursively. For example, lib/**.dart will match both lib/glob.dart and lib/src/utils.dart.

If ** appears at the beginning of a glob, it won't match absolute paths or paths beginning with ../. For example, **.dart won't match /foo.dart, although /**.dart will. This is to ensure that listing a bunch of paths and checking whether they match a glob produces the same results as listing that glob. In the previous example, /foo.dart wouldn't be listed for **.dart, so it shouldn't be matched by it either.

This is an extension to Bash glob syntax that's widely supported by other glob implementations.

Match any single character: ?

The ? character matches a single character other than /. Unlike *, it won't match any more or fewer than one character. For example, test?.dart will match test1.dart but not test10.dart or test.dart.

Match a range of characters: [...]

The [...] construction matches one of several characters. It can contain individual characters, such as [abc], in which case it will match any of those characters; it can contain ranges, such as [a-zA-Z], in which case it will match any characters that fall within the range; or it can contain a mix of both. It will only ever match a single character. For example, test[a-zA-Z_].dart will match testx.dart, testA.dart, and test_.dart, but not test-.dart.

If it starts with ^ or !, the construction will instead match all characters not mentioned. For example, test[^a-z].dart will match test1.dart but not testa.dart.

This construction never matches /.

Match one of several possibilities: {...,...}

The {...,...} construction matches one of several options, each of which is a glob itself. For example, lib/{*.dart,src/*} matches lib/glob.dart and lib/src/data.txt. It can contain any number of options greater than one, and can even contain nested options.

This is an extension to Bash glob syntax, although it is supported by other layers of Bash and is often used in conjunction with globs.

Escaping a character: \

The \ character can be used in any context to escape a character that would otherwise be semantically meaningful. For example, \*.dart matches *.dart but not test.dart.

Syntax errors

Because they're used as part of the shell, almost all strings are valid Bash globs. This implementation is more picky, and performs some validation to ensure that globs are meaningful. For instance, unclosed { and [ are disallowed.

Reserved syntax: (...)

Parentheses are reserved in case this package adds support for Bash extended globbing in the future. For the time being, using them will throw an error unless they're escaped.

2.2.0

• Limit option expansion during glob listing (list() and listSync()) to a maximum of 10,000 branches. Globs with combinatorial option expansions exceeding 10,000 will now throw a FormatException to prevent out-of-memory exhaustion. Glob.matches() uses regular expressions and is unaffected.
• Allow ** to match zero directories at the start of a pattern or following a separator (e.g. **/foo matches foo and a/**/b matches a/b).

2.1.3

• Require Dart 3.3.
• Move to dart-lang/tools monorepo.

2.1.2

• Allow file version 7.x.
• Require Dart 2.19.

2.1.1

• Updated the dependency on package:file to require at least 6.1.3.

2.1.0

• Return empty results instead of throwing when trying to list a path that does not exist.

2.0.2

• Drop package:pedantic dependency, use package:lints instead.
• Update SDK lower bound to 2.15.0

2.0.1

• Update example in README for new import.

2.0.0

• Stable null safety release.

Breaking Change

The list* apis on Glob have been renamed to listFileSystem* and they now require a FileSystem object from package:file.

There is a new convenience import, package:glob/list_local_fs.dart which provides the old methods as extensions, and automatically passes a LocalFileSystem.

1.2.1

• Add an empty list_local_fs.dart to ease upgrade from 1x to 2x

1.2.0

• Support running on Node.js.

1.1.7

• Set max SDK version to <3.0.0, and adjust other dependencies.

1.1.6

• Improve support for Dart 2 runtime semantics.

1.1.5

• Declare support for async 2.0.0.

• Require Dart 1.23.0.

1.1.4

• Throw an exception when listing globs whose initial paths don't exist in case-insensitive mode. This matches the case-sensitive behavior.

1.1.3

• Support string_scanner 1.0.0.

1.1.2

• Fix all strong mode errors and warnings.

1.1.1

• Fix a bug where listing an absolute glob with caseInsensitive: false failed.

1.1.0

• Add a caseSensitive named parameter to new Glob() that controls whether the glob is case-sensitive. This defaults to false on Windows and true elsewhere.

  Matching case-insensitively on Windows is a behavioral change, but since it more closely matches the semantics of Windows paths it's considered a bug fix rather than a breaking change.

1.0.5

• Narrow the dependency on path. Previously, this allowed versions that didn't support all the functionality this package needs.

• Upgrade to the new test runner.

1.0.4

• Added overlooked collection dependency.

1.0.3

• Fix a bug where Glob.list() and Glob.listSync() would incorrectly throw exceptions when a directory didn't exist on the filesystem.

1.0.2

• Fixed Glob.list() on Windows.

1.0.1

• Fix several analyzer warnings.

• Fix the tests on Windows.