Document examples for caveats with find-owners path expressions
This should make it even clearer how find-owners path expressions work.
Signed-off-by: Edwin Kempin <ekempin@google.com>
Change-Id: I02a8d1dfb5b83b07a0248708e2aeb2f16f91c1d0
diff --git a/resources/Documentation/path-expressions.md b/resources/Documentation/path-expressions.md
index 7b976ef..a8fc387 100644
--- a/resources/Documentation/path-expressions.md
+++ b/resources/Documentation/path-expressions.md
@@ -9,8 +9,9 @@
* [find-owners](backend-find-owners.html) backend:
uses [globs](#globs), 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)
+ 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](#findOwnersCaveat) section below)
* [proto](backend-proto.html) backend:
uses [simple path expressions](#simplePathExpressions)
@@ -40,15 +41,17 @@
| To Match | Glob | find-owners | Simple Path Expression |
| -------- | ---- | ----------- | ---------------------- |
-| Concrete file in current folder | `BUILD` | not possible (1) | `BUILD` |
-| File type in current folder | `*.md` | not possible (1) | `*.md` |
+| Concrete file in current folder | `BUILD` | [not possible](#findOwnersCaveatMatchingAFile) | `BUILD` |
+| File type in current folder | `*.md` | [not possible](#findOwnersCaveatMatchingFilesByType) | `*.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 (1), but you can add a `my-folder/OWNERS` file instead of using a glob | `my-folder/...` |
+| All files in a subfolder | `my-folder/**` | [not possible](#findOwnersCaveatMatchingFilesInSubfolder), 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
-(1): To be compatible with the `find-owners` plugin find-owners path expressions
+## <a id="findOwnersCaveat">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](path-expressions.html)). This means if path expressions like `BUILD`,
`*.md` or `my-folder/**` are used in `OWNERS` files the effective path
@@ -58,6 +61,41 @@
`my-folder/**` in any subfolder (e.g. `foo/bar/BUILD`, `foo/bar/baz.md` and
`foo/bar/my-folder/`).
+### Examples
+
+#### <a id="findOwnersCaveatMatchingAFile">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`.
+
+#### <a id="findOwnersCaveatMatchingFilesByType">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`.
+
+#### <a id="findOwnersCaveatMatchingFilesInSubfolder">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](index.html)
