What is the meaning of Powershell's Copy-Item's -container argument?

I am writing a script for MS PowerShell. This script uses the Copy-Item command. One of the optional arguments to this command is "-container". The documentation for the argument states that specifying this argument "Preserves container objects during the copy operation."

This is all well and good, for I would be the last person to want unpreserved container objects during a copy operation. But in all seriousness, what does this argument do? Particularly in the case where I am copying a disk directory tree from one place to another, what difference does this make to the behavior of the Copy-Item command?

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

The container the documentation is talking about is the folder structure. If you are doing a recursive copy and want to preserve the folder structure, you would use the -container switch. (Note: by default the -container switch is set to true, so you really would not need to specify it. If you wanted to turn it off you could use -container: $false.)

There is a catch to this... if you do a directory listing and pipe it to Copy-Item, it will not preserve the folder structure. If you want to preserve the folder structure, you have to specify the -path property and the -recurse switch.