find – Return a list of files based on specific criteria
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 |
|
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 Default is unlimited depth. | |
excludes list added in 2.5 |
One or more (shell or regex) patterns, which type is controlled by Items whose basenames match an
| |
file_type string |
|
Type of file to select. The 'link' and 'any' choices were added in Ansible 2.3. |
follow boolean |
|
Set this to |
get_checksum boolean |
|
Set this to |
hidden boolean |
|
Set this to |
paths list / required |
List of paths of directories to search. All paths must be fully qualified.
| |
patterns list |
Default: "*" |
One or more (shell or regex) patterns, which type is controlled by 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.
|
recurse boolean |
|
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 |
|
If If |
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
- This module is guaranteed to have no backward incompatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]
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)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/find_module.html