Create section 'Merging lists of dictionaries' from the template in helper/lists_mergeby.

docs/docsite/helper/lists_mergeby/default-common.yml

@@ -0,0 +1,12 @@
+list1:
+  - name: foo
+    extra: true
+  - name: bar
+    extra: false
+  - name: meh
+    extra: true
+list2:
+  - name: foo
+    path: /foo
+  - name: baz
+    path: /baz

docs/docsite/helper/lists_mergeby/default-recursive-true.yml

@@ -0,0 +1,19 @@
+list1:
+  - name: myname01
+    param01:
+      x: default_value
+      y: default_value
+      list:
+        - default_value
+  - name: myname02
+    param01: [1, 1, 2, 3]
+
+list2:
+  - name: myname01
+    param01:
+      y: patch_value
+      z: patch_value
+      list:
+        - patch_value
+  - name: myname02
+    param01: [3, 4, 4, {key: value}]

docs/docsite/helper/lists_mergeby/example-001.yml

@@ -0,0 +1,10 @@
+---
+- name: 1. Merge two lists by common attribute 'name'
+  include_vars:
+    dir: example-001_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-001.out

docs/docsite/helper/lists_mergeby/example-001_vars/default-common.yml

@@ -0,0 +1 @@
+../default-common.yml

docs/docsite/helper/lists_mergeby/example-001_vars/list3.yml

@@ -0,0 +1,2 @@
+list3: "{{ list1|
+           community.general.lists_mergeby(list2, 'name') }}"

docs/docsite/helper/lists_mergeby/example-002.yml

@@ -0,0 +1,10 @@
+---
+- name: 2. Merge two lists by common attribute 'name'
+  include_vars:
+    dir: example-002_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-002.out

docs/docsite/helper/lists_mergeby/example-002_vars/default-common.yml

@@ -0,0 +1 @@
+../default-common.yml

docs/docsite/helper/lists_mergeby/example-002_vars/list3.yml

@@ -0,0 +1,2 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name') }}"

docs/docsite/helper/lists_mergeby/example-003.yml

@@ -0,0 +1,10 @@
+---
+- name: 3. Merge recursive by 'name', replace lists (default)
+  include_vars:
+    dir: example-003_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-003.out

docs/docsite/helper/lists_mergeby/example-003_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-003_vars/list3.yml

@@ -0,0 +1,3 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true) }}"

docs/docsite/helper/lists_mergeby/example-004.yml

@@ -0,0 +1,10 @@
+---
+- name: 4. Merge recursive by 'name', keep lists
+  include_vars:
+    dir: example-004_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-004.out

docs/docsite/helper/lists_mergeby/example-004_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-004_vars/list3.yml

@@ -0,0 +1,4 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true,
+                                           list_merge='keep') }}"

docs/docsite/helper/lists_mergeby/example-005.yml

@@ -0,0 +1,10 @@
+---
+- name: 5. Merge recursive by 'name', append lists
+  include_vars:
+    dir: example-005_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-005.out

docs/docsite/helper/lists_mergeby/example-005_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-005_vars/list3.yml

@@ -0,0 +1,4 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true,
+                                           list_merge='append') }}"

docs/docsite/helper/lists_mergeby/example-006.yml

@@ -0,0 +1,10 @@
+---
+- name: 6. Merge recursive by 'name', prepend lists
+  include_vars:
+    dir: example-006_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-006.out

docs/docsite/helper/lists_mergeby/example-006_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-006_vars/list3.yml

@@ -0,0 +1,4 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true,
+                                           list_merge='prepend') }}"

docs/docsite/helper/lists_mergeby/example-007.yml

@@ -0,0 +1,10 @@
+---
+- name: 7. Merge recursive by 'name', append lists 'remove present'
+  include_vars:
+    dir: example-007_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-007.out

docs/docsite/helper/lists_mergeby/example-007_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-007_vars/list3.yml

@@ -0,0 +1,4 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true,
+                                           list_merge='append_rp') }}"

docs/docsite/helper/lists_mergeby/example-008.yml

@@ -0,0 +1,10 @@
+---
+- name: 8. Merge recursive by 'name', prepend lists 'remove present'
+  include_vars:
+    dir: example-008_vars
+- debug:
+    var: list3
+  when: debug|d(false)|bool
+- template:
+    src: list3.out.j2
+    dest: example-008.out

