You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

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

Note

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

- 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: yes

- 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: yes
    purge: yes

- 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