win_robocopy: Check-mode support, improved return code and docs (#25410)

* win_robocopy: Cleanup logic, check-mode support * win_robocopy: Cleanup logic, check-mode support This PR includes: - Improved check-mode support - Clean up documentation - Clean up code structure - Add warnings in special cases * minor fix for typo
7 years ago · 11b50671ba
parent 967fbcb662
commit 11b50671ba
2 changed files with 91 additions and 117 deletions
--- a/lib/ansible/modules/windows/win_robocopy.ps1
+++ b/lib/ansible/modules/windows/win_robocopy.ps1
@ -1,40 +1,26 @@
 #!powershell
-# This file is part of Ansible
 #
 # Copyright 2015, Corwin Brown <corwin.brown@maxpoint.com>
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

 # WANT_JSON
 # POWERSHELL_COMMON

 $params = Parse-Args $args -supports_check_mode $true
-
 $check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false

 $src = Get-AnsibleParam -obj $params -name "src" -type "path" -failifempty $true
 $dest = Get-AnsibleParam -obj $params -name "dest" -type "path" -failifempty $true
 $purge = Get-AnsibleParam -obj $params -name "purge" -type "bool" -default $false
 $recurse = Get-AnsibleParam -obj $params -name "recurse" -type "bool" -default $false
-$flags = Get-AnsibleParam -obj $params -name "flags" -type "string" -default $null
+$flags = Get-AnsibleParam -obj $params -name "flags" -type "string"

 $result = @{
-    src = $src
+    changed = $false
    dest = $dest
-    recurse = $recurse
    purge = $purge
-    changed = $false
+    recurse = $recurse
+    src = $src
 }

 # Search for an Error Message
@ -43,7 +29,7 @@ Function SearchForError($cmd_output, $default_msg) {
    $separator_count = 0
    $error_msg = $default_msg
    ForEach ($line in $cmd_output) {
-        if (-Not $line) {
+        if (-not $line) {
            continue
        }

@ -51,9 +37,8 @@ Function SearchForError($cmd_output, $default_msg) {
            if (Select-String -InputObject $line -pattern "^(\s+)?(\-+)(\s+)?$") {
                $separator_count += 1
            }
-        }
-        Else {
-            If (Select-String -InputObject $line -pattern "error") {
+        } else {
+            if (Select-String -InputObject $line -pattern "error") {
                $error_msg = $line
                break
            }
@ -63,15 +48,16 @@ Function SearchForError($cmd_output, $default_msg) {
    return $error_msg
 }

-# Build Arguments
-$robocopy_opts = @()
-
-if (-Not (Test-Path $src)) {
+if (-not (Test-Path -Path $src)) {
    Fail-Json $result "$src does not exist!"
 }

-$robocopy_opts += $src
-$robocopy_opts += $dest
+# Build Arguments
+$robocopy_opts = @($src, $dest)
+
+if ($check_mode) {
+    $robocopy_opts += "/l"
+}

 if ($flags -eq $null) {
    if ($purge) {
@ -81,85 +67,80 @@ if ($flags -eq $null) {
    if ($recurse) {
        $robocopy_opts += "/e"
    }
-}
-Else {
+} else {
    ForEach ($f in $flags.split(" ")) {
        $robocopy_opts += $f
    }
 }

 $result.flags = $flags
+$result.cmd = "$robocopy $robocopy_opts"

-$robocopy_output = ""
-$rc = 0
-If ($check_mode -eq $true) {
-    $robocopy_output = "Would have copied the contents of $src to $dest"
-    $rc = 0
-}
-Else {
-    Try {
-        &robocopy $robocopy_opts | Tee-Object -Variable robocopy_output | Out-Null
-        $rc = $LASTEXITCODE
-    }
-    Catch {
-        $ErrorMessage = $_.Exception.Message
-        Fail-Json $result "Error synchronizing $src to $dest! Msg: $ErrorMessage"
-    }
+Try {
+    $robocopy_output = &robocopy $robocopy_opts
+    $rc = $LASTEXITCODE
+} Catch {
+    Fail-Json $result "Error synchronizing $src to $dest! Msg: $($_.Exception.Message)"
 }

-$result.return_code = $rc
+$result.msg = "Success"
 $result.output = $robocopy_output
+$result.return_code = $rc # Backward compatibility
+$result.rc = $rc
+
+switch ($rc) {

-$cmd_msg = "Success"
-$changed = $false
-switch ($rc)
-{
    0 {
-        $cmd_msg = "No files copied."
+        $result.msg = "No files copied."
    }
    1 {
-        $cmd_msg = "Files copied successfully!"
-        $changed = $true
+        $result.msg = "Files copied successfully!"
+        $result.changed = $true
+        $result.failed = $false
    }
    2 {
-        $cmd_msg = "Some Extra files or directories were detected. No files were copied."
-        $changed = $true
+        $result.msg = "Some Extra files or directories were detected. No files were copied."
+        Add-Warning $result $result.msg
+        $result.failed = $false
    }
    3 {
-        $cmd_msg = "(2+1) Some files were copied. Additional files were present."
-        $changed = $true
+        $result.msg = "(2+1) Some files were copied. Additional files were present."
+        Add-Warning $result $result.msg
+        $result.changed = $true
+        $result.failed = $false
    }
    4 {
-        $cmd_msg = "Some mismatched files or directories were detected. Housekeeping might be required!"
-        $changed = $true
+        $result.msg = "Some mismatched files or directories were detected. Housekeeping might be required!"
+        Add-Warning $result $result.msg
+        $result.changed = $true
+        $result.failed = $false
    }
    5 {
-        $cmd_msg = "(4+1) Some files were copied. Some files were mismatched."
-        $changed = $true
+        $result.msg = "(4+1) Some files were copied. Some files were mismatched."
+        Add-Warning $result $result.msg
+        $result.changed = $true
+        $result.failed = $false
    }
    6 {
-        $cmd_msg = "(4+2) Additional files and mismatched files exist. No files were copied."
-        $changed = $true
+        $result.msg = "(4+2) Additional files and mismatched files exist. No files were copied."
+        $result.failed = $false
    }
    7 {
-        $cmd_msg = "(4+1+2) Files were copied, a file mismatch was present, and additional files were present."
-        $changed = $true
+        $result.msg = "(4+1+2) Files were copied, a file mismatch was present, and additional files were present."
+        Add-Warning $result $result.msg
+        $result.changed = $true
+        $result.failed = $false
    }
    8 {
-        $error_msg = SearchForError $robocopy_output "Some files or directories could not be copied!"
-        Fail-Json $result $error_msg
+        Fail-Json $result (SearchForError $robocopy_output "Some files or directories could not be copied!")
    }
    { @(9, 10, 11, 12, 13, 14, 15) -contains $_ } {
-        $error_msg = SearchForError $robocopy_output "Fatal error. Check log message!"        
-        Fail-Json $result $error_msg
+        Fail-Json $result (SearchForError $robocopy_output "Fatal error. Check log message!")
    }
    16 {
-        $error_msg = SearchForError $robocopy_output "Serious Error! No files were copied! Do you have permissions to access $src and $dest?"
-        Fail-Json $result $error_msg
+        Fail-Json $result (SearchForError $robocopy_output "Serious Error! No files were copied! Do you have permissions to access $src and $dest?")
    }
-}

-$result.msg = $cmd_msg
-$result.changed = $changed
+}

 Exit-Json $result
--- a/lib/ansible/modules/windows/win_robocopy.py
+++ b/lib/ansible/modules/windows/win_robocopy.py
@ -25,52 +25,45 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                    'status': ['preview'],
                    'supported_by': 'community'}

-
 DOCUMENTATION = r'''
 ---
 module: win_robocopy
-version_added: "2.2"
-short_description: Synchronizes the contents of two directories using Robocopy.
+version_added: '2.2'
+short_description: Synchronizes the contents of two directories using Robocopy
 description:
-    - Synchronizes the contents of two directories on the remote machine. Under the hood this just calls out to RoboCopy, since that should be available
-      on most modern Windows Systems.
+- Synchronizes the contents of two directories on the remote machine.
+- Under the hood this just calls out to RoboCopy, since that should be available
+  on most modern Windows Systems.
 options:
  src:
    description:
-      - Source file/directory to sync.
+    - Source file/directory to sync.
    required: true
  dest:
    description:
-      - Destination file/directory to sync (Will receive contents of src).
+    - Destination file/directory to sync (Will receive contents of src).
    required: true
  recurse:
    description:
-      - Includes all subdirectories (Toggles the `/e` flag to RoboCopy). If "flags" is set, this will be ignored.
-    choices:
-      - true
-      - false
-    default: false
-    required: false
+    - Includes all subdirectories (Toggles the C(/e) flag to RoboCopy).
+    - If C(flags) is set, this will be ignored.
+    type: bool
+    default: 'no'
  purge:
    description:
-      - 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:
-      - true
-      - false
-    default: false
-    required: false
+    - Deletes any files/directories found in the destination that do not exist in the source.
+    - Toggles the C(/purge) flag to RoboCopy. If C(flags) is set, this will be ignored.
+    type: bool
+    default: 'no'
  flags:
    description:
-      - Directly supply Robocopy flags. If set, purge and recurse will be ignored.
-    default: None
-    required: false
-author: Corwin Brown (@blakfeld)
+      - Directly supply Robocopy flags. If set, C(purge) and C(recurse) will be ignored.
+author:
+- Corwin Brown (@blakfeld)
 notes:
-    - This is not a complete port of the "synchronize" module. Unlike the "synchronize" module this only performs the sync/copy on the remote machine,
-      not from the master to the remote machine.
-    - This module does not currently support all Robocopy flags.
-    - Works on Windows 7, Windows 8, Windows Server 2k8, and Windows Server 2k12
+- This is not a complete port of the M(synchronize) module. Unlike the M(synchronize) module this only performs the sync/copy on the remote machine,
+  not from the master to the remote machine.
+- This module does not currently support all Robocopy flags.
 '''

 EXAMPLES = r'''
@ -83,22 +76,22 @@ EXAMPLES = r'''
  win_robocopy:
    src: C:\DirectoryOne
    dest: C:\DirectoryTwo
-    recurse: True
+    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
  win_robocopy:
    src: C:\DirectoryOne
    dest: C:\DirectoryTwo
-    purge: True
+    purge: yes

 - name: Sync content in recursive mode, removing any files/directories found in destination that do not exist in the source
  win_robocopy:
    src: C:\DirectoryOne
    dest: C:\DirectoryTwo
-    recurse: True
-    purge: True
+    recurse: yes
+    purge: yes

- name: Sync Two Directories in recursive and purging mode, specifying additional special flags
+- name: Sync two directories in recursive and purging mode, specifying additional special flags
  win_robocopy:
    src: C:\DirectoryOne
    dest: C:\DirectoryTwo
@ -106,16 +99,21 @@ EXAMPLES = r'''
 '''

 RETURN = r'''
+cmd:
+    description: The used command line
+    returned: always
+    type: string
+    sample: robocopy C:\DirectoryOne C:\DirectoryTwo /e /purge
 src:
    description: The Source file/directory of the sync.
    returned: always
    type: string
-    sample: c:\Some\Path
+    sample: C:\Some\Path
 dest:
    description: The Destination file/directory of the sync.
    returned: always
    type: string
-    sample: c:\Some\Path
+    sample: C:\Some\Path
 recurse:
    description: Whether or not the recurse flag was toggled.
    returned: always
@ -130,9 +128,9 @@ flags:
    description: Any flags passed in by the user.
    returned: always
    type: string
-    sample: "/e /purge"
+    sample: /e /purge
 rc:
-    description: The return code retuned by robocopy.
+    description: The return code returned by robocopy.
    returned: success
    type: int
    sample: 1
@ -146,9 +144,4 @@ msg:
    returned: always
    type: string
    sample: No files copied!
-changed:
-    description: Whether or not any changes were made.
-    returned: always
-    type: bool
-    sample: False
 '''