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

Note

This module is part of the ansible.windows collection (version 2.3.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

  • 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

Retrieve file or file system status.

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"

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)