ansible.windows.win_find – Return a list of files based on specific criteria
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.3.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 |
|
Choose the file property against which we compare The default attribute we compare with is the last modification time. |
checksum_algorithm string |
|
Algorithm to determine the checksum of a file. Will throw an error if the host is unable to use specified algorithm. |
file_type string |
|
Type of file to search for. |
follow boolean |
|
Set this to This needs to be used in conjunction with |
get_checksum boolean |
|
Whether to return a checksum of the file in the return info (default sha1), use |
hidden boolean |
|
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 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.
| |
recurse boolean |
|
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 |
|
Will set patterns to run as a regex check if set to |
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)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/ansible/windows/win_find_module.html