community.windows.win_robocopy module – Synchronizes the contents of two directories using Robocopy

Note

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

To use it in a playbook, specify: community.windows.win_robocopy.

Synopsis

• Synchronizes the contents of files/directories from a source to destination.

• Under the hood this just calls out to RoboCopy, since that should be available on most modern Windows systems.

Parameters

Parameter	Comments
dest path / required	Destination file/directory to sync (Will receive contents of src).
flags string	Directly supply Robocopy flags. If set, purge and recurse will be ignored.
purge boolean	Deletes any files/directories found in the destination that do not exist in the source. Toggles the /purge flag to RoboCopy. If flags is set, this will be ignored. Choices: false ← (default) true
recurse boolean	Includes all subdirectories (Toggles the /e flag to RoboCopy). If flags is set, this will be ignored. Choices: false ← (default) true
src path / required	Source file/directory to sync.

Notes

Note

• This is not a complete port of the ansible.posix.synchronize module. Unlike the ansible.posix.synchronize module this only performs the sync/copy on the remote machine, not from the Ansible controller to the remote machine.

• This module does not currently support all Robocopy flags.

See Also

See also

ansible.posix.synchronize

The official documentation on the ansible.posix.synchronize module.

ansible.windows.win_copy

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

Examples

- name: Sync the contents of one directory to another
  community.windows.win_robocopy:
    src: C:\DirectoryOne
    dest: C:\DirectoryTwo

- name: Sync the contents of one directory to another, including subdirectories
  community.windows.win_robocopy:
    src: C:\DirectoryOne
    dest: C:\DirectoryTwo
    recurse: true

- name: Sync the contents of one directory to another, and remove any files/directories found in destination that do not exist in the source
  community.windows.win_robocopy:
    src: C:\DirectoryOne
    dest: C:\DirectoryTwo
    purge: true

- name: Sync content in recursive mode, removing any files/directories found in destination that do not exist in the source
  community.windows.win_robocopy:
    src: C:\DirectoryOne
    dest: C:\DirectoryTwo
    recurse: true
    purge: true

- name: Sync two directories in recursive and purging mode, specifying additional special flags
  community.windows.win_robocopy:
    src: C:\DirectoryOne
    dest: C:\DirectoryTwo
    flags: /E /PURGE /XD SOME_DIR /XF SOME_FILE /MT:32

- name: Sync one file from a remote UNC path in recursive and purging mode, specifying additional special flags
  community.windows.win_robocopy:
    src: \\Server1\Directory One
    dest: C:\DirectoryTwo
    flags: file.zip /E /PURGE /XD SOME_DIR /XF SOME_FILE /MT:32

Return Values

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

Key	Description
cmd string	The used command line. Returned: always Sample: "robocopy C:\\DirectoryOne C:\\DirectoryTwo /e /purge"
dest string	The Destination file/directory of the sync. Returned: always Sample: "C:\\Some\\Path"
flags string	Any flags passed in by the user. Returned: always Sample: "/e /purge"
msg string	Output interpreted into a concise message. Returned: always Sample: "No files copied!"
output string	The output of running the robocopy command. Returned: success Sample: "------------------------------------\\n   ROBOCOPY     ::     Robust File Copy for Windows         \\n------------------------------------\\n "
purge boolean	Whether or not the purge flag was toggled. Returned: always Sample: false
rc integer	The return code returned by robocopy. Returned: success Sample: 1
recurse boolean	Whether or not the recurse flag was toggled. Returned: always Sample: false
src string	The Source file/directory of the sync. Returned: always Sample: "C:\\Some\\Path"

Authors

• Corwin Brown (@blakfeld)

Collection links

• Issue Tracker
• Repository (Sources)
• Communication