docs/docsite/helper/lists_mergeby/example-008_vars/default-recursive-true.yml

@@ -0,0 +1 @@
+../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-008_vars/list3.yml

@@ -0,0 +1,4 @@
+list3: "{{ [list1, list2]|
+           community.general.lists_mergeby('name',
+                                           recursive=true,
+                                           list_merge='prepend_rp') }}"

docs/docsite/helper/lists_mergeby/examples.yml

@@ -1,37 +1,49 @@
 ---
 examples:
+  - label: 'In the example below the lists are merged by the attribute ``name``:'
+    file: example-001_vars/list3.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-001.out
+    lang: 'yaml'
+  - label: 'It is possible to use a list of lists as an input of the filter:'
+    file: example-002_vars/list3.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces the same result as in the previous example:'
+    file: example-002.out
+    lang: 'yaml'
   - label: 'Example ``list_merge=replace`` (default):'
-    file: example-003.yml
+    file: example-003_vars/list3.yml
     lang: 'yaml+jinja'
   - label: 'This produces:'
     file: example-003.out
     lang: 'yaml'
   - label: 'Example ``list_merge=keep``:'
-    file: example-004.yml
+    file: example-004_vars/list3.yml
     lang: 'yaml+jinja'
   - label: 'This produces:'
     file: example-004.out
     lang: 'yaml'
   - label: 'Example ``list_merge=append``:'
-    file: example-005.yml
+    file: example-005_vars/list3.yml
     lang: 'yaml+jinja'
   - label: 'This produces:'
     file: example-005.out
     lang: 'yaml'
   - label: 'Example ``list_merge=prepend``:'
-    file: example-006.yml
+    file: example-006_vars/list3.yml
     lang: 'yaml+jinja'
   - label: 'This produces:'
     file: example-006.out
     lang: 'yaml'
   - label: 'Example ``list_merge=append_rp``:'
-    file: example-007.yml
+    file: example-007_vars/list3.yml
     lang: 'yaml+jinja'
   - label: 'This produces:'
     file: example-007.out
     lang: 'yaml'
   - label: 'Example ``list_merge=prepend_rp``:'
-    file: example-008.yml
+    file: example-008_vars/list3.yml
     lang: 'yaml+jinja'
   - label: 'This produces:'
     file: example-008.out

docs/docsite/helper/lists_mergeby/examples_all.rst.j2

@@ -3,6 +3,6 @@
 
 .. code-block:: {{ i.lang }}
 
-  {{ lookup('file', source_path ~ i.file)|indent(2) }}
+  {{ lookup('file', i.file)|indent(2) }}
 
 {% endfor %}

docs/docsite/helper/lists_mergeby/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2

@@ -0,0 +1,57 @@
+Merging lists of dictionaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have two or more lists of dictionaries and want to combine them into a list of merged dictionaries, where the dictionaries are merged by an attribute, you can use the ``lists_mergeby`` filter.
+
+.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ref:`the documentation for the community.general.yaml callback plugin <ansible_collections.community.general.yaml_callback>`.
+
+Let us use the lists below in the following examples
+
+.. code-block:: yaml
+
+  {{ lookup('file', 'default-common.yml')|indent(2) }}
+
+{% for i in examples[0:2] %}
+{{ i.label }}
+
+.. code-block:: {{ i.lang }}
+
+  {{ lookup('file', i.file)|indent(2) }}
+
+{% endfor %}
+
+.. versionadded:: 2.0.0
+
+{% for i in examples[2:4] %}
+{{ i.label }}
+
+.. code-block:: {{ i.lang }}
+
+  {{ lookup('file', i.file)|indent(2) }}
+
+{% endfor %}
+
+The filter also accepts two optional parameters: ``recursive`` and ``list_merge``. These parameters are only supported when used with ansible-base 2.10 or ansible-core, but not with Ansible 2.9. This is available since community.general 4.4.0.
+
+**recursive**
+    Is a boolean, default to ``False``. Should the ``community.general.lists_mergeby`` recursively merge nested hashes. Note: It does not depend on the value of the ``hash_behaviour`` setting in ``ansible.cfg``.
+
+**list_merge**
+    Is a string, its possible values are ``replace`` (default), ``keep``, ``append``, ``prepend``, ``append_rp`` or ``prepend_rp``. It modifies the behaviour of ``community.general.lists_mergeby`` when the hashes to merge contain arrays/lists.
+
+The examples below set ``recursive=true`` and display the differences among all six options of ``list_merge``. Functionality of the parameters is exactly the same as in the filter ``combine``. See :ref:`Combining hashes/dictionaries <combine_filter>` to learn details about these options.
+
+Let us use the lists below in the following examples
+
+.. code-block:: yaml
+
+  {{ lookup('file', 'default-recursive-true.yml')|indent(2) }}
+
+{% for i in examples[4:16] %}
+{{ i.label }}
+
+.. code-block:: {{ i.lang }}
+
+  {{ lookup('file', i.file)|indent(2) }}
+
+{% endfor %}

