From fa1564c548d3fb1dbb82a013ad11930ce8d3d10e Mon Sep 17 00:00:00 2001
From: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
Date: Tue, 7 Feb 2023 16:31:08 -0500
Subject: [PATCH] include_vars - document hash_behaviour + dir (#79790)

* document that hash_behaviour does not apply to individual files of variables when using the dir option

* add tests
---
 lib/ansible/modules/include_vars.py               |  1 +
 .../targets/include_vars/tasks/main.yml           | 15 +++++++++++++++
 2 files changed, 16 insertions(+)

diff --git a/lib/ansible/modules/include_vars.py b/lib/ansible/modules/include_vars.py
index f0aad94ad44..b39a5fe2e5f 100644
--- a/lib/ansible/modules/include_vars.py
+++ b/lib/ansible/modules/include_vars.py
@@ -75,6 +75,7 @@ options:
     description:
       - If set to C(merge), merges existing hash variables instead of overwriting them.
       - If omitted C(null), the behavior falls back to the global I(hash_behaviour) configuration.
+      - This option is self-contained and does not apply to individual files in C(dir). You can use a loop to apply C(hash_behaviour) per file.
     default: null
     type: str
     choices: ["replace", "merge"]
diff --git a/test/integration/targets/include_vars/tasks/main.yml b/test/integration/targets/include_vars/tasks/main.yml
index db15ba3c5db..dc12d2bb5ed 100644
--- a/test/integration/targets/include_vars/tasks/main.yml
+++ b/test/integration/targets/include_vars/tasks/main.yml
@@ -208,6 +208,21 @@
       - "config.key2.b == 22"
       - "config.key3 == 3"
 
+- name: Include a vars dir with hash variables
+  include_vars:
+    dir: "{{ role_path }}/vars2/hashes/"
+    hash_behaviour: merge
+
+- name: Verify that the hash is merged after vars files are accumulated
+  assert:
+    that:
+      - "{{ config | length }} == 3"
+      - "config.key0 is undefined"
+      - "config.key1 == 1"
+      - "{{ config.key2 | length }} == 1"
+      - "config.key2.b == 22"
+      - "config.key3 == 3"
+
 - include_vars:
     file: no_auto_unsafe.yml
   register: baz