Skip to content

Latest commit

 

History

History
117 lines (86 loc) · 4.61 KB

path-expressions.md

File metadata and controls

117 lines (86 loc) · 4.61 KB

Path Expressions

Path expressions are used to restrict access grants in code owner config files to only apply to a subset of files in a directory (e.g. see per-file rule for the find-owners backend).

The following path expression syntaxes are supported:

  • GLOB: Uses globs to match paths.
  • FIND_OWNERS_GLOB: Uses globs to match paths, but each glob is automatically prefixed with {**/,} so that subfolders are always matched, e.g. *.md matches all md files in all subfolders, rather then only md files in the current folder (also see the caveat section below).
  • SIMPLE: Uses simple path expressions to match paths.

Which syntax is used by default depends on the used code owner backend:

  • find-owners backend: Uses FIND_OWNERS_GLOB as path expression syntax.
  • proto backend: Uses SIMPLE as path expression syntax.

The default path expression syntax that is derived from the backend can be overriden by global configuration, on project-level or on branch-level.

Globs

Globs support the following wildcards:

  • *: matches any string that does not include slashes
  • **: matches any string, including slashes
  • ?: matches any character
  • [abc]: matches one character given in the bracket
  • [a-c]: matches one character from the range given in the bracket
  • {html,htm}: matches either of the 2 expressions, html or htm

See below for examples.

Simple path expressions

Simple path expressions use the following wildcards:

  • *: matches any string that does not include slashes
  • ...: matches any string, including slashes

See below for examples.

Examples

To Match Glob find-owners Simple Path Expression
Concrete file in current folder BUILD not possible BUILD
File type in current folder *.md not possible *.md
Concrete file in the current folder and in all subfolders {**/,}BUILD BUILD needs 2 expressions: BUILD + .../BUILD
File type in the current folder and in all subfolders **.md *.md or **.md ....md
All files in a subfolder my-folder/** not possible, but you can add a my-folder/OWNERS file instead of using a glob my-folder/...
All “foo-<1-digit-number>.txt” files in all subfolders {**/,}foo-[0-9].txt foo-[0-9].txt not possible
All “foo-<n-digit-number>.txt” files in all subfolders not possible not possible not possible

Caveat with find-owners path expressions

To be compatible with the find-owners plugin find-owners path expressions are prefixes with {**/,} which matches any folder (see above). This means if path expressions like BUILD, *.md or my-folder/** are used in OWNERS files the effective path expression are {**/,}BUILD, {**/,}*.md and {**/,}my-folder/**. These path expression do not only match BUILD, *.md and my-folder/** directly in the folder that contains the OWNERS file but also BUILD, *.md and my-folder/** in any subfolder (e.g. foo/bar/BUILD, foo/bar/baz.md and foo/bar/my-folder/).

Examples

Matching a file

If you have the following /foo/OWNERS file:

  per-file BUILD=john.doe@example.com


John Doe owns the /foo/BUILD file, but also all BUILD files in subfolders of /foo/, e.g. /foo/bar/baz/BUILD.

Matching files by type

If you have the following /foo/OWNERS file:

  per-file *.md=john.doe@example.com


John Doe owns all *.md files in /foo/, but also all *.md files in subfolders of /foo/, e.g. /foo/bar/baz.md.

Matching files in subfolder

If you have the following /foo/OWNERS file:

  per-file my-folder/*=john.doe@example.com


John Doe owns all files in the /foo/my-folder/ folder, but also all files in any my-folder/ subfolder, e.g. all files in /foo/bar/baz/my-folder/.

Back to @PLUGIN@ documentation index

Part of Gerrit Code Review