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

Note

This plugin is part of the community.windows collection (version 1.7.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	Choices/Defaults	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	Choices: no ← yes	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.
recurse boolean	Choices: no ← yes	Includes all subdirectories (Toggles the `/e` flag to RoboCopy). If `flags` is set, this will be ignored.
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.

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

Authors

Corwin Brown (@blakfeld)

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

Docs

Docs4dev

Title here