Add docs to `only:changes/except:changes` that discuss using regex in certain scenarios

1 files changed, 27 insertions, 3 deletions

diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 83a226d3577..e75f7050a09 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -501,7 +501,7 @@ Learn more about [variables expressions](../variables/README.md#variables-expres
 
 #### `only:changes`/`except:changes`
 
-Using the `changes` keyword with `only` or `except`, makes it possible to define if
+Using the `changes` keyword with `only` or `except` makes it possible to define if
 a job should be created based on files modified by a git push event.
 
 For example:
@@ -518,14 +518,38 @@ docker build:
 ```
 
 In the scenario above, when pushing multiple commits to GitLab to an existing
-branch, GitLab creates and triggers `docker build` job, provided that one of the
-commits contains changes to either:
+branch, GitLab creates and triggers the `docker build` job, provided that one of the
+commits contains changes to any of the following:
 
 - The `Dockerfile` file.
 - Any of the files inside `docker/scripts/` directory.
 - Any of the files and subdirectories inside the `dockerfiles` directory.
 - Any of the files with `rb`, `py`, `sh` extensions inside the `more_scripts` directory.
 
+You can also use glob patterns to match multiple files in either the root directory of the repo, or in _any_ directory within the repo. For example:
+
+```yaml
+test:
+  script: npm run test
+  only:
+    changes:
+      - "*.json"
+      - "**/*.sql"
+```
+
+NOTE: **Note:**
+In the example above, the expressions are wrapped double quotes because they are glob patterns. GitLab will fail to parse `.gitlab-ci.yml` files with unwrapped glob patterns.
+
+The following example will skip the CI job if a change is detected in any file in the root directory of the repo with a `.md` extension:
+
+```yaml
+build:
+  script: npm run build
+  except:
+    changes:
+      - "*.md"
+```
+
 CAUTION: **Warning:**
 There are some caveats when using this feature with new branches and tags. See
 the section below.