Pattern Lists

File name patterns and lists of file name patterns are used throughout Qgoda for definining sets of files and directories.

Lists of search patterns in Qgoda follow the convention of gitignore, only that you put your configuration in a YAML file _config.yaml and not in a file .gitignore.

As an example we use the configuration variable exclude which is used for excluding files from being processed.

Special Characters

Some characters in patterns have a special meaning.

The Star/Asterisk *

The star or asterisk stands for an arbitrary number of characters except for a slash:

exclude:
- images/*.xcf

This will exclude all XCF files in the subdirectory images for example images/logo.xcf but not images/ci/logo.xcf (because the star/asterisk does not match a slash).

Note that *.xcf also matches the file .xcf. The star stands for an arbitrary number of characters and that includes zero characters.

The Double Star/Asterisk **

Two consecutive stars ** stand for any sequence of characters including the slash.

exclude:
- images/**/*.xcf

This now matches images/ci/logo.xcf and images/logo.xcf and also images/nothing/beats/nesting/logo.xcf. The pattern ** matches recursively.

The Exclamation Mark !

The exclamation mark negates a pattern. See below for details.

The Question Mark ?

The question mark standard for any character except for a slash.

exclude:
- images/corporate?logos

This matches images/corporate-logos and images/corporate_logos and images/corporatedQlogos and images/corporate&logos.

Character [Ranges]

It's getting esoteric.

exclude:
- images/[abc].jpeg

This matches exactly images/a.jpeg, images/b.jpeg, and images/c.jpeg. Instead, you could also write this:

exclude:
- images/[a-c].jpeg

Read the [a-c] as all characters from a to c.

You can combine ranges:

exclude:
- images/[a-z0-9].jpeg

This would now match x.jpeg and 3.jpeg.

Character ranges cannot be empty, and therefore [] does not stand for no character. It is simply not special. Use []abc] if you want to match a, b, c, and a closing square bracket.

And put the hyphen at the front if you want to match it: [-a-zA-Z0-9]. That matches all alphanumeric characters and the hyphen.

You can also use named character classes like [a-zA-Z[:digit:]] where [:digit] stands for any digit in the current locale. Using this feature is discouraged unless you understand it.

The Backslash ""

You can escape any character by preceding it with a backslash "".

exclude:
- images/Quo Vadis\?.jpeg

This matches only images/Quo Vadis?.jpeg but not images/Quo VadissX.jpeg. The question mark has lost its special meaning by the preceding backslash.

Negating Patterns

It is possible to negate patterns with a leading exclamation mark:

exclude:
- /_*
- "!/_posts"

This would exclude all files and directories with names starting with an underscore but not the directory _posts.

Exclusion and Inclusion Mode

Search patterns behave slightly different, when they are used for excluding files (as opposed to including files). With pattern lists used for excluding files, you cannot re-include files or directories, when one of their parent directories is already excluded.

Example:

exclude:
- /archive
- "!/archive/2017"

The second pattern is invalid and ignored because /archive is a parent directory of /archive/2017.

This behavior has performance reasons. When Qgoda collects files, it does not descend into excluded directories. In the above example, it would not read the contents of archive and would therefore never see the subdirectory archive/2017.

That leads to a little problem if you want to re-include a subdirectory of an automatically excluded directory, for example _experiments/stable. The top-level directory _experiments is automatically excluded by Qgoda. In order to re-include it, you would have to do the following:

exclude:
- "!/_experiments"
- /_experiments/*
- "!/_experiments/stable"

You have to keep in mind that Qgoda has prepended this list with /_* (see Excluding Files). Line 1 re-includes _experiments. Line 2 excludes all its subdirectories again. And line 3 selectively re-includes _experiments/stable.

Slashes

Leading Slashes

A leading slash anchors the pattern to the source directory.

Example:

exclude:
- /package.json
- TODO

The first patterns starts with a slash. It therefore excludes the top-level file package.json but it would not exclude a/b/c/package.json.

The second pattern is not anchored to the source directory. It would therefore match TODO as well as a/TODO or a/b/TODO.

Trailing Slashes

A trailing slash causes a pattern only to match directories:

exclude:
- /src/lib/

This would exclude src/lib only if it is a directory. A regular file src/lib would not be affected.

Other Slashes

Every slash inside a pattern causes the entire file name to be taken into account when matching:

exclude:
- posts/experiments/dangerous-minds.md

This would exclude posts/experiments/dangerous-minds.md. It does not exclude a file dangerous-minds.md in other locations. It also does not exclude a/b/posts/experiments/dangerous-minds.md.

As you can see, a slash in the middle of a pattern effectively anchors the pattern to the source directory, and you can therefore almost always omit a leading slash, when there are more slashes following. The following two patterns are absolutely equivalent:

exclude:
- posts/experiments/dangerous-minds.md
- /posts/experiments/dangerous-minds.md