Documentation

win_find - return a list of files based on specific criteria

New in version 2.3.

Synopsis

  • Return a list of files based on specified criteria.
  • Multiple criteria are AND’d together.
  • For non-Windows targets, use the find module instead.

Options

parameter required default choices comments
age
no
Select files or folders 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 an of those words (e.g., "2s", "10d", 1w").
age_stamp
no mtime
  • atime
  • mtime
  • ctime
Choose the file property against which we compare age. The default attribute we compare with is the last modification time.
checksum_algorithm
no sha1
  • md5
  • sha1
  • sha256
  • sha384
  • sha512
Algorithm to determine the checksum of a file. Will throw an error if the host is unable to use specified algorithm.
file_type
no file
  • file
  • directory
Type of file to search for
follow
no
  • true
  • false
Set this to true to follow symlinks in the path. This needs to be used in conjunction with recurse.
get_checksum
no True
  • true
  • false
Whether to return a checksum of the file in the return info (default sha1), use checksum_algorithm to change from the default.
hidden
no
  • true
  • false
Set this to include hidden files or folders
paths
yes
List of paths of directories to search for files or folders in. This can be supplied as a single path or a list of paths.
patterns
no
One or more (powershell or regex) patterns to compare filenames with. The type of pattern matching is controlled by use_regex option. The patterns retrict the list of files or folders to be returned based on the filenames. For a file to be matched it only has to match with one pattern in a list provided.
recurse
no
  • true
  • false
Will recursively descend into the directory looking for files or folders
size
no
Select files or folders whose size is equal to or greater than the specified size. Use a negative value to find files equal to or less than the specified size. You can specify the size with a suffix of the byte type i.e. kilo = k, mega = m... Size is not evaluated for symbolic links.
use_regex
no
  • true
  • false
Will set patterns to run as a regex check if true

Examples

# Find files in path
- win_find:
    paths: D:\temp

# Find hidden files in path
- win_find:
    paths: D:\temp
    hidden: True

# Find files in multiple paths
- win_find:
    paths: ['C:\temp', 'D:\temp']

# Find files in directory while searching recursively
- win_find:
    paths: D:\temp
    recurse: True

# Find files in directory while following symlinks
- win_find:
    paths: D:\temp
    recurse: True
    follow: True

# Find files with .log and .out extension using powershell wildcards
- win_find:
    paths: D:\temp
    patterns: ['*.log', '*.out']

# Find files in path based on regex pattern
- win_find:
    paths: D:\temp
    patterns: 'out_\d{8}-\d{6}.log'

# Find files older than 1 day
- win_find:
    paths: D:\temp
    age: 86400

# Find files older than 1 day based on create time
- win_find:
    paths: D:\temp
    age: 86400
    age_stamp: ctime

# Find files older than 1 day with unit syntax
- win_find:
    paths: D:\temp
    age: 1d

# Find files newer than 1 hour
- win_find:
    paths: D:\temp
    age: -3600

# Find files newer than 1 hour with unit syntax
- win_find:
    paths: D:\temp
    age: -1h

# Find files larger than 1MB
- win_find:
    paths: D:\temp
    size: 1048576

# Find files larger than 1GB with unit syntax
- win_find:
    paths: D:\temp
    size: 1g

# Find files smaller than 1MB
- win_find:
    paths: D:\temp
    size: -1048576

# Find files smaller than 1GB with unit syntax
- win_find:
    paths: D:\temp
    size: -1g

# Find folders/symlinks in multiple paths
- win_find:
    paths: ['C:\temp', 'D:\temp']
    file_type: directory

# Find files and return SHA256 checksum of files found
- win_find:
    paths: C:\temp
    get_checksum: True
    checksum_algorithm: sha256

# Find files and do not return the checksum
- win_find:
    path: C:\temp
    get_checksum: False

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
Information on the files/folders that match the criteria returned as a list of dictionary elements for each file matched
success complex
contains:
name description returned type sample
lastwritetime
the last modification time of the file represented in seconds since epoch
success, path exists float 1477984205.15
creationtime
the create time of the file represented in seconds since epoch
success, path exists float 1477984205.15
lastaccesstime
the last access time of the file represented in seconds since epoch
success, path exists float 1477984205.15
owner
the owner of the file
success, path exists string BUILTIN\Administrators
path
the full absolute path to the file
success, path exists string BUILTIN\Administrators
isarchive
if the path is ready for archiving or not
success, path exists boolean True
ishidden
if the path is hidden or not
success, path exists boolean True
lnk_source
the target of the symbolic link, will return null if not a link or the link is broken
string C:\temp
size
the size in bytes of a file or folder
success, path exists, path is not a link int 1024
isdir
if the path is a directory or not
success, path exists boolean True
extension
the extension of the file at path
success, path exists, path is a file string .ps1
isreadonly
if the path is read only or not
success, path exists boolean True
sharename
the name of share if folder is shared
success, path exists, path is a directory and isshared == True string file-share
checksum
The checksum of a file based on checksum_algorithm specified
success, path exists, path is a file, get_checksum == True string 09cb79e8fc7453c84a07f644e441fd81623b7f98
islnk
if the path is a symbolic link or junction or not
success, path exists boolean True
attributes
attributes of the file at path in raw form
success, path exists string Archive, Hidden
isshared
if the path is shared or not
success, path exists boolean True
changed
Whether anything was chagned
always boolean True
examined
The number of files/folders that was checked
always int 10
matched
The number of files/folders that match the criteria
always int 2


Notes

Note

  • For non-Windows targets, use the find module instead.

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

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