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

@@ -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"]

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