Try SpotterReturn a list of files based on specific criteria
| "added in version" 2.0 of ansible.builtin"
Authors: Brian Coca (@bcoca)
stableinterface | supported by core
pipInstall with pip install ansible==2.8.13
Return a list of files based on specific criteria. Multiple criteria are AND'd together.
For Windows targets, use the M(win_find) module instead.
- name: Recursively find /tmp files older than 2 days
find:
paths: /tmp
age: 2d
recurse: yes
- name: Recursively find /tmp files older than 4 weeks and equal or greater than 1 megabyte
find:
paths: /tmp
age: 4w
size: 1m
recurse: yes
- name: Recursively find /var/tmp files with last access time greater than 3600 seconds
find:
paths: /var/tmp
age: 3600
age_stamp: atime
recurse: yes
- name: Find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz
find:
paths: /var/log
patterns: '*.old,*.log.gz'
size: 10m
# Note that YAML double quotes require escaping backslashes but yaml single quotes do not.
- name: Find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz via regex
find:
paths: /var/log
patterns: "^.*?\\.(?:old|log\\.gz)$"
size: 10m
use_regex: yes
- name: Find /var/log all directories, exclude nginx and mysql
find:
paths: /var/log
recurse: no
file_type: directory
excludes: 'nginx,mysql'
# When using patterns that contain a comma, make sure they are formatted as lists to avoid splitting the pattern
- name: Use a single pattern that contains a comma formatted as a list
find:
paths: /var/log
file_type: file
use_regex: yes
patterns: ['^_[0-9]{2,4}_.*.log$']
- name: Use multiple patterns that contain a comma formatted as a YAML list
find:
paths: /var/log
file_type: file
use_regex: yes
patterns:
- '^_[0-9]{2,4}_.*.log$'
- '^[a-z]{1,5}_.*log$'
age:
description:
- Select files whose age is equal to or greater than the specified time.
- Use a negative age to find files equal to or less than the specified time.
- You can choose seconds, minutes, hours, days, or weeks by specifying the first letter
of any of those words (e.g., "1w").
type: str
size:
description:
- Select files whose size is equal to or greater than the specified size.
- Use a negative size to find files equal to or less than the specified size.
- Unqualified values are in bytes but b, k, m, g, and t can be appended to specify
bytes, kilobytes, megabytes, gigabytes, and terabytes, respectively.
- Size is not evaluated for directories.
depth:
description:
- Set the maximum number of levels to decend into.
- Setting recurse to C(no) will override this value, which is effectively depth 1.
- Default is unlimited depth.
type: int
version_added: '2.6'
version_added_collection: ansible.builtin
paths:
aliases:
- name
- path
description:
- List of paths of directories to search. All paths must be fully qualified.
required: true
type: list
follow:
default: false
description:
- Set this to C(yes) to follow symlinks in path for systems with python 2.6+.
type: bool
hidden:
default: false
description:
- Set this to C(yes) to include hidden files, otherwise they will be ignored.
type: bool
recurse:
default: false
description:
- If target is a directory, recursively descend into the directory looking for files.
type: bool
contains:
description:
- One or more regex patterns which should be matched against the file content.
type: str
excludes:
aliases:
- exclude
description:
- One or more (shell or regex) patterns, which type is controlled by C(use_regex)
option.
- Items whose basenames match an C(excludes) pattern are culled from C(patterns) matches.
Multiple patterns can be specified using a list.
type: list
version_added: '2.5'
version_added_collection: ansible.builtin
patterns:
aliases:
- pattern
default: '*'
description:
- One or more (shell or regex) patterns, which type is controlled by C(use_regex)
option.
- The patterns restrict the list of files to be returned to those whose basenames
match at least one of the patterns specified. Multiple patterns can be specified
using a list.
- This parameter expects a list, which can be either comma separated or YAML. If any
of the patterns contain a comma, make sure to put them in a list to avoid splitting
the patterns in undesirable ways.
type: list
age_stamp:
choices:
- atime
- ctime
- mtime
default: mtime
description:
- Choose the file property against which we compare age.
type: str
file_type:
choices:
- any
- directory
- file
- link
default: file
description:
- Type of file to select.
- The 'link' and 'any' choices were added in Ansible 2.3.
type: str
use_regex:
default: false
description:
- If C(no), the patterns are file globs (shell).
- If C(yes), they are python regexes.
type: bool
get_checksum:
default: false
description:
- Set this to C(yes) to retrieve a file's SHA1 checksum.
type: bool
examined:
description: Number of filesystem objects looked at
returned: success
sample: 34
type: int
files:
description: All matches found with the specified criteria (see stat module for
full output of each dictionary)
returned: success
sample:
- '...': '...'
checksum: 16fac7be61a6e4591a33ef4b729c5c3302307523
mode: '0644'
path: /var/tmp/test1
- '...': '...'
path: /var/tmp/test2
type: list
matched:
description: Number of matches
returned: success
sample: 14
type: int