W3cubDocs

/Ansible

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.

Options

parameter required default choices comments
age
 no
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
 no mtime
  • atime
  • ctime
  • mtime
Choose the file property against which we compare age.
contains
 no
One or more regex patterns which should be matched against the file content.
file_type
 no file
  • any
  • directory
  • file
  • link
Type of file to select.
The 'link' and 'any' choices were added in version 2.3.
follow
 no no
  • no
  • yes
Set this to true to follow symlinks in path for systems with python 2.6+.
get_checksum
 no no
  • no
  • yes
Set this to true to retrieve a file's sha1 checksum.
hidden
 no no
  • no
  • yes
Set this to true to include hidden files, otherwise they'll be ignored.
paths
 yes
List of paths of directories to search. All paths must be fully qualified.
aliases: name, path
patterns
 no *
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.
aliases: pattern
recurse
 no no
  • no
  • yes
If target is a directory, recursively descend into the directory looking for files.
size
 no
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
 no no
  • no
  • yes
If false the patterns are file globs (shell) if true they are python regexes.

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

Return Values

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

name description returned type sample
files
all matches found with the specified criteria (see stat module for full output of each dictionary)
 success list [{'path': '/var/tmp/test1', 'mode': '0644', '...': '...', 'checksum': '16fac7be61a6e4591a33ef4b729c5c3302307523'}, {'path': '/var/tmp/test2', '...': '...'}]
examined
number of filesystem objects looked at
 success string 34
matched
number of matches
 success string 14

Notes

Note

  • For Windows targets, use the win_find module instead.

Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Maintenance Info

For more information about Red Hat’s this support of this module, please refer to this knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2017 Michael DeHaan
© 2017 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/find_module.html