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

Note

This plugin is part of the community.windows collection (version 1.3.0).

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)