ansible.windows.win_find – Return a list of files based on specific criteria

Note

This plugin is part of the ansible.windows collection (version 1.5.0).

To install it use: ansible-galaxy collection install ansible.windows.

To use it in a playbook, specify: ansible.windows.win_find.

Synopsis

  • Return a list of files based on specified criteria.

  • Multiple criteria are AND’d together.

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

Parameters

Parameter Choices/Defaults Comments
age
string
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
string
    Choices:
  • atime
  • ctime
  • mtime ←
Choose the file property against which we compare age.
The default attribute we compare with is the last modification time.
checksum_algorithm
string
    Choices:
  • 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
string
    Choices:
  • directory
  • file ←
Type of file to search for.
follow
boolean
    Choices:
  • no ←
  • yes
Set this to yes to follow symlinks in the path.
This needs to be used in conjunction with recurse.
get_checksum
boolean
    Choices:
  • no
  • yes ←
Whether to return a checksum of the file in the return info (default sha1), use checksum_algorithm to change from the default.
hidden
boolean
    Choices:
  • no ←
  • yes
Set this to include hidden files or folders.
paths
list / elements=string / required
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
list / elements=string
One or more (powershell or regex) patterns to compare filenames with.
The type of pattern matching is controlled by use_regex option.
The patterns restrict 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.

aliases: regex, regexp
recurse
boolean
    Choices:
  • no ←
  • yes
Will recursively descend into the directory looking for files or folders.
size
string
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
boolean
    Choices:
  • no ←
  • yes
Will set patterns to run as a regex check if set to yes.

Examples

- name: Find files in path
  ansible.windows.win_find:
    paths: D:\Temp

- name: Find hidden files in path
  ansible.windows.win_find:
    paths: D:\Temp
    hidden: yes

- name: Find files in multiple paths
  ansible.windows.win_find:
    paths:
    - C:\Temp
    - D:\Temp

- name: Find files in directory while searching recursively
  ansible.windows.win_find:
    paths: D:\Temp
    recurse: yes

- name: Find files in directory while following symlinks
  ansible.windows.win_find:
    paths: D:\Temp
    recurse: yes
    follow: yes

- name: Find files with .log and .out extension using powershell wildcards
  ansible.windows.win_find:
    paths: D:\Temp
    patterns: [ '*.log', '*.out' ]

- name: Find files in path based on regex pattern
  ansible.windows.win_find:
    paths: D:\Temp
    patterns: out_\d{8}-\d{6}.log

- name: Find files older than 1 day
  ansible.windows.win_find:
    paths: D:\Temp
    age: 86400

- name: Find files older than 1 day based on create time
  ansible.windows.win_find:
    paths: D:\Temp
    age: 86400
    age_stamp: ctime

- name: Find files older than 1 day with unit syntax
  ansible.windows.win_find:
    paths: D:\Temp
    age: 1d

- name: Find files newer than 1 hour
  ansible.windows.win_find:
    paths: D:\Temp
    age: -3600

- name: Find files newer than 1 hour with unit syntax
  ansible.windows.win_find:
    paths: D:\Temp
    age: -1h

- name: Find files larger than 1MB
  ansible.windows.win_find:
    paths: D:\Temp
    size: 1048576

- name: Find files larger than 1GB with unit syntax
  ansible.windows.win_find:
    paths: D:\Temp
    size: 1g

- name: Find files smaller than 1MB
  ansible.windows.win_find:
    paths: D:\Temp
    size: -1048576

- name: Find files smaller than 1GB with unit syntax
  ansible.windows.win_find:
    paths: D:\Temp
    size: -1g

- name: Find folders/symlinks in multiple paths
  ansible.windows.win_find:
    paths:
    - C:\Temp
    - D:\Temp
    file_type: directory

- name: Find files and return SHA256 checksum of files found
  ansible.windows.win_find:
    paths: C:\Temp
    get_checksum: yes
    checksum_algorithm: sha256

- name: Find files and do not return the checksum
  ansible.windows.win_find:
    paths: C:\Temp
    get_checksum: no

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
examined
integer
always
The number of files/folders that was checked.

Sample:
10
files
complex
success
Information on the files/folders that match the criteria returned as a list of dictionary elements for each file matched. The entries are sorted by the path value alphabetically.
 
attributes
string
success, path exists
attributes of the file at path in raw form.

Sample:
Archive, Hidden
 
checksum
string
success, path exists, path is a file, get_checksum == True
The checksum of a file based on checksum_algorithm specified.

Sample:
09cb79e8fc7453c84a07f644e441fd81623b7f98
 
creationtime
float
success, path exists
The create time of the file represented in seconds since epoch.

Sample:
1477984205.15
 
exists
boolean
success, path exists
Whether the file exists, will always be true for ansible.windows.win_find.

Sample:
True
 
extension
string
success, path exists, path is a file
The extension of the file at path.

Sample:
.ps1
 
filename
string
success, path exists
The name of the file.

Sample:
temp
 
hlnk_targets
list / elements=string
success, path exists
List of other files pointing to the same file (hard links), excludes the current file.

Sample:
['C:\\temp\\file.txt', 'C:\\Windows\\update.log']
 
isarchive
boolean
success, path exists
If the path is ready for archiving or not.

Sample:
True
 
isdir
boolean
success, path exists
If the path is a directory or not.

Sample:
True
 
ishidden
boolean
success, path exists
If the path is hidden or not.

Sample:
True
 
isjunction
boolean
success, path exists
If the path is a junction point.

Sample:
True
 
islnk
boolean
success, path exists
If the path is a symbolic link.

Sample:
True
 
isreadonly
boolean
success, path exists
If the path is read only or not.

Sample:
True
 
isreg
boolean
success, path exists
If the path is a regular file or not.

Sample:
True
 
isshared
boolean
success, path exists
If the path is shared or not.

Sample:
True
 
lastaccesstime
float
success, path exists
The last access time of the file represented in seconds since epoch.

Sample:
1477984205.15
 
lastwritetime
float
success, path exists
The last modification time of the file represented in seconds since epoch.

Sample:
1477984205.15
 
lnk_source
string
success, path exists, path is a symbolic link or junction point
The target of the symlink normalized for the remote filesystem.

Sample:
C:\temp
 
lnk_target
string
success, path exists, path is a symbolic link or junction point
The target of the symlink. Note that relative paths remain relative, will return null if not a link.

Sample:
temp
  nlink
integer
success, path exists
Number of links to the file (hard links)

Sample:
1
 
owner
string
success, path exists
The owner of the file.

Sample:
BUILTIN\Administrators
 
path
string
success, path exists
The full absolute path to the file.

Sample:
BUILTIN\Administrators
 
sharename
string
success, path exists, path is a directory and isshared == True
The name of share if folder is shared.

Sample:
file-share
 
size
integer
success, path exists, path is a file
The size in bytes of the file.

Sample:
1024
matched
integer
always
The number of files/folders that match the criteria.

Sample:
2


Authors

  • Jordan Borean (@jborean93)