ansible.windows.win_stat module – Get information about Windows files

Note

This module is part of the ansible.windows collection (version 2.5.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

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	Comments
checksum_algorithm string	Algorithm to determine checksum of file. Will throw an error if the host is unable to use specified algorithm. Choices: "md5" "sha1" ← (default) "sha256" "sha384" "sha512"
follow boolean	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. Choices: false ← (default) true
get_checksum boolean	Whether to return a checksum of the file (default sha1) Choices: false true ← (default)
get_size boolean added in ansible.windows 1.11.0	Whether to return the size of a file or directory. Choices: false true ← (default)
path aliases: dest, name path / required	The full path of the file/object to get the facts of; both forward and back slashes are accepted.

See Also

See also

ansible.builtin.stat

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

ansible.windows.win_acl

Set file/directory/registry/certificate permissions for a system user or group.

ansible.windows.win_file

Creates, touches or removes files or directories.

ansible.windows.win_owner

Set owner.

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: true
    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: true
  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: true
    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	Description
changed boolean	Whether anything was changed Returned: always Sample: true
stat complex	dictionary containing all the stat data Returned: success
attributes string	Attributes of the file at path in raw form. Returned: success, path exists Sample: "Archive, Hidden"
checksum string	The checksum of a file based on checksum_algorithm specified. Returned: success, path exist, path is a file, get_checksum == True checksum_algorithm specified is supported Sample: "09cb79e8fc7453c84a07f644e441fd81623b7f98"
creationtime float	The create time of the file represented in seconds since epoch. Returned: success, path exists Sample: 1477984205.15
exists boolean	If the path exists or not. Returned: success Sample: true
extension string	The extension of the file at path. Returned: success, path exists, path is a file Sample: ".ps1"
filename string	The name of the file (without path). Returned: success, path exists, path is a file Sample: "foo.ini"
hlnk_targets list / elements=string	List of other files pointing to the same file (hard links), excludes the current file. Returned: success, path exists Sample: ["C:\\temp\\file.txt", "C:\\Windows\\update.log"]
isarchive boolean	If the path is ready for archiving or not. Returned: success, path exists Sample: true
isdir boolean	If the path is a directory or not. Returned: success, path exists Sample: true
ishidden boolean	If the path is hidden or not. Returned: success, path exists Sample: true
isjunction boolean	If the path is a junction point or not. Returned: success, path exists Sample: true
islnk boolean	If the path is a symbolic link or not. Returned: success, path exists Sample: true
isreadonly boolean	If the path is read only or not. Returned: success, path exists Sample: true
isreg boolean	If the path is a regular file. Returned: success, path exists Sample: true
isshared boolean	If the path is shared or not. Returned: success, path exists Sample: true
lastaccesstime float	The last access time of the file represented in seconds since epoch. Returned: success, path exists Sample: 1477984205.15
lastwritetime float	The last modification time of the file represented in seconds since epoch. Returned: success, path exists Sample: 1477984205.15
lnk_source string	Target of the symlink normalized for the remote filesystem. Returned: success, path exists and the path is a symbolic link or junction point Sample: "C:\\temp\\link"
lnk_target string	Target of the symlink. Note that relative paths remain relative. Returned: success, path exists and the path is a symbolic link or junction point Sample: "..\\link"
nlink integer	Number of links to the file (hard links). Returned: success, path exists Sample: 1
owner string	The owner of the file. Returned: success, path exists Sample: "BUILTIN\\Administrators"
path string	The full absolute path to the file. Returned: success, path exists, file exists Sample: "C:\\foo.ini"
sharename string	The name of share if folder is shared. Returned: success, path exists, file is a directory and isshared == True Sample: "file-share"
size integer	The size in bytes of a file or folder. Returned: success, path exists, file is not a link, get_size == True Sample: 1024

Authors

• Chris Church (@cchurch)

Collection links

• Issue Tracker
• Repository (Sources)