community.general.filetree – recursively match all files in a directory tree

Note

This plugin is part of the community.general collection (version 3.8.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.filetree.

Synopsis

  • This lookup enables you to template a complete tree of files on a target system while retaining permissions and ownership.
  • Supports directories, files and symlinks, including SELinux and other file properties.
  • If you provide more than one path, it will implement a first_found logic, and will not process entries it already processed in previous paths. This enables merging different trees in order of importance, or add role_vars to specific paths to influence different instances of the same role.

Parameters

Parameter Choices/Defaults Configuration Comments
_terms
string / required
path(s) of files to read

Examples

- name: Create directories
  ansible.builtin.file:
    path: /web/{{ item.path }}
    state: directory
    mode: '{{ item.mode }}'
  with_community.general.filetree: web/
  when: item.state == 'directory'

- name: Template files (explicitly skip directories in order to use the 'src' attribute)
  ansible.builtin.template:
    src: '{{ item.src }}'
    # Your template files should be stored with a .j2 file extension,
    # but should not be deployed with it. splitext|first removes it.
    dest: /web/{{ item.path | splitext | first }}
    mode: '{{ item.mode }}'
  with_community.general.filetree: web/
  when: item.state == 'file'

- name: Recreate symlinks
  ansible.builtin.file:
    src: '{{ item.src }}'
    dest: /web/{{ item.path }}
    state: link
    follow: false  # avoid corrupting target files if the link already exists
    force: yes
    mode: '{{ item.mode }}'
  with_community.general.filetree: web/
  when: item.state == 'link'

- name: list all files under web/
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.filetree', 'web/') }}"

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key Returned Description
_raw
list / elements=dictionary
success
List of dictionaries with file information.

ctime
float
success
Time of last metadata update or creation (depends on OS).

gid
integer
success
Group ID of the file/directory.

group
any
success
Name of the group that owns the file/directory.

mode
string
success
The permissions the resulting file or directory.

mtime
float
success
Time of last modification.

owner
any
success
Name of the user that owns the file/directory.

path
path
success
Contains the relative path to root.

root
path
success
Allows filtering by original location.

selevel
any
success
The level part of the SELinux file context.

serole
any
success
The role part of the SELinux file context.

setype
any
success
The type part of the SELinux file context.

seuser
any
success
The user part of the SELinux file context.

size
integer
success
Size of the target.

src
path
success
Full path to file.
Not returned when item.state is set to directory.

state
string
success
TODO

uid
integer
success
Owner ID of the file/directory.



Authors

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/filetree_lookup.html