ansible.windows.win_stat – Get information about Windows files

Note

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

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

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

Synopsis

  • Returns information about a Windows file.

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

Parameters

Parameter Choices/Defaults Comments
checksum_algorithm
string
    Choices:
  • md5
  • sha1 ←
  • sha256
  • sha384
  • sha512
Algorithm to determine checksum of file.
Will throw an error if the host is unable to use specified algorithm.
follow
boolean
    Choices:
  • no ←
  • yes
Whether to follow symlinks or junction points.
In the case of path pointing to another link, then that will be followed until no more links are found.
get_checksum
boolean
    Choices:
  • no
  • yes ←
Whether to return a checksum of the file (default sha1)
path
path / required
The full path of the file/object to get the facts of; both forward and back slashes are accepted.

aliases: dest, name

See Also

See also

ansible.builtin.stat

The official documentation on the ansible.builtin.stat module.

ansible.windows.win_acl

The official documentation on the ansible.windows.win_acl module.

ansible.windows.win_file

The official documentation on the ansible.windows.win_file module.

ansible.windows.win_owner

The official documentation on the ansible.windows.win_owner module.

Examples

- name: Obtain information about a file
  ansible.windows.win_stat:
    path: C:\foo.ini
  register: file_info

- name: Obtain information about a folder
  ansible.windows.win_stat:
    path: C:\bar
  register: folder_info

- name: Get MD5 checksum of a file
  ansible.windows.win_stat:
    path: C:\foo.ini
    get_checksum: yes
    checksum_algorithm: md5
  register: md5_checksum

- debug:
    var: md5_checksum.stat.checksum

- name: Get SHA1 checksum of file
  ansible.windows.win_stat:
    path: C:\foo.ini
    get_checksum: yes
  register: sha1_checksum

- debug:
    var: sha1_checksum.stat.checksum

- name: Get SHA256 checksum of file
  ansible.windows.win_stat:
    path: C:\foo.ini
    get_checksum: yes
    checksum_algorithm: sha256
  register: sha256_checksum

- debug:
    var: sha256_checksum.stat.checksum

Return Values

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

Key Returned Description
changed
boolean
always
Whether anything was changed

Sample:
True
stat
complex
success
dictionary containing all the stat data

 
attributes
string
success, path exists
Attributes of the file at path in raw form.

Sample:
Archive, Hidden
 
checksum
string
success, path exist, path is a file, get_checksum == True checksum_algorithm specified is supported
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
If the path exists or not.

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, path is a file
The name of the file (without path).

Sample:
foo.ini
 
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 or not.

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

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.

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 and the path is a symbolic link or junction point
Target of the symlink normalized for the remote filesystem.

Sample:
C:\temp\link
 
lnk_target
string
success, path exists and the path is a symbolic link or junction point
Target of the symlink. Note that relative paths remain relative.

Sample:
..\link
  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, file exists
The full absolute path to the file.

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

Sample:
file-share
 
size
integer
success, path exists, file is not a link
The size in bytes of a file or folder.

Sample:
1024


Authors

  • Chris Church (@cchurch)