find – Return a list of files based on specific criteria

New in version 2.0.

Synopsis

  • Return a list of files based on specific criteria. Multiple criteria are AND’d together.

  • For Windows targets, use the win_find module instead.

Parameters

Parameter Choices/Defaults Comments
age
string
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").
age_stamp
string
    Choices:
  • atime
  • ctime
  • mtime ←
Choose the file property against which we compare age.
contains
string
One or more regex patterns which should be matched against the file content.
depth
integer
added in 2.6
Set the maximum number of levels to decend into.
Setting recurse to no will override this value, which is effectively depth 1.
Default is unlimited depth.
excludes
list
added in 2.5
One or more (shell or regex) patterns, which type is controlled by use_regex option.
Items whose basenames match an excludes pattern are culled from patterns matches. Multiple patterns can be specified using a list.

aliases: exclude
file_type
string
    Choices:
  • any
  • directory
  • file ←
  • link
Type of file to select.
The 'link' and 'any' choices were added in Ansible 2.3.
follow
boolean
    Choices:
  • no ←
  • yes
Set this to yes to follow symlinks in path for systems with python 2.6+.
get_checksum
boolean
    Choices:
  • no ←
  • yes
Set this to yes to retrieve a file's SHA1 checksum.
hidden
boolean
    Choices:
  • no ←
  • yes
Set this to yes to include hidden files, otherwise they will be ignored.
paths
list / required
List of paths of directories to search. All paths must be fully qualified.

aliases: name, path
patterns
list
Default:
"*"
One or more (shell or regex) patterns, which type is controlled by 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.

aliases: pattern
recurse
boolean
    Choices:
  • no ←
  • yes
If target is a directory, recursively descend into the directory looking for files.
size
-
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.
use_regex
boolean
    Choices:
  • no ←
  • yes
If no, the patterns are file globs (shell).
If yes, they are python regexes.

See Also

See also

win_find – Return a list of files based on specific criteria

The official documentation on the win_find module.

Examples

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

Return Values

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

Key Returned Description
examined
integer
 success
Number of filesystem objects looked at

Sample:
34
files
list
 success
All matches found with the specified criteria (see stat module for full output of each dictionary)

Sample:
[{'path': '/var/tmp/test1', 'mode': '0644', '...': '...', 'checksum': '16fac7be61a6e4591a33ef4b729c5c3302307523'}, {'path': '/var/tmp/test2', '...': '...'}]
matched
integer
 success
Number of matches

Sample:
14


Status

Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

Authors

  • Brian Coca (@bcoca)

Hint

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