docs/docsite/helper/lists_mergeby/list3.out.j2

@@ -0,0 +1,2 @@
+list3:
+  {{ list3|to_nice_yaml|indent(2) }}

docs/docsite/helper/lists_mergeby/playbook.yml

@@ -1,41 +1,49 @@
 ---
-# The following runs all examples:
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# 1) Run all examples and create example-XXX.out
+# shell> ansible-playbook playbook.yml -e examples=true
 #
-#    ANSIBLE_STDOUT_CALLBACK=community.general.yaml ansible-playbook playbook.yml -e examples=true
+# 2) Optionally, create examples_all.rst
+# shell> ansible-playbook playbook.yml -e examples_all=true
 #
-# You need to copy the YAML output of example-XXX.yml into example-XXX.out.
+# 3) Create other REST files. See the blocks below.
-#
+# shell> ansible-playbook playbook.yml -e merging_lists_of_dictionaries=true
-# The following generates examples.rst out of the .out files:
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-#
+# docs/docsite/helper/lists_mergeby/playbook.yml
-#    ansible-playbook playbook.yml -e template=true
+
 - hosts: localhost
   gather_facts: false
-  vars:
-    source_path: ../../rst/examples/lists_mergeby/
   tasks:
 
     - block:
-        - import_tasks: '{{ source_path }}example-001.yml'
+        - import_tasks: example-001.yml
           tags: t001
-        - import_tasks: '{{ source_path }}example-002.yml'
+        - import_tasks: example-002.yml
           tags: t002
-        - import_tasks: '{{ source_path }}example-003.yml'
+        - import_tasks: example-003.yml
           tags: t003
-        - import_tasks: '{{ source_path }}example-004.yml'
+        - import_tasks: example-004.yml
           tags: t004
-        - import_tasks: '{{ source_path }}example-005.yml'
+        - import_tasks: example-005.yml
           tags: t005
-        - import_tasks: '{{ source_path }}example-006.yml'
+        - import_tasks: example-006.yml
           tags: t006
-        - import_tasks: '{{ source_path }}example-007.yml'
+        - import_tasks: example-007.yml
           tags: t007
-        - import_tasks: '{{ source_path }}example-008.yml'
+        - import_tasks: example-008.yml
           tags: t008
       when: examples|d(false)|bool
 
     - block:
         - include_vars: examples.yml
         - template:
-            src: examples.rst.j2
+            src: examples_all.rst.j2
-            dest: examples.rst
+            dest: examples_all.rst
-      when: template|d(false)|bool
+      when: examples_all|d(false)|bool
+
+    - block:
+        - include_vars: examples.yml
+        - template:
+            src: filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2
+            dest: filter_guide_abstract_informations_merging_lists_of_dictionaries.rst
+      when: merging_lists_of_dictionaries|d(false)|bool

docs/docsite/rst/examples/lists_mergeby/example-001.out

@@ -1,10 +0,0 @@
-  list3:
-  - extra: false
-    name: bar
-  - name: baz
-    path: /baz
-  - extra: true
-    name: foo
-    path: /foo
-  - extra: true
-    name: meh

docs/docsite/rst/examples/lists_mergeby/example-001.yml

@@ -1,20 +0,0 @@
----
-- name: Merge two lists by common attribute 'name'
-  set_fact:
-    list3: "{{ list1|
-               community.general.lists_mergeby(list2, 'name') }}"
-  vars:
-    list1:
-      - name: foo
-        extra: true
-      - name: bar
-        extra: false
-      - name: meh
-        extra: true
-    list2:
-      - name: foo
-        path: /foo
-      - name: baz
-        path: /baz
-- debug:
-    var: list3

