Document file-matcher behavior for refs w/o files

This change documents the behavior of file matchers for refs that don't
contain any files.

This documents the behavior that was introduced with
Icf5df145e4cd351ffd04b1e417e9f7ab8c5ccd12 after the related discussion
in If7a3a7cc212c981529be086dadb8157f08bda342.

Change-Id: I579dd6b50cd50a78d5e846f7c2376ffc9e7ba4a1

1 files changed, 16 insertions, 0 deletions

diff --git a/doc/source/config/job.rst b/doc/source/config/job.rst
index 435d68e7e..f9e7b7b71 100644
--- a/doc/source/config/job.rst
+++ b/doc/source/config/job.rst
@@ -1046,6 +1046,14 @@ Here is an example of two job definitions:
       value is used to determine if the job should run. This is a
       :ref:`regular expression <regex>` or list of regular expressions.
 
+      .. warning::
+
+         File filters will be ignored for refs that don't have any
+         files. This will be the case for merge commits (e.g. in a post
+         pipeline) or empty commits created with
+         ``git commit --allow-empty`` (which can be used in order to
+         run all jobs).
+
    .. attr:: irrelevant-files
 
       This is a negative complement of **files**.  It indicates that
@@ -1055,6 +1063,14 @@ Here is an example of two job definitions:
       are in the docs directory.  A :ref:`regular expression <regex>`
       or list of regular expressions.
 
+      .. warning::
+
+         File filters will be ignored for refs that don't have any
+         files. This will be the case for merge commits (e.g. in a post
+         pipeline) or empty commits created with
+         ``git commit --allow-empty`` (which can be used in order to
+         run all jobs).
+
    .. attr:: match-on-config-updates
       :default: true