Merge pull request #9270 from bcoca/do_the_shuffle

added new 'shuffle' filter

1 files changed, 14 insertions, 0 deletions

diff --git a/docsite/rst/playbooks_variables.rst b/docsite/rst/playbooks_variables.rst
index 34d5a77be4..08b8ce60eb 100644
--- a/docsite/rst/playbooks_variables.rst
+++ b/docsite/rst/playbooks_variables.rst
@@ -297,6 +297,20 @@ Get a random number from 1 to 100 but in steps of 10::
     {{ 100 |random(start=1, step=10) }}    => 51
 
 
+Shuffle Filter
+--------------
+
+.. versionadded:: 1.8
+
+This filter will randomize an existing list, giving a differnt order every invocation.
+
+To get a random list from an existing  list::
+
+    {{ ['a','b','c']|shuffle }} => ['c','a','b']
+    {{ ['a','b','c']|shuffle }} => ['b','c','a']
+
+note that when used with a non 'listable' item it is a noop, otherwise it always returns a list
+
 .. _other_useful_filters:
 
 Other Useful Filters