community.internal_test_tools.files_collect module – Collect state of files and directories on disk

Note

This module is part of the community.internal_test_tools collection (version 0.12.0).

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.internal_test_tools.

To use it in a playbook, specify: community.internal_test_tools.files_collect.

New in community.internal_test_tools 0.3.0

Synopsis

  • This module collects the state (timestamps, attributes, content) of files and directories on disk and returns them. Use together with community.internal_test_tools.files_diff to verify later on whether something changed, and if yes, what exactly changed.

Parameters

Parameter

Comments

directories

list / elements=dictionary

List of directories to check.

check_content

boolean

Whether to store the content of the files, or only a checksum.

Storing the content allows to show a diff.

Choices:

  • false ← (default)

  • true

path

path / required

Path to the directory.

recursive

boolean

Whether to consider subdirectories as well.

Choices:

  • false

  • true ← (default)

files

list / elements=dictionary

List of filenames to check.

allow_not_existing

boolean

Whether to accept if the file does not exist (and mark it as a non-existing file in the output).

Choices:

  • false ← (default)

  • true

check_content

boolean

Whether to store the content of the file, or only a checksum.

Storing the content allows to show a diff.

Choices:

  • false ← (default)

  • true

path

path / required

Path to the directory.

Notes

Note

  • Supports check_mode. The module never modifies anything, so check mode behavior is identical to regular behavior.

Examples

- name: Recursively collect information on all files in output_dir
  community.internal_test_tools.files_collect:
    directories:
      - path: "{{ output_dir }}"
  register: state

# ... some tasks in between ...

- name: Verify whether any file changed in output_dir
  community.internal_test_tools.files_diff:
    state: "{{ state }}"

Return Values

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

Key

Description

state

dictionary

The state of all files and directories.

Use the community.internal_test_tools.files_diff module to validate against the original files.

The structure of every field in this dictionary not explicitly documented here might change at any point, or might vanish altogether without further notice. Do not rely on undocumented data!

Returned: success

Authors

  • Felix Fontein (@felixfontein)