From 74999a5dcca1fb85f677a598a6aece825348d738 Mon Sep 17 00:00:00 2001
From: Matthew Treinish <mtreinish@kortar.org>
Date: Tue, 10 May 2016 17:18:17 -0400
Subject: [PATCH] Add whitelist file to ostestr docs

This commit adds the missing details for the whitelist file to the
ostestr docs.

Change-Id: I863dcad9b1a77a083f7007ab76760e77295c610d
---
 doc/source/ostestr.rst | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/doc/source/ostestr.rst b/doc/source/ostestr.rst
index ac1290f..bc9d65a 100644
--- a/doc/source/ostestr.rst
+++ b/doc/source/ostestr.rst
@@ -14,6 +14,7 @@ default behavior might change in future version.
 Summary
 -------
     ostestr [-b|--blacklist_file <blacklist_file>] [-r|--regex REGEX]
+            [-w|--whitelist_file <whitelist_file>]
             [-p|--pretty] [--no-pretty] [-s|--subunit] [-l|--list]
             [-n|--no-discover <test_id>] [--slowest] [--no-slowest]
             [--pdb <test_id>] [--parallel] [--serial]
@@ -25,6 +26,9 @@ Options
   --blacklist_file BLACKLIST_FILE, -b BLACKLIST_FILE
                         Path to a blacklist file, this file contains a
                         separate regex exclude on each newline
+  --whitelist_file WHITELIST_FILE, -w WHITELIST_FILE
+                        Path to a whitelist file, this file contains a
+                        separate regex on each newline
   --regex REGEX, -r REGEX
                         A normal testr selection regex. If a blacklist file is
                         specified, the regex will be appended to the end of
@@ -134,6 +138,22 @@ regex test selection options can not be used in conjunction with the
 because the regex selection requires using testr under the covers to actually
 do the filtering, and those 2 options do not use testr.
 
+The dual of the blacklist file is the whitelist file which works in the exact
+same manner, except that instead of excluding regex matches it includes them.
+You can specify the path to the file with --whitelist_file/-w, for example::
+
+    $ ostestr --whitelist_file $path_to_file
+
+The format for the file is more or less identical to the blacklist file::
+
+    # Whitelist File
+    ^regex1 # Include these tests
+    .*regex2 # include those tests
+
+However, instead of excluding the matches it will include them. Note that a
+blacklist file can not be used at the same time as a whitelist file, they
+are mutually exclusive.
+
 It's also worth noting that you can use the test list option to dry run any
 selection arguments you are using. You just need to use --list/-l with your
 selection options to do this, for example::