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

Note

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

You might already have this collection installed if you are using the ansible package. 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
Parameters
See Also
Examples
Return Values

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.

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

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/windows/win_stat_module.html