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.5.0).
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.
Terms
Parameter |
Comments |
---|---|
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 |
---|---|
List of dictionaries with file information. Returned: success |
|
Time of last metadata update or creation (depends on OS). Returned: success |
|
Group ID of the file/directory. Returned: success |
|
Name of the group that owns the file/directory. Returned: success |
|
The permissions the resulting file or directory. Returned: success |
|
Time of last modification. Returned: success |
|
Name of the user that owns the file/directory. Returned: success |
|
Contains the relative path to root. Returned: success |
|
Allows filtering by original location. Returned: success |
|
The level part of the SELinux file context. Returned: success |
|
The role part of the SELinux file context. Returned: success |
|
The type part of the SELinux file context. Returned: success |
|
The user part of the SELinux file context. Returned: success |
|
Size of the target. Returned: success |
|
TODO Returned: success |
|
Owner ID of the file/directory. Returned: success |