Glob Patterns¶

A glob pattern is a textual pattern that uses wildcard characters to match file names. For example, * matches any canonical file name, and README.txt matches the file whose canonical name is exactly README.txt.

VisionByte treats a stored file name as one complete string. Directory separators do not create a separate matching scope. As a result, * can match zero or more characters including directory prefixes, and */* can match a name with one or more directory components.

Glob patterns are not regular expressions. The two pattern languages use some of the same characters, but their syntax and matching rules are different. VisionByte uses glob patterns, not regular expressions, for the file-name matching settings and command options described in this page.

Glob Lists¶

When VisionByte accepts a glob list, the list is usually separated by ASCII whitespace or commas. A pattern may contain spaces or commas only when the whole pattern is enclosed in ASCII single quotes or ASCII double quotes.

If a pattern begins with a quote character, it ends at the next occurrence of the same quote character. The delimiter quotes are not part of the pattern. Quote characters that do not begin a pattern are treated as ordinary characters.

For example, the following list contains two patterns:

"foo bar" qux

The first pattern is foo bar and the second pattern is qux.

A glob list matches a file when at least one pattern in the list matches that file. Each pattern must match the whole canonical file name. A partial match is not a match.

Pattern Syntax¶

Most characters in a glob pattern match exactly one identical character in the file name. The following characters and character sequences have special meaning:

Pattern element	Meaning
`*`	Matches any sequence of zero or more characters, including `/`.
`?`	Matches exactly one character, including `/`.
`[...]`	Matches exactly one character that is listed inside the brackets.
`[^...]`	Matches exactly one character that is not listed inside the brackets.

The special pattern elements can match the / directory separator. They can also match a leading . in a hidden file or directory name. This behavior follows from VisionByte matching each canonical file name as one complete string.

Bracket Expressions¶

Inside [...] and [^...], a range may be written with -. For example, [a-f] matches exactly the same set of characters as [abcdef]. Ranges are evaluated by Unicode code point order; they do not use locale-specific collation rules.

A range must be written from the lower code point to the higher code point. A reversed range such as [z-a] matches no character, which prevents the enclosing glob pattern from matching.

Examples:

Pattern element	Meaning
`[a-d]`	Matches one of `a`, `b`, `c`, or `d`.
`[^a-d]`	Matches one character other than `a`, `b`, `c`, or `d`.
`[0-9a-fA-F]`	Matches one hexadecimal digit.
`[a-]`	Matches `a` or `-`.
`[][]`	Matches `]` or `[`.
`[^]]`	Matches one character other than `]`.
`[]^]`	Matches `]` or `^`.
`[^-]`	Matches one character other than `-`.

Whitespace and Quotes¶

For glob-list parsing, whitespace means only these ASCII characters: TAB, LF, VT, FF, CR, and SPACE. Unicode space characters such as U+00A0 NO-BREAK SPACE are not whitespace separators.

Because LF and CR are whitespace, and because leading and trailing whitespace is removed from each pattern in a list, a glob list stored in a file may place one pattern on each line.

Only ASCII straight quotes have special meaning as quote delimiters: single quote (') and double quote ("). Typographic quotation marks are ordinary characters.

Filename Matching¶

Before VisionByte compares a file name with a glob pattern, the file name is converted to canonical form:

Directory separators are written as /.
Concrete repository file names are relative to the root of the working copy.
Matching is case-sensitive.

The glob pattern must match the whole canonical file name.

The canonical form makes glob behavior portable across supported platforms. A versioned setting that contains a glob list is interpreted the same way when the same repository is opened on different operating systems.

VisionByte glob matching is case-sensitive regardless of host platform or file-system behavior. This matters on platforms such as Windows and some macOS file systems, where the file system may preserve case but treat names that differ only by case as the same file. Write each glob pattern to match the exact file names stored in the repository.

Examples:

Pattern	Result
`README`	Matches only `README` at the tree root. It does not match `src/README` because the pattern has no characters that match the `src/` prefix.
`*/README`	Matches `src/README` and `src/library/README`. It does not match `README` at the tree root.
`*README`	Matches `README`, `src/README`, `foo/bar/README`, and any other canonical file name ending in `README`.
`src/README`	Matches a file stored as `src/README`. On Windows, a working-tree path such as `src\README` is canonicalized to `src/README` before glob matching.
`*.[ch]`	Matches C source and header files at the tree root or at any directory depth.

Where Glob Lists Are Used¶

Several settings use glob lists to classify or filter files, including binary-glob, clean-glob, crlf-glob, crnl-glob, encoding-glob, fileedit-glob, ignore-glob, and keep-glob.

Many commands accept glob-list options that override or supplement those settings for one command invocation. Examples include add, addremove, changes, clean, commit, extras, merge, settings, status, touch, and unset.

Archive commands such as tarball and zip use glob lists to include or exclude files from the generated archive.

Web-serving commands such as cgi, http, server, and ui use glob lists to decide which static files may be served.

Always consult the command-specific option documentation for precedence rules. For example, an include glob and an exclude glob may both match the same file, and the command determines which rule wins.

Shell Interaction¶

When a glob pattern is passed on the command line, the operating-system shell may process wildcard characters before VisionByte receives the argument. To force VisionByte to interpret a pattern itself, quote or escape the argument according to the rules of the shell that starts vb.