1#!/usr/local/bin/python3.8
2# -*- coding: utf-8 -*-
3
4# Copyright: (c) 2015, Corwin Brown <blakfeld@gmail.com>
5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
6
7DOCUMENTATION = r'''
8---
9module: win_robocopy
10short_description: Synchronizes the contents of two directories using Robocopy
11description:
12- Synchronizes the contents of files/directories from a source to destination.
13- Under the hood this just calls out to RoboCopy, since that should be available
14  on most modern Windows systems.
15options:
16  src:
17    description:
18    - Source file/directory to sync.
19    type: path
20    required: yes
21  dest:
22    description:
23    - Destination file/directory to sync (Will receive contents of src).
24    type: path
25    required: yes
26  recurse:
27    description:
28    - Includes all subdirectories (Toggles the C(/e) flag to RoboCopy).
29    - If C(flags) is set, this will be ignored.
30    type: bool
31    default: no
32  purge:
33    description:
34    - Deletes any files/directories found in the destination that do not exist in the source.
35    - Toggles the C(/purge) flag to RoboCopy.
36    - If C(flags) is set, this will be ignored.
37    type: bool
38    default: no
39  flags:
40    description:
41      - Directly supply Robocopy flags.
42      - If set, C(purge) and C(recurse) will be ignored.
43    type: str
44notes:
45- This is not a complete port of the M(ansible.posix.synchronize) module. Unlike the M(ansible.posix.synchronize)
46  module this only performs the sync/copy on the remote machine, not from the Ansible controller to the remote machine.
47- This module does not currently support all Robocopy flags.
48seealso:
49- module: ansible.posix.synchronize
50- module: ansible.windows.win_copy
51author:
52- Corwin Brown (@blakfeld)
53'''
54
55EXAMPLES = r'''
56- name: Sync the contents of one directory to another
57  community.windows.win_robocopy:
58    src: C:\DirectoryOne
59    dest: C:\DirectoryTwo
60
61- name: Sync the contents of one directory to another, including subdirectories
62  community.windows.win_robocopy:
63    src: C:\DirectoryOne
64    dest: C:\DirectoryTwo
65    recurse: yes
66
67- name: Sync the contents of one directory to another, and remove any files/directories found in destination that do not exist in the source
68  community.windows.win_robocopy:
69    src: C:\DirectoryOne
70    dest: C:\DirectoryTwo
71    purge: yes
72
73- name: Sync content in recursive mode, removing any files/directories found in destination that do not exist in the source
74  community.windows.win_robocopy:
75    src: C:\DirectoryOne
76    dest: C:\DirectoryTwo
77    recurse: yes
78    purge: yes
79
80- name: Sync two directories in recursive and purging mode, specifying additional special flags
81  community.windows.win_robocopy:
82    src: C:\DirectoryOne
83    dest: C:\DirectoryTwo
84    flags: /E /PURGE /XD SOME_DIR /XF SOME_FILE /MT:32
85
86- name: Sync one file from a remote UNC path in recursive and purging mode, specifying additional special flags
87  community.windows.win_robocopy:
88    src: \\Server1\Directory One
89    dest: C:\DirectoryTwo
90    flags: file.zip /E /PURGE /XD SOME_DIR /XF SOME_FILE /MT:32
91'''
92
93RETURN = r'''
94cmd:
95    description: The used command line.
96    returned: always
97    type: str
98    sample: robocopy C:\DirectoryOne C:\DirectoryTwo /e /purge
99src:
100    description: The Source file/directory of the sync.
101    returned: always
102    type: str
103    sample: C:\Some\Path
104dest:
105    description: The Destination file/directory of the sync.
106    returned: always
107    type: str
108    sample: C:\Some\Path
109recurse:
110    description: Whether or not the recurse flag was toggled.
111    returned: always
112    type: bool
113    sample: false
114purge:
115    description: Whether or not the purge flag was toggled.
116    returned: always
117    type: bool
118    sample: false
119flags:
120    description: Any flags passed in by the user.
121    returned: always
122    type: str
123    sample: /e /purge
124rc:
125    description: The return code returned by robocopy.
126    returned: success
127    type: int
128    sample: 1
129output:
130    description: The output of running the robocopy command.
131    returned: success
132    type: str
133    sample: "------------------------------------\\n   ROBOCOPY     ::     Robust File Copy for Windows         \\n------------------------------------\\n "
134msg:
135    description: Output interpreted into a concise message.
136    returned: always
137    type: str
138    sample: No files copied!
139'''
140