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

Note

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

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 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)