Update description of -Force parameter (#10498)

MicrosoftDocs · Oct 6, 2023 · 4504512 · 4504512
1 parent 8c2698e
commit 4504512
Show file tree

Hide file tree

Showing 8 changed files with 107 additions and 119 deletions.
diff --git a/reference/5.1/Microsoft.PowerShell.Archive/Compress-Archive.md b/reference/5.1/Microsoft.PowerShell.Archive/Compress-Archive.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Archive-help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Archive
-ms.date: 03/03/2023
+ms.date: 10/06/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.archive/compress-archive?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Compress-Archive
@@ -61,12 +61,12 @@ Compress-Archive -LiteralPath <String[]> [-DestinationPath] <String> [-Compressi
 
 The `Compress-Archive` cmdlet creates a compressed, or zipped, archive file from one or more
 specified files or directories. 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
+a single zipped file for easier distribution and storage. An archive file can be compressed using
 the compression algorithm specified by the **CompressionLevel** parameter.
 
-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.
+The `Compress-Archive` cmdlet uses the **System.IO.Compression.ZipArchive** API to compress files.
+The API limits the maximum file size to 2GB. For more information, see
+[System.IO.Compression.ZipArchive](xref:System.IO.Compression.ZipArchive).
 
 > [!NOTE]
 > The `Compress-Archive` cmdlet ignores hidden files and folders when creating or updating the
@@ -289,7 +289,7 @@ Accept wildcard characters: False
 
 ### -Force
 
-Forces the command to run without asking for user confirmation.
+Use this parameter to overwrite an existing archive file.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -427,12 +427,10 @@ Using recursion and sending objects down the pipeline can duplicate files in you
 example, if you use `Get-ChildItem` with the **Recurse** parameter, each **FileInfo** and
 **DirectoryInfo** object that's sent down the pipeline is added to the archive.
 
-The [ZIP file specification](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT) does not
-specify a standard way of encoding filenames that contain non-ASCII characters. The
-`Compress-Archive` cmdlet uses UTF-8 encoding. Other ZIP archive tools may use a different encoding
-scheme. When extracting files with filenames not stored using UTF-8 encoding, `Expand-Archive` uses
-the raw value found in the archive. This can result in a filename that is different than the source
-filename stored in the archive.
+The `Compress-Archive` cmdlet uses UTF-8 encoding. Other ZIP archive tools may use a different
+encoding scheme. When extracting files with filenames not stored using UTF-8 encoding,
+`Expand-Archive` uses the raw value found in the archive. This can result in a filename that's
+different than the source filename stored in the archive.
 
 ## RELATED LINKS
 

diff --git a/reference/5.1/Microsoft.PowerShell.Archive/Expand-Archive.md b/reference/5.1/Microsoft.PowerShell.Archive/Expand-Archive.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Archive-help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Archive
-ms.date: 12/09/2022
+ms.date: 10/06/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.archive/expand-archive?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Expand-Archive
@@ -62,9 +62,9 @@ Expand-Archive -Path Draftv2.zip -DestinationPath C:\Reference
 
 ### -DestinationPath
 
-By default, `Expand-Archive` creates a folder in the current location that is the same name as the
+By default, `Expand-Archive` creates a folder in the current location that's the same name as the
 ZIP file. The parameter allows you to specify the path to a different folder. The target folder is
-created if it does not exist.
+created if it doesn't exist.
 
 ```yaml
 Type: System.String
@@ -80,7 +80,7 @@ Accept wildcard characters: False
 
 ### -Force
 
-Forces the command to run without asking for user confirmation.
+Use this parameter to overwrite existing files. By default, `Expand-Archive` doesn't overwrite.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -97,7 +97,7 @@ Accept wildcard characters: False
 ### -LiteralPath
 
 Specifies the path to an archive file. Unlike the **Path** parameter, the value of **LiteralPath**
-is used exactly as it is typed. Wildcard characters are not supported. If the path includes escape
+is used exactly as it's typed. Wildcard characters aren't supported. 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.
 
@@ -147,7 +147,7 @@ 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: System.Management.Automation.SwitchParameter
@@ -162,6 +162,7 @@ Accept wildcard characters: False
 ```
 
 ### CommonParameters
+
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
 -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
 -WarningAction, and -WarningVariable. For more information, see
@@ -179,12 +180,10 @@ You can pipe a string that contains a path to an existing archive file.
 
 ## NOTES
 
-The [ZIP file specification](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT) does not
-specify a standard way of encoding filenames that contain non-ASCII characters. The
-`Compress-Archive` cmdlet uses UTF-8 encoding. Other ZIP archive tools may use a different encoding
-scheme. When extracting files with filenames not stored using UTF-8 encoding, `Expand-Archive` uses
-the raw value found in the archive. This can result in a filename that is different than the source
-filename stored in the archive.
+The `Compress-Archive` cmdlet uses UTF-8 encoding. Other ZIP archive tools may use a different
+encoding scheme. When extracting files with filenames not stored using UTF-8 encoding,
+`Expand-Archive` uses the raw value found in the archive. This can result in a filename that's
+different than the source filename stored in the archive.
 
 ## RELATED LINKS
 

diff --git a/reference/7.2/Microsoft.PowerShell.Archive/Compress-Archive.md b/reference/7.2/Microsoft.PowerShell.Archive/Compress-Archive.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Archive-help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Archive
-ms.date: 03/03/2023
+ms.date: 10/06/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.archive/compress-archive?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Compress-Archive
@@ -25,15 +25,15 @@ Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLev
 ### PathWithUpdate
 
 ```
-Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLevel <String>] -Update
- [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
+Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLevel <String>]
+ -Update [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### PathWithForce
 
 ```
-Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLevel <String>] -Force
- [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
+Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLevel <String>]
+ -Force [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### LiteralPathWithUpdate
@@ -61,12 +61,12 @@ Compress-Archive -LiteralPath <String[]> [-DestinationPath] <String> [-Compressi
 
 The `Compress-Archive` cmdlet creates a compressed, or zipped, archive file from one or more
 specified files or directories. 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
+a single zipped file for easier distribution and storage. An archive file can be compressed using
 the compression algorithm specified by the **CompressionLevel** parameter.
 
-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.
+The `Compress-Archive` cmdlet uses the **System.IO.Compression.ZipArchive** API to compress files.
+The API limits the maximum file size to 2GB. For more information, see
+[System.IO.Compression.ZipArchive](xref:System.IO.Compression.ZipArchive).
 
 > [!NOTE]
 > The `Compress-Archive` cmdlet ignores hidden files and folders when creating or updating the
@@ -290,7 +290,7 @@ Accept wildcard characters: False
 
 ### -Force
 
-Forces the command to run without asking for user confirmation.
+Use this parameter to overwrite an existing archive file.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -452,12 +452,10 @@ Using recursion and sending objects down the pipeline can duplicate files in you
 example, if you use `Get-ChildItem` with the **Recurse** parameter, each **FileInfo** and
 **DirectoryInfo** object that's sent down the pipeline is added to the archive.
 
-The [ZIP file specification](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT) does not
-specify a standard way of encoding filenames that contain non-ASCII characters. The
-`Compress-Archive` cmdlet uses UTF-8 encoding. Other ZIP archive tools may use a different encoding
-scheme. When extracting files with filenames not stored using UTF-8 encoding, `Expand-Archive` uses
-the raw value found in the archive. This can result in a filename that is different than the source
-filename stored in the archive.
+The `Compress-Archive` cmdlet uses UTF-8 encoding. Other ZIP archive tools may use a different
+encoding scheme. When extracting files with filenames not stored using UTF-8 encoding,
+`Expand-Archive` uses the raw value found in the archive. This can result in a filename that's
+different than the source filename stored in the archive.
 
 ## RELATED LINKS
 

diff --git a/reference/7.2/Microsoft.PowerShell.Archive/Expand-Archive.md b/reference/7.2/Microsoft.PowerShell.Archive/Expand-Archive.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Archive-help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Archive
-ms.date: 12/09/2022
+ms.date: 10/06/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.archive/expand-archive?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Expand-Archive
@@ -18,15 +18,15 @@ Extracts files from a specified archive (zipped) file.
 ### Path (Default)
 
 ```
-Expand-Archive [-Path] <String> [[-DestinationPath] <String>] [-Force] [-PassThru] [-WhatIf]
- [-Confirm] [<CommonParameters>]
+Expand-Archive [-Path] <String> [[-DestinationPath] <String>] [-Force] [-PassThru]
+ [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### LiteralPath
 
 ```
-Expand-Archive -LiteralPath <String> [[-DestinationPath] <String>] [-Force] [-PassThru] [-WhatIf]
- [-Confirm] [<CommonParameters>]
+Expand-Archive -LiteralPath <String> [[-DestinationPath] <String>] [-Force] [-PassThru]
+ [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -62,9 +62,9 @@ Expand-Archive -Path Draftv2.zip -DestinationPath C:\Reference
 
 ### -DestinationPath
 
-By default, `Expand-Archive` creates a folder in the current location that is the same name as the
+By default, `Expand-Archive` creates a folder in the current location that's the same name as the
 ZIP file. The parameter allows you to specify the path to a different folder. The target folder is
-created if it does not exist.
+created if it doesn't exist.
 
 ```yaml
 Type: System.String
@@ -80,7 +80,7 @@ Accept wildcard characters: False
 
 ### -Force
 
-Forces the command to run without asking for user confirmation.
+Use this parameter to overwrite existing files. By default, `Expand-Archive` doesn't overwrite.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -97,7 +97,7 @@ Accept wildcard characters: False
 ### -LiteralPath
 
 Specifies the path to an archive file. Unlike the **Path** parameter, the value of **LiteralPath**
-is used exactly as it is typed. Wildcard characters are not supported. If the path includes escape
+is used exactly as it's typed. Wildcard characters aren't supported. 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.
 
@@ -163,7 +163,7 @@ 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: System.Management.Automation.SwitchParameter
@@ -178,6 +178,7 @@ Accept wildcard characters: False
 ```
 
 ### CommonParameters
+
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
 -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
 -WarningAction, and -WarningVariable. For more information, see
@@ -202,12 +203,10 @@ the archive.
 
 ## NOTES
 
-The [ZIP file specification](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT) does not
-specify a standard way of encoding filenames that contain non-ASCII characters. The
-`Compress-Archive` cmdlet uses UTF-8 encoding. Other ZIP archive tools may use a different encoding
-scheme. When extracting files with filenames not stored using UTF-8 encoding, `Expand-Archive` uses
-the raw value found in the archive. This can result in a filename that is different than the source
-filename stored in the archive.
+The `Compress-Archive` cmdlet uses UTF-8 encoding. Other ZIP archive tools may use a different
+encoding scheme. When extracting files with filenames not stored using UTF-8 encoding,
+`Expand-Archive` uses the raw value found in the archive. This can result in a filename that's
+different than the source filename stored in the archive.
 
 ## RELATED LINKS
 

diff --git a/reference/7.3/Microsoft.PowerShell.Archive/Compress-Archive.md b/reference/7.3/Microsoft.PowerShell.Archive/Compress-Archive.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Archive-help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Archive
-ms.date: 03/03/2023
+ms.date: 10/06/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.archive/compress-archive?view=powershell-7.3&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Compress-Archive
@@ -25,15 +25,15 @@ Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLev
 ### PathWithUpdate
 
 ```
-Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLevel <String>] -Update
- [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
+Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLevel <String>]
+ -Update [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### PathWithForce
 
 ```
-Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLevel <String>] -Force
- [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
+Compress-Archive [-Path] <String[]> [-DestinationPath] <String> [-CompressionLevel <String>]
+ -Force [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### LiteralPathWithUpdate
@@ -61,12 +61,12 @@ Compress-Archive -LiteralPath <String[]> [-DestinationPath] <String> [-Compressi
 
 The `Compress-Archive` cmdlet creates a compressed, or zipped, archive file from one or more
 specified files or directories. 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
+a single zipped file for easier distribution and storage. An archive file can be compressed using
 the compression algorithm specified by the **CompressionLevel** parameter.
 
-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.
+The `Compress-Archive` cmdlet uses the **System.IO.Compression.ZipArchive** API to compress files.
+The API limits the maximum file size to 2GB. For more information, see
+[System.IO.Compression.ZipArchive](xref:System.IO.Compression.ZipArchive).
 
 > [!NOTE]
 > The `Compress-Archive` cmdlet ignores hidden files and folders when creating or updating the
@@ -290,7 +290,7 @@ Accept wildcard characters: False
 
 ### -Force
 
-Forces the command to run without asking for user confirmation.
+Use this parameter to overwrite an existing archive file.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -452,12 +452,10 @@ Using recursion and sending objects down the pipeline can duplicate files in you
 example, if you use `Get-ChildItem` with the **Recurse** parameter, each **FileInfo** and
 **DirectoryInfo** object that's sent down the pipeline is added to the archive.
 
-The [ZIP file specification](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT) does not
-specify a standard way of encoding filenames that contain non-ASCII characters. The
-`Compress-Archive` cmdlet uses UTF-8 encoding. Other ZIP archive tools may use a different encoding
-scheme. When extracting files with filenames not stored using UTF-8 encoding, `Expand-Archive` uses
-the raw value found in the archive. This can result in a filename that is different than the source
-filename stored in the archive.
+The `Compress-Archive` cmdlet uses UTF-8 encoding. Other ZIP archive tools may use a different
+encoding scheme. When extracting files with filenames not stored using UTF-8 encoding,
+`Expand-Archive` uses the raw value found in the archive. This can result in a filename that's
+different than the source filename stored in the archive.
 
 ## RELATED LINKS