docs/docsite/rst/examples/lists_mergeby/example-002.out

@@ -1,10 +0,0 @@
-  list3:
-  - extra: false
-    name: bar
-  - name: baz
-    path: /baz
-  - extra: true
-    name: foo
-    path: /foo
-  - extra: true
-    name: meh

docs/docsite/rst/examples/lists_mergeby/example-002.yml

@@ -1,20 +0,0 @@
----
-- name: Merge two lists by common attribute 'name'
-  set_fact:
-    list3: "{{ [list1, list2]|
-               community.general.lists_mergeby('name') }}"
-  vars:
-    list1:
-      - name: foo
-        extra: true
-      - name: bar
-        extra: false
-      - name: meh
-        extra: true
-    list2:
-      - name: foo
-        path: /foo
-      - name: baz
-        path: /baz
-- debug:
-    var: list3

docs/docsite/rst/examples/lists_mergeby/example-003.out

@@ -1,14 +0,0 @@
-  list3:
-  - name: myname01
-    param01:
-      list:
-      - patch_value
-      x: default_value
-      y: patch_value
-      z: patch_value
-  - name: myname02
-    param01:
-    - 3
-    - 4
-    - 4
-    - key: value

docs/docsite/rst/examples/lists_mergeby/example-003.yml

@@ -1,28 +0,0 @@
----
-- name: Merge recursive by 'name', replace lists (default)
-  set_fact:
-    list3: "{{ [list1, list2]|
-               community.general.lists_mergeby('name',
-                                               recursive=true) }}"
-  vars:
-    list1:
-      - name: myname01
-        param01:
-          x: default_value
-          y: default_value
-          list:
-            - default_value
-      - name: myname02
-        param01: [1, 1, 2, 3]
-
-    list2:
-      - name: myname01
-        param01:
-          y: patch_value
-          z: patch_value
-          list:
-            - patch_value
-      - name: myname02
-        param01: [3, 4, 4, {key: value}]
-- debug:
-    var: list3

docs/docsite/rst/examples/lists_mergeby/example-004.out

@@ -1,14 +0,0 @@
-  list3:
-  - name: myname01
-    param01:
-      list:
-      - default_value
-      x: default_value
-      y: patch_value
-      z: patch_value
-  - name: myname02
-    param01:
-    - 1
-    - 1
-    - 2
-    - 3

docs/docsite/rst/examples/lists_mergeby/example-004.yml

@@ -1,29 +0,0 @@
----
-- name: Merge recursive by 'name', keep lists
-  set_fact:
-    list3: "{{ [list1, list2]|
-               community.general.lists_mergeby('name',
-                                               recursive=true,
-                                               list_merge='keep') }}"
-  vars:
-    list1:
-      - name: myname01
-        param01:
-          x: default_value
-          y: default_value
-          list:
-            - default_value
-      - name: myname02
-        param01: [1, 1, 2, 3]
-
-    list2:
-      - name: myname01
-        param01:
-          y: patch_value
-          z: patch_value
-          list:
-            - patch_value
-      - name: myname02
-        param01: [3, 4, 4, {key: value}]
-- debug:
-    var: list3

docs/docsite/rst/examples/lists_mergeby/example-005.out

@@ -1,19 +0,0 @@
-  list3:
-  - name: myname01
-    param01:
-      list:
-      - default_value
-      - patch_value
-      x: default_value
-      y: patch_value
-      z: patch_value
-  - name: myname02
-    param01:
-    - 1
-    - 1
-    - 2
-    - 3
-    - 3
-    - 4
-    - 4
-    - key: value

docs/docsite/rst/examples/lists_mergeby/example-005.yml

@@ -1,29 +0,0 @@
----
-- name: Merge recursive by 'name', append lists
-  set_fact:
-    list3: "{{ [list1, list2]|
-               community.general.lists_mergeby('name',
-                                               recursive=true,
-                                               list_merge='append') }}"
-  vars:
-    list1:
-      - name: myname01
-        param01:
-          x: default_value
-          y: default_value
-          list:
-            - default_value
-      - name: myname02
-        param01: [1, 1, 2, 3]
-
-    list2:
-      - name: myname01
-        param01:
-          y: patch_value
-          z: patch_value
-          list:
-            - patch_value
-      - name: myname02
-        param01: [3, 4, 4, {key: value}]
-- debug:
-    var: list3

