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

Dag Wieers (@dagwieers) <dag@wieers.com>

© 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

Docs

Docs4dev

Title here