ansible.builtin.find (v2.5.10) — module

Install Ansible via pip

Install with pip install ansible==2.5.10

Description

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.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Recursively find /tmp files older than 2 days
  find:
    paths: /tmp
    age: 2d
    recurse: yes

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Find /var/log all directories, exclude nginx and mysql
  find:
    paths: /var/log
    recurse: no
    file_type: directory
    excludes: 'nginx,mysql'

Inputs

    
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").

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.

paths:
    aliases:
    - name
    - path
    description:
    - List of paths of directories to search. All paths must be fully qualified.
    required: true

follow:
    choices:
    - 'no'
    - 'yes'
    default: 'no'
    description:
    - Set this to true to follow symlinks in path for systems with python 2.6+.

hidden:
    choices:
    - 'no'
    - 'yes'
    default: 'no'
    description:
    - Set this to true to include hidden files, otherwise they'll be ignored.

recurse:
    choices:
    - 'no'
    - 'yes'
    default: 'no'
    description:
    - If target is a directory, recursively descend into the directory looking for files.

contains:
    description:
    - One or more regex patterns which should be matched against the file content.

excludes:
    aliases:
    - exclude
    default: null
    description:
    - One or more (shell or regex) patterns, which type is controlled by C(use_regex)
      option.
    - Excludes is a patterns should not be returned in list. Multiple patterns can be
      specified using a 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.

age_stamp:
    choices:
    - atime
    - ctime
    - mtime
    default: mtime
    description:
    - Choose the file property against which we compare age.

file_type:
    choices:
    - any
    - directory
    - file
    - link
    default: file
    description:
    - Type of file to select.
    - The 'link' and 'any' choices were added in version 2.3.

use_regex:
    choices:
    - 'no'
    - 'yes'
    default: 'no'
    description:
    - If false the patterns are file globs (shell) if true they are python regexes.

get_checksum:
    choices:
    - 'no'
    - 'yes'
    default: 'no'
    description:
    - Set this to true to retrieve a file's sha1 checksum.

Outputs

examined:
  description: number of filesystem objects looked at
  returned: success
  sample: 34
  type: string
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: string