docs/docsite/rst/examples/lists_mergeby/example-006.out

@@ -1,19 +0,0 @@
-  list3:
-  - name: myname01
-    param01:
-      list:
-      - patch_value
-      - default_value
-      x: default_value
-      y: patch_value
-      z: patch_value
-  - name: myname02
-    param01:
-    - 3
-    - 4
-    - 4
-    - key: value
-    - 1
-    - 1
-    - 2
-    - 3

docs/docsite/rst/examples/lists_mergeby/example-006.yml

@@ -1,29 +0,0 @@
----
-- name: Merge recursive by 'name', prepend lists
-  set_fact:
-    list3: "{{ [list1, list2]|
-               community.general.lists_mergeby('name',
-                                               recursive=true,
-                                               list_merge='prepend') }}"
-  vars:
-    list1:
-      - name: myname01
-        param01:
-          x: default_value
-          y: default_value
-          list:
-            - default_value
-      - name: myname02
-        param01: [1, 1, 2, 3]
-
-    list2:
-      - name: myname01
-        param01:
-          y: patch_value
-          z: patch_value
-          list:
-            - patch_value
-      - name: myname02
-        param01: [3, 4, 4, {key: value}]
-- debug:
-    var: list3

docs/docsite/rst/examples/lists_mergeby/example-007.out

@@ -1,18 +0,0 @@
-  list3:
-  - name: myname01
-    param01:
-      list:
-      - default_value
-      - patch_value
-      x: default_value
-      y: patch_value
-      z: patch_value
-  - name: myname02
-    param01:
-    - 1
-    - 1
-    - 2
-    - 3
-    - 4
-    - 4
-    - key: value

docs/docsite/rst/examples/lists_mergeby/example-007.yml

@@ -1,29 +0,0 @@
----
-- name: Merge recursive by 'name', append lists 'remove present'
-  set_fact:
-    list3: "{{ [list1, list2]|
-               community.general.lists_mergeby('name',
-                                               recursive=true,
-                                               list_merge='append_rp') }}"
-  vars:
-    list1:
-      - name: myname01
-        param01:
-          x: default_value
-          y: default_value
-          list:
-            - default_value
-      - name: myname02
-        param01: [1, 1, 2, 3]
-
-    list2:
-      - name: myname01
-        param01:
-          y: patch_value
-          z: patch_value
-          list:
-            - patch_value
-      - name: myname02
-        param01: [3, 4, 4, {key: value}]
-- debug:
-    var: list3

docs/docsite/rst/examples/lists_mergeby/example-008.out

@@ -1,18 +0,0 @@
-  list3:
-  - name: myname01
-    param01:
-      list:
-      - patch_value
-      - default_value
-      x: default_value
-      y: patch_value
-      z: patch_value
-  - name: myname02
-    param01:
-    - 3
-    - 4
-    - 4
-    - key: value
-    - 1
-    - 1
-    - 2

docs/docsite/rst/examples/lists_mergeby/example-008.yml

@@ -1,29 +0,0 @@
----
-- name: Merge recursive by 'name', prepend lists 'remove present'
-  set_fact:
-    list3: "{{ [list1, list2]|
-               community.general.lists_mergeby('name',
-                                               recursive=true,
-                                               list_merge='prepend_rp') }}"
-  vars:
-    list1:
-      - name: myname01
-        param01:
-          x: default_value
-          y: default_value
-          list:
-            - default_value
-      - name: myname02
-        param01: [1, 1, 2, 3]
-
-    list2:
-      - name: myname01
-        param01:
-          y: patch_value
-          z: patch_value
-          list:
-            - patch_value
-      - name: myname02
-        param01: [3, 4, 4, {key: value}]
-- debug:
-    var: list3

docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst

@@ -5,45 +5,45 @@ If you have two or more lists of dictionaries and want to combine them into a li
 
 .. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ref:`the documentation for the community.general.yaml callback plugin <ansible_collections.community.general.yaml_callback>`.
 
+Let us use the lists below in the following examples
+
+.. code-block:: yaml
+
+  list1:
+    - name: foo
+      extra: true
+    - name: bar
+      extra: false
+    - name: meh
+      extra: true
+  list2:
+    - name: foo
+      path: /foo
+    - name: baz
+      path: /baz
+
 In the example below the lists are merged by the attribute ``name``:
 
 .. code-block:: yaml+jinja
 
