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

Note

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

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

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

Description

_raw

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 item.state is set to directory.

Returned: success

state

string

TODO

Returned: success

uid

integer

Owner ID of the file/directory.

Returned: success

Authors