Lists of search patterns in Qgoda follow the convention of gitignore, only that you put your configuration in a YAML file _qgoda.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.
Some characters in patterns have a special meaning.
*
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.
**
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 negates a pattern. See below for details.
The exclamation mark ! is a special character in YAML and JSON. You therefore have to put negated patters into quotes, for example "!a/b".
?
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.
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.
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.
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.
The exclamation mark ! is a special character in YAML and JSON. You therefore have to put negated patters into quotes, for example "!a/b".
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.
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.
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.
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