-  ---
+  list3: "{{ list1|
-  - name: Merge two lists by common attribute 'name'
+             community.general.lists_mergeby(list2, 'name') }}"
-    set_fact:
-      list3: "{{ list1|
-                 community.general.lists_mergeby(list2, 'name') }}"
-    vars:
-      list1:
-        - name: foo
-          extra: true
-        - name: bar
-          extra: false
-        - name: meh
-          extra: true
-      list2:
-        - name: foo
-          path: /foo
-        - name: baz
-          path: /baz
-  - debug:
-      var: list3
 
 This produces:
 
 .. code-block:: yaml
 
   list3:
-  - extra: false
+    -   extra: false
-    name: bar
+        name: bar
-  - name: baz
+    -   name: baz
-    path: /baz
+        path: /baz
-  - extra: true
+    -   extra: true
-    name: foo
+        name: foo
-    path: /foo
+        path: /foo
-  - extra: true
+    -   extra: true
-    name: meh
+        name: meh
+
 
 .. versionadded:: 2.0.0
 
@@ -51,41 +51,24 @@ It is possible to use a list of lists as an input of the filter:
 
 .. code-block:: yaml+jinja
 
-  ---
+  list3: "{{ [list1, list2]|
-  - name: Merge two lists by common attribute 'name'
+             community.general.lists_mergeby('name') }}"
-    set_fact:
-      list3: "{{ [list1, list2]|
-                 community.general.lists_mergeby('name') }}"
-    vars:
-      list1:
-        - name: foo
-          extra: true
-        - name: bar
-          extra: false
-        - name: meh
-          extra: true
-      list2:
-        - name: foo
-          path: /foo
-        - name: baz
-          path: /baz
-  - debug:
-      var: list3
 
 This produces the same result as in the previous example:
 
 .. code-block:: yaml
 
   list3:
-  - extra: false
+    -   extra: false
-    name: bar
+        name: bar
-  - name: baz
+    -   name: baz
-    path: /baz
+        path: /baz
-  - extra: true
+    -   extra: true
-    name: foo
+        name: foo
-    path: /foo
+        path: /foo
-  - extra: true
+    -   extra: true
-    name: meh
+        name: meh
+
 
 The filter also accepts two optional parameters: ``recursive`` and ``list_merge``. These parameters are only supported when used with ansible-base 2.10 or ansible-core, but not with Ansible 2.9. This is available since community.general 4.4.0.
 
