Documentation

find - return a list of files based on specific criteria

New in version 2.0.

Synopsis

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

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
    • mtime
    • ctime
    Choose the file property against which we compare age. Default is mtime.
    contains
    		 no
      One or more re patterns which should be matched against the file content
      file_type
      		 no file
      • file
      • directory
      Type of file to select
      follow
      		 no False
      • True
      • False
      Set this to true to follow symlinks in path for systems with python 2.6+
      get_checksum
      		 no False
      • True
      • False
      Set this to true to retrieve a file's sha1 checksum
      hidden
      		 no False
      • True
      • False
      Set this to true to include hidden files, otherwise they'll be ignored.
      paths
      		 yes
        List of paths to the file or directory to search. All paths must be fully qualified.

        aliases: name, path
        patterns
        		 no *
          One or more (shell or regex) patterns, which type is controled 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
          • yes
          • no
          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 False
            • True
            • False
            If false the patterns are file globs (shell) if true they are python regexes

            Examples

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

# Recursively find /tmp files older than 4 weeks and equal or greater than 1 megabyte
- find: paths="/tmp" age="4w" size="1m" recurse=yes

# Recursively find /var/tmp files with last access time greater than 3600 seconds
- find: paths="/var/tmp" age="3600" age_stamp=atime recurse=yes

# find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz
- find: paths="/var/tmp" patterns="*.old,*.log.gz" size="10m"

# find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz via regex
- find: paths="/var/tmp" patterns="^.*?\.(?:old|log\.gz)$" size="10m" use_regex=True

            Return Values

            Common return values are documented here Common 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 of dictionaries [{'mode=0644': None, 'path="/var/tmp/test1"': None, '...': None, 'checksum=16fac7be61a6e4591a33ef4b729c5c3302307523': None}, {'...': None, 'path="/var/tmp/test2"': None}]
            examined number of filesystem objects looked at success string 34
            matched number of matches success string 14


            This is a Core Module

            For more information on what this means please read Core Modules

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