community.general.filetree (8.5.0) — lookup

Install collection

Install with ansible-galaxy collection install community.general:==8.5.0

Add to requirements.yml

  collections:
    - name: community.general
      version: 8.5.0

Description

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.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Create directories
  ansible.builtin.file:
    path: /web/{{ item.path }}
    state: directory
    mode: '{{ item.mode }}'
  with_community.general.filetree: web/
  when: item.state == 'directory'

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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'

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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'

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: list all files under web/
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.filetree', 'web/') }}"

Inputs

    
_terms:
    description: path(s) of files to read
    required: true

Outputs

_raw:
  contains:
    ctime:
      description: Time of last metadata update or creation (depends on OS).
      type: float
    gid:
      description: Group ID of the file/directory.
      type: int
    group:
      description: Name of the group that owns the file/directory.
      type: raw
    mode:
      description: The permissions the resulting file or directory.
      type: str
    mtime:
      description: Time of last modification.
      type: float
    owner:
      description: Name of the user that owns the file/directory.
      type: raw
    path:
      description: Contains the relative path to root.
      type: path
    root:
      description: Allows filtering by original location.
      type: path
    selevel:
      description: The level part of the SELinux file context.
      type: raw
    serole:
      description: The role part of the SELinux file context.
      type: raw
    setype:
      description: The type part of the SELinux file context.
      type: raw
    seuser:
      description: The user part of the SELinux file context.
      type: raw
    size:
      description: Size of the target.
      type: int
    src:
      description:
      - Full path to file.
      - Not returned when RV(_raw[].state) is set to V(directory).
      type: path
    state:
      description: TODO
      type: str
    uid:
      description: Owner ID of the file/directory.
      type: int
  description: List of dictionaries with file information.
  elements: dict
  type: list