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

Note

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

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.

Terms

Parameter

Comments

Terms

list / elements=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: true
    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 Value

Key

Description

Return value

list / elements=dictionary

List of dictionaries with file information.

Returned: success

ctime

float

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

Returned: success

gid

integer

Group ID of the file/directory.

Returned: success

group

any

Name of the group that owns the file/directory.

Returned: success

mode

string

The permissions the resulting file or directory.

Returned: success

mtime

float

Time of last modification.

Returned: success

owner

any

Name of the user that owns the file/directory.

Returned: success

path

path

Contains the relative path to root.

Returned: success

root

path

Allows filtering by original location.

Returned: success

selevel

any

The level part of the SELinux file context.

Returned: success

serole

any

The role part of the SELinux file context.

Returned: success

setype

any

The type part of the SELinux file context.

Returned: success

seuser

any

The user part of the SELinux file context.

Returned: success

size

integer

Size of the target.

Returned: success

src

path

Full path to file.

Not returned when _raw[].state is set to directory.

Returned: success

state

string

TODO

Returned: success

uid

integer

Owner ID of the file/directory.

Returned: success

Authors

  • Dag Wieers (@dagwieers)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.