From d64060ace0cf96995458f10dc345523fbe113d6a Mon Sep 17 00:00:00 2001
From: Brian Coca <brian.coca+git@gmail.com>
Date: Sun, 24 Jul 2016 21:32:04 -0400
Subject: [PATCH] updated docs to reflect new feature

---
 utilities/logic/include_vars.py | 28 +++++++++++++++++++++++-----
 1 file changed, 23 insertions(+), 5 deletions(-)

diff --git a/utilities/logic/include_vars.py b/utilities/logic/include_vars.py
index fb55ab5515f..a0b3280d807 100644
--- a/utilities/logic/include_vars.py
+++ b/utilities/logic/include_vars.py
@@ -16,17 +16,32 @@ short_description: Load variables from files, dynamically within a task.
 description:
      - Loads variables from a YAML/JSON file dynamically during task runtime.  It can work with conditionals, or use host specific variables to determine the path name to load from.
 options:
+  file:
+    version_added: "2.2"
+    description:
+       - The file name from which variables should be loaded.
+       - If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook.
+  name:
+    version_added: "2.2"
+    description:
+        - The name of a variable into which assign the included vars, if omitted (null) they will be made top level vars.
+    default: null
   free-form:
     description:
-       - The file name from which variables should be loaded, if called from a role it will look for 
-         the file in vars/ subdirectory of the role, otherwise the path would be relative to playbook. An absolute path can also be provided.
-    required: true
+        - This module allows you to specify the 'file' option directly w/o any other options.
+notes:
+    - The file is always required either as the explicit option or using the free-form.
 version_added: "1.4"
 '''
 
 EXAMPLES = """
-# Conditionally decide to load in variables when x is 0, otherwise do not.
-- include_vars: contingency_plan.yml
+# Include vars of stuff.yml into the 'stuff' variable (2.2).
+- include_vars:
+    file: stuff.yml
+    name: stuff
+
+# Conditionally decide to load in variables into 'plans' when x is 0, otherwise do not. (2.2)
+- include_vars: file=contingency_plan.yml name=plans
   when: x == 0
 
 # Load a variable file based on the OS type, or a default if not found.
@@ -36,4 +51,7 @@ EXAMPLES = """
    - "{{ ansible_os_family }}.yml"
    - "default.yml"
 
+# bare include (free-form)
+- include_vars: myvars.yml
+
 """