@@ -97,337 +80,212 @@ The filter also accepts two optional parameters: ``recursive`` and ``list_merge`
 
 The examples below set ``recursive=true`` and display the differences among all six options of ``list_merge``. Functionality of the parameters is exactly the same as in the filter ``combine``. See :ref:`Combining hashes/dictionaries <combine_filter>` to learn details about these options.
 
+Let us use the lists below in the following examples
+
+.. code-block:: yaml
+
+  list1:
+    - name: myname01
+      param01:
+        x: default_value
+        y: default_value
+        list:
+          - default_value
+    - name: myname02
+      param01: [1, 1, 2, 3]
+
+  list2:
+    - name: myname01
+      param01:
+        y: patch_value
+        z: patch_value
+        list:
+          - patch_value
+    - name: myname02
+      param01: [3, 4, 4, {key: value}]
+
 Example ``list_merge=replace`` (default):
 
 .. code-block:: yaml+jinja
 
-  ---
+  list3: "{{ [list1, list2]|
-  - name: Merge recursive by 'name', replace lists (default)
+             community.general.lists_mergeby('name',
-    set_fact:
+                                             recursive=true) }}"
-      list3: "{{ [list1, list2]|
-                 community.general.lists_mergeby('name',
-                                                 recursive=true) }}"
-    vars:
-      list1:
-        - name: myname01
-          param01:
-            x: default_value
-            y: default_value
-            list:
-              - default_value
-        - name: myname02
-          param01: [1, 1, 2, 3]
-
-      list2:
-        - name: myname01
-          param01:
-            y: patch_value
-            z: patch_value
-            list:
-              - patch_value
-        - name: myname02
-          param01: [3, 4, 4, {key: value}]
-  - debug:
-      var: list3
 
 This produces:
 
 .. code-block:: yaml
 
-    list3:
+  list3:
-    - name: myname01
+    -   name: myname01
-      param01:
+        param01:
-        list:
+            list:
-        - patch_value
+            - patch_value
-        x: default_value
+            x: default_value
-        y: patch_value
+            y: patch_value
-        z: patch_value
+            z: patch_value
-    - name: myname02
+    -   name: myname02
-      param01:
+        param01:
-      - 3
+        - 3
-      - 4
+        - 4
-      - 4
+        - 4
-      - key: value
+        -   key: value
 
 Example ``list_merge=keep``:
 
 .. code-block:: yaml+jinja
 
-  ---
+  list3: "{{ [list1, list2]|
-  - name: Merge recursive by 'name', keep lists
+             community.general.lists_mergeby('name',
-    set_fact:
+                                             recursive=true,
-      list3: "{{ [list1, list2]|
+                                             list_merge='keep') }}"
-                 community.general.lists_mergeby('name',
-                                                 recursive=true,
-                                                 list_merge='keep') }}"
-    vars:
-      list1:
-        - name: myname01
-          param01:
-            x: default_value
-            y: default_value
-            list:
-              - default_value
-        - name: myname02
-          param01: [1, 1, 2, 3]
-
-      list2:
-        - name: myname01
-          param01:
-            y: patch_value
-            z: patch_value
-            list:
-              - patch_value
-        - name: myname02
-          param01: [3, 4, 4, {key: value}]
-  - debug:
-      var: list3
 
 This produces:
 
 .. code-block:: yaml
 
-    list3:
+  list3:
-    - name: myname01
+    -   name: myname01
-      param01:
+        param01:
-        list:
+            list:
-        - default_value
+            - default_value
-        x: default_value
+            x: default_value
-        y: patch_value
+            y: patch_value
-        z: patch_value
+            z: patch_value
-    - name: myname02
+    -   name: myname02
-      param01:
+        param01:
-      - 1
+        - 1
-      - 1
+        - 1
-      - 2
+        - 2
-      - 3
+        - 3
 
 Example ``list_merge=append``:
 
 .. code-block:: yaml+jinja
 
-  ---
+  list3: "{{ [list1, list2]|
-  - name: Merge recursive by 'name', append lists
+             community.general.lists_mergeby('name',
-    set_fact:
+                                             recursive=true,
-      list3: "{{ [list1, list2]|
+                                             list_merge='append') }}"
-                 community.general.lists_mergeby('name',
-                                                 recursive=true,
-                                                 list_merge='append') }}"
-    vars:
-      list1:
-        - name: myname01
-          param01:
-            x: default_value
-            y: default_value
-            list:
-              - default_value
-        - name: myname02
-          param01: [1, 1, 2, 3]
-
-      list2:
-        - name: myname01
-          param01:
-            y: patch_value
-            z: patch_value
-            list:
-              - patch_value
-        - name: myname02
-          param01: [3, 4, 4, {key: value}]
-  - debug:
-      var: list3
 
 This produces:
 
 .. code-block:: yaml
 
-    list3:
+  list3:
-    - name: myname01
+    -   name: myname01
-      param01:
+        param01:
-        list:
+            list:
-        - default_value
+            - default_value
-        - patch_value
+            - patch_value
-        x: default_value
+            x: default_value
-        y: patch_value
+            y: patch_value
-        z: patch_value
+            z: patch_value
-    - name: myname02
+    -   name: myname02
-      param01:
+        param01:
-      - 1
+        - 1
-      - 1
+        - 1
-      - 2
+        - 2
-      - 3
+        - 3
-      - 3
+        - 3
-      - 4
+        - 4
-      - 4
+        - 4
-      - key: value
+        -   key: value
 
 Example ``list_merge=prepend``:
 
 .. code-block:: yaml+jinja
 
-  ---
+  list3: "{{ [list1, list2]|
-  - name: Merge recursive by 'name', prepend lists
+             community.general.lists_mergeby('name',
-    set_fact:
+                                             recursive=true,
-      list3: "{{ [list1, list2]|
+                                             list_merge='prepend') }}"
-                 community.general.lists_mergeby('name',
-                                                 recursive=true,
-                                                 list_merge='prepend') }}"
-    vars:
-      list1:
-        - name: myname01
-          param01:
-            x: default_value
-            y: default_value
-            list:
-              - default_value
-        - name: myname02
-          param01: [1, 1, 2, 3]
-
-      list2:
-        - name: myname01
-          param01:
-            y: patch_value
-            z: patch_value
-            list:
-              - patch_value
-        - name: myname02
-          param01: [3, 4, 4, {key: value}]
-  - debug:
-      var: list3
 
 This produces:
 
 .. code-block:: yaml
 
-    list3:
+  list3:
-    - name: myname01
+    -   name: myname01
-      param01:
+        param01:
-        list:
+            list:
-        - patch_value
+            - patch_value
-        - default_value
+            - default_value
-        x: default_value
+            x: default_value
-        y: patch_value
+            y: patch_value
-        z: patch_value
+            z: patch_value
-    - name: myname02
+    -   name: myname02
-      param01:
+        param01:
-      - 3
+        - 3
-      - 4
+        - 4
-      - 4
+        - 4
-      - key: value
+        -   key: value
-      - 1
+        - 1
-      - 1
+        - 1
-      - 2
+        - 2
-      - 3
+        - 3
 
 Example ``list_merge=append_rp``:
 
 .. code-block:: yaml+jinja
 
-  ---
+  list3: "{{ [list1, list2]|
-  - name: Merge recursive by 'name', append lists 'remove present'
+             community.general.lists_mergeby('name',
-    set_fact:
+                                             recursive=true,
-      list3: "{{ [list1, list2]|
+                                             list_merge='append_rp') }}"
-                 community.general.lists_mergeby('name',
-                                                 recursive=true,
-                                                 list_merge='append_rp') }}"
-    vars:
-      list1:
-        - name: myname01
-          param01:
-            x: default_value
-            y: default_value
-            list:
-              - default_value
-        - name: myname02
-          param01: [1, 1, 2, 3]
-
-      list2:
-        - name: myname01
-          param01:
-            y: patch_value
-            z: patch_value
-            list:
-              - patch_value
-        - name: myname02
-          param01: [3, 4, 4, {key: value}]
-  - debug:
-      var: list3
 
 This produces:
 
 .. code-block:: yaml
 
-    list3:
+  list3:
-    - name: myname01
+    -   name: myname01
-      param01:
+        param01:
-        list:
+            list:
-        - default_value
+            - default_value
-        - patch_value
+            - patch_value
-        x: default_value
+            x: default_value
-        y: patch_value
+            y: patch_value
-        z: patch_value
+            z: patch_value
-    - name: myname02
+    -   name: myname02
-      param01:
+        param01:
-      - 1
+        - 1
-      - 1
+        - 1
-      - 2
+        - 2
-      - 3
+        - 3
-      - 4
+        - 4
-      - 4
+        - 4
-      - key: value
+        -   key: value
 
 Example ``list_merge=prepend_rp``:
 
 .. code-block:: yaml+jinja
 
-  ---
+  list3: "{{ [list1, list2]|
-  - name: Merge recursive by 'name', prepend lists 'remove present'
+             community.general.lists_mergeby('name',
-    set_fact:
+                                             recursive=true,
-      list3: "{{ [list1, list2]|
+                                             list_merge='prepend_rp') }}"
-                 community.general.lists_mergeby('name',
-                                                 recursive=true,
-                                                 list_merge='prepend_rp') }}"
-    vars:
-      list1:
-        - name: myname01
-          param01:
-            x: default_value
-            y: default_value
-            list:
-              - default_value
-        - name: myname02
-          param01: [1, 1, 2, 3]
-
-      list2:
-        - name: myname01
-          param01:
-            y: patch_value
-            z: patch_value
-            list:
-              - patch_value
-        - name: myname02
-          param01: [3, 4, 4, {key: value}]
-  - debug:
-      var: list3
 
 This produces:
 
 .. code-block:: yaml
 
-    list3:
+  list3:
-    - name: myname01
+    -   name: myname01
-      param01:
+        param01:
-        list:
+            list:
-        - patch_value
+            - patch_value
-        - default_value
+            - default_value
-        x: default_value
+            x: default_value
-        y: patch_value
+            y: patch_value
-        z: patch_value
+            z: patch_value
-    - name: myname02
+    -   name: myname02
-      param01:
+        param01:
-      - 3
+        - 3
-      - 4
+        - 4
-      - 4
+        - 4
-      - key: value
+        -   key: value
-      - 1
+        - 1
-      - 1
+        - 1
-      - 2
+        - 2
+