# filetree – recursively match all files in a directory tree

New in version 2.4.

- Synopsis

- Parameters

- Examples

- Return Values

- Status

## 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 - / required |  |  | path(s) of files to read

## Examples

    - name: Create directories
      file:
        path: /web/{{ item.path }}
        state: directory
        mode: '{{ item.mode }}'
      with_filetree: web/
      when: item.state == 'directory'

    - name: Template files (explicitly skip directories in order to use the 'src' attribute)
      template:
        src: '{{ item.src }}'
        dest: /web/{{ item.path }}
        mode: '{{ item.mode }}'
      with_filetree: web/
      when: item.state == 'file'

    - name: Recreate symlinks
      file:
        src: '{{ item.src }}'
        dest: /web/{{ item.path }}
        state: link
        force: yes
        mode: '{{ item.mode }}'
      with_filetree: web/
      when: item.state == 'link'

## Return Values

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

Key | Returned | Description
--- | --- | ---
_raw - |  | list of dictionaries with file information
| ctime - |  | TODO
| gid - |  | TODO
| group - |  | TODO
| mode - |  | TODO
| mtime - |  | TODO
| owner - |  | TODO
| path - |  | contains the relative path to root
| root - |  | allows filtering by original location
| selevel - |  | TODO
| serole - |  | TODO
| setype - |  | TODO
| seuser - |  | TODO
| size - |  | TODO
| src - |  | full path to file not returned when `item.state` is set to `directory`
| state - |  | TODO
| uid - |  | TODO

## Status

- This lookup is not guaranteed to have a backwards compatible interface. [preview]

- This lookup is maintained by the Ansible Community. [community]

### Authors

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

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

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.