issue 4808 (#4833)

Author: davidsmatlak

reference/5.0/Microsoft.PowerShell.Archive/Compress-Archive.md

@@ -12,7 +12,7 @@ title: Compress-Archive
 # Compress-Archive
 
 ## SYNOPSIS
-Creates an archive, or zipped file, from specified files and folders.
+Creates a compressed archive, or zipped file, from specified files and folders.
 
 ## SYNTAX
 
@@ -60,55 +60,71 @@ Compress-Archive -LiteralPath <String[]> [-DestinationPath] <String> [-Compressi
 
 ## DESCRIPTION
 
-The `Compress-Archive` cmdlet creates a zipped (or compressed) archive file from one or more
-specified files or folders. An archive file allows multiple files to be packaged, and optionally
-compressed, into a single zipped file for easier distribution and storage. An archive file can be
-compressed by using the compression algorithm specified by the CompressionLevel parameter.
+The `Compress-Archive` cmdlet creates a compressed, or zipped, archive file from one or more
+specified files or folders. An archive packages multiple files, with optional compression, into a
+single zipped file for easier distribution and storage. An archive file can be compressed by using
+the compression algorithm specified by the **CompressionLevel** parameter.
 
-The `Compress-Archive` cmdlet relies upon the Microsoft .NET API `System.IO.Compression.ZipArchive`
-to compress files. Therefore, the maximum file size that is 2 GB. This is a limitation of the
-underlying API.
+The `Compress-Archive` cmdlet uses the Microsoft .NET API [System.IO.Compression.ZipArchive](/dotnet/api/system.io.compression.ziparchive)
+to compress files. The maximum file size is 2 GB because there's a limitation of the underlying API.
+
+Some examples use splatting to reduce the line length of the code samples. For more information, see
+[about_Splatting](../Microsoft.PowerShell.Core/About/about_Splatting.md).
 
 ## EXAMPLES
 
 ### Example 1: Create an archive file
 
-This command creates a new archive file, `Draft.zip`, by compressing two files, `Draftdoc.docx` and
+This example creates a new archive file, `Draft.zip`, by compressing two files, `Draftdoc.docx` and
 `diagram2.vsd`, specified by the **Path** parameter. The compression level specified for this
-operation is Optimal.
+operation is **Optimal**.
 
 ```powershell
-Compress-Archive -Path C:\Reference\Draftdoc.docx, C:\Reference\Images\diagram2.vsd -CompressionLevel Optimal -DestinationPath C:\Archives\Draft.Zip
+$compress = @{
+Path= "C:\Test\Reference\Draftdoc.docx", "C:\Test\Reference\Images\diagram2.vsd"
+CompressionLevel = "Optimal"
+DestinationPath = "C:\Test\Archives\Draft.Zip"
+}
+Compress-Archive @compress
 ```
 
-### Example 2: Create an archive file (using LiteralPath)
+### Example 2: Create an archive file using LiteralPath
 
-This command creates a new archive file, `Draft.zip`, by compressing two files, `Draft doc.docx` and
-`Diagram [2].vsd`, specified by the **LiteralPath** parameter. The compression level specified for this
-operation is Optimal.
+This example creates a new archive file, `Draft.zip`, by compressing two files, `Draft doc.docx` and
+`Diagram [2].vsd`, specified by the **LiteralPath** parameter. The compression level specified for
+this operation is **Optimal**.
 
 ```powershell
-Compress-Archive -LiteralPath 'C:\Reference\Draft Doc.docx', 'C:\Reference\Images\Diagram [2].vsd'  -CompressionLevel Optimal -DestinationPath C:\Archives\Draft.Zip
+$compress = @{
+LiteralPath= "C:\Test\Reference\Draft Doc.docx", "C:\Test\Reference\Images\Diagram [2].vsd"
+CompressionLevel = "Optimal"
+DestinationPath = "C:\Test\Archives\Draft.Zip"
+}
+Compress-Archive @compress
 ```
 
 ### Example 3: Create an archive with wildcard characters
 
-This command creates a new archive file, `Draft.zip`, in the `C:\Archives` folder. The new archive
-file contains every file in the `C:\Reference` folder, because a wildcard character was used in
-place of specific file names in the **Path** parameter.
+This example creates a new archive file, `Draft.zip`, in the `C:\Archives` folder. The new archive
+file contains every file, folder, and subfolder in the `C:\Reference` root folder, because an
+asterisk (`*`) wildcard character was used in place of specific file names in the **Path**
+parameter. The root folder, `Reference`, is excluded from the archive.
 
 ```powershell
 Compress-Archive -Path C:\Reference\* -CompressionLevel Fastest -DestinationPath C:\Archives\Draft
 ```
 
-Notice that the file name extension .zip was not added to the value of the **DestinationPath**
-parameter. PowerShell appends the .zip extension to the file name automatically. The specified
-compression level is **Fastest**, which might result in a larger output file, but compresses a large
-number of files faster.
+Notice that the file name extension `.zip` wasn't added to the value of the **DestinationPath**
+parameter. PowerShell appends the `.zip` extension to the file name automatically. The specified
+compression level is **Fastest**. The faster compression level will compress large numbers of files
+faster, but might result in a larger output file.
+
+> [!NOTE]
+> To zip only the files in the specified root folder, use the **star-dot-star** (`*.*`) wildcard.
 
 ### Example 4: Update an existing archive file
 
-This command updates an existing archive file, Draft.Zip, in the C:\Archives folder.
+This example updates an existing archive file, `Draft.Zip`, in the `C:\Archives` folder.
 
 ```powershell
 Compress-Archive -Path C:\Reference\* -Update -DestinationPath C:\Archives\Draft.Zip
@@ -120,29 +136,31 @@ C:\Reference folder, and also to add new files that have been added to `C:\Refer
 
 ### Example 5: Create an archive from an entire folder
 
-This command creates an archive from an entire folder, C:\Reference.
+This example creates an archive from an entire folder, `C:\Reference`. The archive contains the root
+folder, `Reference`, and all its files, folders, and subfolders.
 
 ```powershell
 Compress-Archive -Path C:\Reference -DestinationPath C:\Archives\Draft
 ```
 
-Notice that the file name extension .zip was not added to the value of the **DestinationPath**
-parameter. PowerShell appends the .zip extension to the file name automatically.
+Notice that the file name extension `.zip` wasn't added to the value of the **DestinationPath**
+parameter. PowerShell appends the `.zip` extension to the file name automatically.
 
 ## PARAMETERS
 
 ### -CompressionLevel
 
-Specifies how much compression to apply when you are creating the archive file. Faster compression
-requires less time to create the file, but can result in larger file sizes. The acceptable values
-for this parameter are:
+Specifies how much compression to apply when you're creating the archive file. Faster compression
+requires less time to create the file, but can result in larger file sizes.
 
-- **Fastest**. Use the fastest compression method available to decrease processing time; this can result
-  in larger file sizes.
-- **NoCompression**. Do not compress the source files.
-- **Optimal**. Processing time is dependent on file size.
+If this parameter isn't specified, the command uses the default value, **Optimal**.
 
-If this parameter is not specified, the command uses the default value, Optimal.
+The acceptable values for this parameter are as follows:
+
+- **Fastest**. Use the fastest compression method available to reduce processing time. Faster
+  compression can result in larger file sizes.
+- **NoCompression**. Doesn't compress the source files.
+- **Optimal**. Processing time is dependent on file size.
 
 ```yaml
 Type: String
@@ -157,12 +175,28 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Confirm
+
+Prompts you for confirmation before running the cmdlet.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: cf
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -DestinationPath
 
 Specifies the path to the archive output file. This parameter is required. The specified
-**DestinationPath** value should include the desired name of the output zipped file; it specifies
+**DestinationPath** value should include the desired name of the output zipped file, and specifies
 either the absolute or relative path to the zipped file. If the file name specified in
-**DestinationPath** does not have a .zip file name extension, the cmdlet adds a .zip file name
+**DestinationPath** doesn't have a `.zip` file name extension, the cmdlet adds a `.zip` file name
 extension.
 
 ```yaml
@@ -196,7 +230,7 @@ Accept wildcard characters: False
 ### -LiteralPath
 
 Specifies the path or paths to the files that you want to add to the archive zipped file. Unlike the
-**Path** parameter, the value of **LiteralPath** is used exactly as it is typed. No characters are
+**Path** parameter, the value of **LiteralPath** is used exactly as it's typed. No characters are
 interpreted as wildcards. If the path includes escape characters, enclose each escape character in
 single quotation marks, to instruct PowerShell not to interpret any characters as escape sequences.
 To specify multiple paths, and include files in multiple locations in your output zipped file, use
@@ -221,6 +255,19 @@ parameter can accept wildcard characters. Wildcard characters allow you to add a
 to your zipped archive file. To specify multiple paths, and include files in multiple locations in
 your output zipped file, use commas to separate the paths.
 
+To zip all the files, folders, and subfolders in a specified root folder, use the asterisk (`*`)
+wildcard. The root folder is excluded from the archive.
+
+For example:
+
+`-Path C:\Reference\*`
+
+To zip only the files in the specified root folder, use the **star-dot-star** (`*.*`) wildcard.
+
+For example:
+
+`-Path C:\Reference\*.*`
+
 ```yaml
 Type: String[]
 Parameter Sets: Path, PathWithUpdate, PathWithForce
@@ -235,9 +282,9 @@ Accept wildcard characters: True
 
 ### -Update
 
-Updates the specified archive by replacing older versions of files in the archive with newer
-versions of files that have the same names. You can also add this parameter to add files to an
-existing archive.
+Updates the specified archive by replacing older file versions in the archive with newer file
+versions that have the same names. You can also add this parameter to add files to an existing
+archive.
 
 ```yaml
 Type: SwitchParameter
@@ -251,25 +298,9 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Confirm
-
-Prompts you for confirmation before running the cmdlet.
-
-```yaml
-Type: SwitchParameter
-Parameter Sets: (All)
-Aliases: cf
-
-Required: False
-Position: Named
-Default value: False
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -WhatIf
 
-Shows what would happen if the cmdlet runs. The cmdlet is not run.
+Shows what would happen if the cmdlet runs. The cmdlet isn't run.
 
 ```yaml
 Type: SwitchParameter
@@ -287,8 +318,7 @@ Accept wildcard characters: False
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
 -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
--WarningAction, and -WarningVariable. For more information, see
-[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS
 
@@ -304,5 +334,4 @@ You can pipe a string that contains a path to one or more files.
 
 ## RELATED LINKS
 
-[Expand-Archive](expand-archive.md)
-
+[Expand-Archive](Expand-Archive.md)