Provide the list of files that were included by include_vars

include_vars will now also return a key 'ansible_included_var_files'
which contains the list of files that were successfully loaded.
This is useful information and, amongst other things, a way for users
to know exactly what files were included when debugging their
playbooks.
This also allows us to improve the integration tests around
include_vars.

lib/ansible/modules/utilities/logic/include_vars.py

@@ -120,3 +120,17 @@ EXAMPLES = """
     ignore_files: 'bastion.yml'
     extensions: ['yml']
 """
+
+RETURN = '''
+ansible_facts:
+  description: Variables that were included and their values
+  returned: success
+  type: dict
+  sample: {'variable': 'value'}
+ansible_included_var_files:
+  description: A list of files that were successfully included
+  returned: success
+  type: list
+  sample: [ '/path/to/file.yml', '/path/to/file.json' ]
+  version_added: 2.4
+'''

lib/ansible/plugins/action/include_vars.py

@@ -84,6 +84,7 @@ class ActionModule(ActionBase):
             task_vars = dict()
 
         self.show_content = True
+        self.included_files = []
 
         # Validate arguments
         dirs = 0
@@ -141,6 +142,7 @@ class ActionModule(ActionBase):
             result['failed'] = failed
             result['message'] = err_msg
 
+        result['ansible_included_var_files'] = self.included_files
         result['ansible_facts'] = results
         result['_ansible_no_log'] = not self.show_content
 
@@ -237,6 +239,7 @@ class ActionModule(ActionBase):
                 failed = True
                 err_msg = ('{0} must be stored as a dictionary/hash' .format(filename))
             else:
+                self.included_files.append(filename)
                 results.update(data)
 
         return failed, err_msg, results

test/integration/targets/include_vars/tasks/main.yml

@@ -8,12 +8,15 @@
 - name: include the vars/environments/development/all.yml
   include_vars:
     file: environments/development/all.yml
+  register: included_one_file
 
-- name: verify that the default value is indeed 789
+- name: verify that the correct file has been loaded and default value is indeed 789
   assert:
     that:
       - "testing == 789"
       - "base_dir == 'environments/development'"
+      - "{{ included_one_file.ansible_included_var_files | length }} == 1"
+      - "'vars/environments/development/all.yml' in included_one_file.ansible_included_var_files[0]"
 
 - name: include the vars/environments/development/all.yml and save results in all
   include_vars:
@@ -40,30 +43,40 @@
 - name: include every directory in vars
   include_vars:
     dir: vars
+  register: include_every_dir
 
-- name: verify that the variable overwrite based on alphabetical order
+- name: verify that the correct files have been loaded and overwrite based on alphabetical order
   assert:
     that:
       - "testing == 456"
       - "base_dir == 'services'"
       - "webapp_containers == 10"
+      - "{{ include_every_dir.ansible_included_var_files | length }} == 4"
+      - "'vars/all/all.yml' in include_every_dir.ansible_included_var_files[0]"
+      - "'vars/environments/development/all.yml' in include_every_dir.ansible_included_var_files[1]"
+      - "'vars/environments/development/services/webapp.yml' in include_every_dir.ansible_included_var_files[2]"
+      - "'vars/services/webapp.yml' in include_every_dir.ansible_included_var_files[3]"
 
 - name: include every directory in vars except files matching webapp.yml
   include_vars:
     dir: vars
     ignore_files:
       - webapp.yml
+  register: include_without_webapp
 
 - name: verify that the webapp.yml file was not included
   assert:
     that:
       - "testing == 789"
       - "base_dir == 'environments/development'"
+      - "{{ include_without_webapp.ansible_included_var_files | length }} == 2"
+      - "'webapp.yml' not in '{{ include_without_webapp.ansible_included_var_files | join(' ') }}'"
 
 - name: include only files matching webapp.yml
   include_vars:
     dir: environments
     files_matching: webapp.yml
+  register: include_match_webapp
 
 - name: verify that only files matching webapp.yml and in the environments directory get loaded.
   assert:
@@ -71,6 +84,9 @@
       - "testing == 101112"
       - "base_dir == 'development/services'"
       - "webapp_containers == 20"
+      - "{{ include_match_webapp.ansible_included_var_files | length }} == 1"
+      - "'vars/environments/development/services/webapp.yml' in include_match_webapp.ansible_included_var_files[0]"
+      - "'all.yml' not in '{{ include_match_webapp.ansible_included_var_files | join(' ') }}'"
 
 - name: include only files matching webapp.yml and store results in webapp
   include_vars: