Try Spotterreturn a list of files based on specific criteria
| "added in version" 2.3 of ansible.builtin"
Authors: Jordan Borean (@jborean93)
preview | supported by community
pipInstall with pip install ansible==2.3.2.0.post1
Return a list of files based on specified criteria.
Multiple criteria are AND'd together.
# 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
age:
description:
- 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").
required: false
size:
default: false
description:
- 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.
required: false
paths:
description:
- 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.
required: true
follow:
choices:
- 'true'
- 'false'
default: false
description:
- Set this to true to follow symlinks in the path. This needs to be used in conjunction
with C(recurse).
required: false
hidden:
choices:
- 'true'
- 'false'
default: false
description: Set this to include hidden files or folders
required: false
recurse:
choices:
- 'true'
- 'false'
default: false
description:
- Will recursively descend into the directory looking for files or folders
required: false
patterns:
description:
- One or more (powershell or regex) patterns to compare filenames with. The type of
pattern matching is controlled by C(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.
required: false
age_stamp:
choices:
- atime
- mtime
- ctime
default: mtime
description:
- Choose the file property against which we compare C(age). The default attribute
we compare with is the last modification time.
required: false
file_type:
choices:
- file
- directory
default: file
description: Type of file to search for
required: false
use_regex:
choices:
- 'true'
- 'false'
default: false
description:
- Will set patterns to run as a regex check if true
required: false
get_checksum:
choices:
- 'true'
- 'false'
default: true
description:
- Whether to return a checksum of the file in the return info (default sha1), use
C(checksum_algorithm) to change from the default.
required: false
checksum_algorithm:
choices:
- md5
- sha1
- sha256
- sha384
- sha512
default: sha1
description:
- Algorithm to determine the checksum of a file. Will throw an error if the host is
unable to use specified algorithm.
required: false
changed:
description: Whether anything was chagned
returned: always
sample: true
type: boolean
examined:
description: The number of files/folders that was checked
returned: always
sample: 10
type: int
files:
contains:
attributes:
description: attributes of the file at path in raw form
returned: success, path exists
sample: Archive, Hidden
type: string
checksum:
description: The checksum of a file based on checksum_algorithm specified
returned: success, path exists, path is a file, get_checksum == True
sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98
type: string
creationtime:
description: the create time of the file represented in seconds since epoch
returned: success, path exists
sample: 1477984205.15
type: float
extension:
description: the extension of the file at path
returned: success, path exists, path is a file
sample: .ps1
type: string
isarchive:
description: if the path is ready for archiving or not
returned: success, path exists
sample: true
type: boolean
isdir:
description: if the path is a directory or not
returned: success, path exists
sample: true
type: boolean
ishidden:
description: if the path is hidden or not
returned: success, path exists
sample: true
type: boolean
islnk:
description: if the path is a symbolic link or junction or not
returned: success, path exists
sample: true
type: boolean
isreadonly:
description: if the path is read only or not
returned: success, path exists
sample: true
type: boolean
isshared:
description: if the path is shared or not
returned: success, path exists
sample: true
type: boolean
lastaccesstime:
description: the last access time of the file represented in seconds since epoch
returned: success, path exists
sample: 1477984205.15
type: float
lastwritetime:
description: the last modification time of the file represented in seconds since
epoch
returned: success, path exists
sample: 1477984205.15
type: float
lnk_source:
description: the target of the symbolic link, will return null if not a link
or the link is broken
return: success, path exists, path is a symbolic link
sample: C:\temp
type: string
owner:
description: the owner of the file
returned: success, path exists
sample: BUILTIN\Administrators
type: string
path:
description: the full absolute path to the file
returned: success, path exists
sample: BUILTIN\Administrators
type: string
sharename:
description: the name of share if folder is shared
returned: success, path exists, path is a directory and isshared == True
sample: file-share
type: string
size:
description: the size in bytes of a file or folder
returned: success, path exists, path is not a link
sample: 1024
type: int
description: Information on the files/folders that match the criteria returned as
a list of dictionary elements for each file matched
returned: success
type: dictionary
matched:
description: The number of files/folders that match the criteria
returns: always
sample: 2
type: int