win_find – Return a list of files based on specific criteria

From Get docs
Ansible/docs/2.8/modules/win find module


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.

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

  • 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

  • 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

  • directory
  • file

Type of file to search for.

follow

boolean

  • no

  • yes

Set this to yes to follow symlinks in the path.

This needs to be used in conjunction with recurse.

get_checksum

boolean

  • 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

  • no

  • yes

Set this to include hidden files or folders.

paths

list / 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

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.

recurse

boolean

  • 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

  • no

  • yes

Will set patterns to run as a regex check if set to yes.



Examples

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

- name: Find files and do not return the checksum
  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

extension

string

success, path exists, path is a file

The extension of the file at path.


Sample:

.ps1

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

islnk

boolean

success, path exists

If the path is a symbolic link or junction or not.


Sample:

True

isreadonly

boolean

success, path exists

If the path is read only 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

The target of the symbolic link, will return null if not a link or the link is broken.


Sample:

C:\temp

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 not a link

The size in bytes of a file or folder.


Sample:

1024

matched

integer

always

The number of files/folders that match the criteria.


Sample:

2




Status

Authors

  • Jordan Borean (@jborean93)

Hint

If you notice any issues in this documentation you can edit this document to improve it.


© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/win_find_module.html