I too found the documentation less than helpful. I did some tests to see how the -Container parameter works in conjunction with -Recurse when copying files and folders.
Note that -Container means -Container: $true.
This is the file structure I used for the examples:
# X:.
# ├───destination
# └───source
# │ source.1.txt
# │ source.2.txt
# │
# └───source.1
# source.1.1.txt
- For all examples, the current location (pwd) is
X:\.
- I used PowerShell 4.0.
1) To copy just the source folder (empty folder):
Copy-Item -Path source -Destination .\destination
Copy-Item -Path source -Destination .\destination -Container
# X:.
# ├───destination
# │ └───source
# └───source (...)
The following gives an error:
Copy-Item -Path source -Destination .\destination -Container: $false
# Exception: Container cannot be copied to another container.
# The -Recurse or -Container parameter is not specified.
2) To copy the whole folder structure with files:
Copy-Item -Path source -Destination .\destination -Recurse
Copy-Item -Path source -Destination .\destination -Recurse -Container
# X:.
# ├───destination
# │ └───source
# │ │ source.1.txt
# │ │ source.2.txt
# │ │
# │ └───source.1
# │ source.1.1.txt
# └───source (...)
3) To copy all descendants (files and folders) into a single folder:
Copy-Item -Path source -Destination .\destination -Recurse -Container: $false
# X:.
# ├───destination
# │ │ source.1.1.txt
# │ │ source.1.txt
# │ │ source.2.txt
# │ │
# │ └───source.1
# └───source (...)
