Try SpotterReturn a list of files based on specific criteria
| "added in version" 2.0 of ansible.builtin"
Authors: Brian Coca (@bcoca)
pipInstall with pip install ansible-core==2.16.5
Return a list of files based on specific criteria. Multiple criteria are AND'd together.
For Windows targets, use the M(ansible.windows.win_find) module instead.
This module does not use the C(find) command, it is a much simpler and slower Python implementation. It is intended for small and simple uses. Those that need the extra power or speed and have expertise with the UNIX command, should use it directly.
- name: Recursively find /tmp files older than 2 days
ansible.builtin.find:
paths: /tmp
age: 2d
recurse: yes
- name: Recursively find /tmp files older than 4 weeks and equal or greater than 1 megabyte
ansible.builtin.find:
paths: /tmp
age: 4w
size: 1m
recurse: yes
- name: Recursively find /var/tmp files with last access time greater than 3600 seconds
ansible.builtin.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
ansible.builtin.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
ansible.builtin.find:
paths: /var/log
patterns: "^.*?\\.(?:old|log\\.gz)$"
size: 10m
use_regex: yes
- name: Find /var/log all directories, exclude nginx and mysql
ansible.builtin.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
ansible.builtin.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
ansible.builtin.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
mode:
description:
- Choose objects matching a specified permission. This value is restricted to modes
that can be applied using the python C(os.chmod) function.
- The mode can be provided as an octal such as V("0644") or as symbolic such as V(u=rw,g=r,o=r)
type: raw
version_added: '2.16'
version_added_collection: ansible.builtin
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.
type: str
depth:
description:
- Set the maximum number of levels to descend into.
- Setting recurse to V(false) 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.
elements: str
required: true
type: list
follow:
default: false
description:
- Set this to V(true) to follow symlinks in path for systems with python 2.6+.
type: bool
hidden:
default: false
description:
- Set this to V(true) 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:
- A regular expression or pattern which should be matched against the file content.
- If O(read_whole_file) is V(false) it matches against the beginning of the line (uses
V(re.match(\))). If O(read_whole_file) is V(true), it searches anywhere for that
pattern (uses V(re.search(\))).
- Works only when O(file_type) is V(file).
type: str
excludes:
aliases:
- exclude
description:
- One or more (shell or regex) patterns, which type is controlled by O(use_regex)
option.
- Items whose basenames match an O(excludes) pattern are culled from O(patterns) matches.
Multiple patterns can be specified using a list.
elements: str
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 O(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.
- The pattern is matched against the file base name, excluding the directory.
- When using regexen, the pattern MUST match the ENTIRE file name, not just parts
of it. So if you are looking to match all files ending in .default, you'd need to
use C(.*\.default) as a regexp and not just C(\.default).
- 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.
- Defaults to V(*) when O(use_regex=False), or V(.*) when O(use_regex=True).
elements: str
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 V(false), the patterns are file globs (shell).
- If V(true), they are python regexes.
type: bool
exact_mode:
default: true
description:
- Restrict mode matching to exact matches only, and not as a minimum set of permissions
to match.
type: bool
version_added: '2.16'
version_added_collection: ansible.builtin
get_checksum:
default: false
description:
- Set this to V(true) to retrieve a file's SHA1 checksum.
type: bool
read_whole_file:
default: false
description:
- When doing a C(contains) search, determines whether the whole file should be read
into memory or if the regex should be applied to the file line-by-line.
- Setting this to C(true) can have performance and memory implications for large files.
- This uses V(re.search(\)) instead of V(re.match(\)).
type: bool
version_added: '2.11'
version_added_collection: ansible.builtin
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
skipped_paths:
description: skipped paths and reasons they were skipped
returned: success
sample:
/laskdfj: '''/laskdfj'' is not a directory'
type: dict
version_added: '2.12'
version_added_collection: ansible.builtin