Skip to content

Commit 5e89e7f

Browse files
santisqsantisq
authored
Merge pull request #49 from santisq/47-add-password-support-for-ziparchive
Adds password support for zip entires
2 parents e2bf5fe + bcb7810 commit 5e89e7f

64 files changed

Lines changed: 1177 additions & 1016 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,37 @@
11
# CHANGELOG
22

3+
## 12/13/2025
4+
5+
- **Native Zip Entry Objects**
6+
7+
Zip entries returned by `Get-ZipEntry` (and created by `New-ZipEntry`) are now backed directly by `ICSharpCode.SharpZipLib.Zip.ZipEntry`.
8+
This exposes additional useful properties on `ZipEntryBase` derived objects:
9+
- `IsEncrypted` (`bool`) – Indicates whether the entry is encrypted.
10+
- `AESKeySize` (`int`) – AES key size (0, 128, 192, or 256) if AES encryption is used.
11+
- `CompressionMethod` (`ICSharpCode.SharpZipLib.Zip.CompressionMethod`) – The actual compression method used.
12+
- `Comment` (`string`) – The entry comment.
13+
- `Crc` (`long`) – Cyclic redundancy check.
14+
15+
- **Support for Encrypted Zip Entries**
16+
17+
`Get-ZipEntryContent` and `Expand-ZipEntry` now fully support reading and extracting password-protected entries.
18+
A new common parameter has been added to both cmdlets:
19+
20+
```powershell
21+
-Password <SecureString>
22+
```
23+
24+
- If an entry is encrypted and no password is provided, the cmdlets will securely prompt for one.
25+
- Examples and detailed guidance for handling encrypted entries have been added to the help documentation.
26+
27+
- **Documentation Improvements**
28+
29+
All cmdlet help files have been reviewed and updated for consistency and clarity.
30+
Significant enhancements to `Get-ZipEntryContent` and `Expand-ZipEntry` help:
31+
- Added dedicated examples demonstrating password-protected entry handling.
32+
- Updated parameter descriptions and notes for the new `-Password` parameter.
33+
- Improved phrasing, removed outdated example output, and ensured uniform formatting across the module.
34+
335
## 07/02/2025
436

537
- Added `AssemblyLoadContext` support for PowerShell 7 (.NET 8.0 or later) to resolve DLL hell by isolating module dependencies. PowerShell 5.1 (.NET Framework) users can't get around this issue due to lack of `AssemblyLoadContext` in that runtime.

‎README.md‎

Lines changed: 28 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -22,143 +22,38 @@
2222

2323
## Cmdlets
2424

25-
### Zip Archive Cmdlets
26-
27-
<table>
28-
<tr>
29-
<th>Cmdlet</th>
30-
<th>Alias</th>
31-
<th>Description</th>
32-
</tr>
33-
<tr>
34-
<td colspan="1" width="220"><a href="docs/en-US/Compress-ZipArchive.md">Compress-ZipArchive</a></td>
35-
<td><code>zipcompress</code></td>
36-
<td>Compresses files and folders into a zip archive, overcoming built-in PowerShell limitations.</td>
37-
</tr>
38-
<tr>
39-
<td><a href="docs/en-US/Expand-ZipEntry.md">Expand-ZipEntry</a></td>
40-
<td><code>unzipentry</code></td>
41-
<td>Extracts individual zip entries to a destination directory.</td>
42-
</tr>
43-
<tr>
44-
<td><a href="docs/en-US/Get-ZipEntry.md">Get-ZipEntry</a></td>
45-
<td><code>zipge</code></td>
46-
<td>Lists zip archive entries from paths or streams, serving as the entry point for zip cmdlets.</td>
47-
</tr>
48-
<tr>
49-
<td><a href="docs/en-US/Get-ZipEntryContent.md">Get-ZipEntryContent</a></td>
50-
<td><code>zipgec</code></td>
51-
<td>Retrieves the content of zip entries as text or bytes.</td>
52-
</tr>
53-
<tr>
54-
<td><a href="docs/en-US/New-ZipEntry.md">New-ZipEntry</a></td>
55-
<td><code>zipne</code></td>
56-
<td>Adds new entries to a zip archive from files or paths.</td>
57-
</tr>
58-
<tr>
59-
<td><a href="docs/en-US/Remove-ZipEntry.md">Remove-ZipEntry</a></td>
60-
<td><code>ziprm</code></td>
61-
<td>Removes entries from one or more zip archives.</td>
62-
</tr>
63-
<tr>
64-
<td><a href="docs/en-US/Rename-ZipEntry.md">Rename-ZipEntry</a></td>
65-
<td><code>zipren</code></td>
66-
<td>Renames entries in one or more zip archives.</td>
67-
</tr>
68-
<tr>
69-
<td><a href="docs/en-US/Set-ZipEntryContent.md">Set-ZipEntryContent</a></td>
70-
<td><code>zipsc</code></td>
71-
<td>Sets or appends content to a zip entry.</td>
72-
</tr>
73-
</table>
25+
### Zip Archive
26+
27+
- [__`Compress-ZipArchive`__](docs/en-US/Compress-ZipArchive.md) — Compresses files and folders into a zip archive, overcoming built-in PowerShell limitations.
28+
- [__`Expand-ZipEntry`__](docs/en-US/Expand-ZipEntry.md) — Extracts individual zip entries to a destination directory.
29+
- [__`Get-ZipEntry`__](docs/en-US/Get-ZipEntry.md) — Lists zip archive entries from paths or streams, serving as the entry point for zip cmdlets.
30+
- [__`Get-ZipEntryContent`__](docs/en-US/Get-ZipEntryContent.md) — Retrieves the content of zip entries as text or bytes.
31+
- [__`New-ZipEntry`__](docs/en-US/New-ZipEntry.md) — Adds new entries to a zip archive from files or paths.
32+
- [__`Remove-ZipEntry`__](docs/en-US/Remove-ZipEntry.md) — Removes entries from one or more zip archives.
33+
- [__`Rename-ZipEntry`__](docs/en-US/Rename-ZipEntry.md) — Renames entries in one or more zip archives.
34+
- [__`Set-ZipEntryContent`__](docs/en-US/Set-ZipEntryContent.md) — Sets or appends content to a zip entry.
7435

7536
> [!NOTE]
7637
> Due to a .NET limitation, cmdlets like `New-ZipEntry`, `Compress-ZipArchive` with `-Update`, and `Set-ZipEntryContent` may fail when handling files or content > 2 GB __in existing zip archives__. As a workaround, recreate the zip archive or use tools like 7-Zip, which support larger files. See [issue #19](https://github.com/santisq/PSCompression/issues/19) for details.
7738
78-
### Tar Archive Cmdlets
79-
80-
<table>
81-
<tr>
82-
<th>Cmdlet</th>
83-
<th>Alias</th>
84-
<th>Description</th>
85-
</tr>
86-
<tr>
87-
<td colspan="1" width="220"><a href="docs/en-US/Compress-TarArchive.md">Compress-TarArchive</a></td>
88-
<td><code>tarcompress</code></td>
89-
<td>Compresses files and folders into a tar archive with optional compression (gz, bz2, zst, lz, none).</td>
90-
</tr>
91-
<tr>
92-
<td><a href="docs/en-US/Expand-TarArchive.md">Expand-TarArchive</a></td>
93-
<td><code>untar</code></td>
94-
<td>Extracts a tar archive with support for gz, bz2, zst, lz, and uncompressed formats.</td>
95-
</tr>
96-
<tr>
97-
<td><a href="docs/en-US/Expand-TarEntry.md">Expand-TarEntry</a></td>
98-
<td><code>untarentry</code></td>
99-
<td>Extracts individual tar entries to a destination directory.</td>
100-
</tr>
101-
<tr>
102-
<td><a href="docs/en-US/Get-TarEntry.md">Get-TarEntry</a></td>
103-
<td><code>targe</code></td>
104-
<td>Lists tar archive entries from paths or streams, serving as the entry point for tar cmdlets.</td>
105-
</tr>
106-
<tr>
107-
<td><a href="docs/en-US/Get-TarEntryContent.md">Get-TarEntryContent</a></td>
108-
<td><code>targec</code></td>
109-
<td>Retrieves the content of tar entries as text or bytes.</td>
110-
</tr>
111-
</table>
112-
113-
### String Compression Cmdlets
114-
115-
<table>
116-
<tr>
117-
<th>Cmdlet</th>
118-
<th>Alias</th>
119-
<th>Description</th>
120-
</tr>
121-
<tr>
122-
<td colspan="1" width="220"><a href="docs/en-US/ConvertFrom-BrotliString.md">ConvertFrom-BrotliString</a></td>
123-
<td><code>frombrotlistring</code></td>
124-
<td>Decompresses a Brotli-compressed string.</td>
125-
</tr>
126-
<tr>
127-
<td><a href="docs/en-US/ConvertFrom-DeflateString.md">ConvertFrom-DeflateString</a></td>
128-
<td><code>fromdeflatestring</code></td>
129-
<td>Decompresses a Deflate-compressed string.</td>
130-
</tr>
131-
<tr>
132-
<td><a href="docs/en-US/ConvertFrom-GzipString">ConvertFrom-GzipString</a></td>
133-
<td><code>fromgzipstring</code></td>
134-
<td>Decompresses a Gzip-compressed string.</td>
135-
</tr>
136-
<tr>
137-
<td><a href="docs/en-US/ConvertFrom-ZlibString.md">ConvertFrom-ZlibString</a></td>
138-
<td><code>fromzlibstring</code></td>
139-
<td>Decompresses a Zlib-compressed string.</td>
140-
</tr>
141-
<tr>
142-
<td><a href="docs/en-US/ConvertTo-BrotliString.md">ConvertTo-BrotliString</a></td>
143-
<td><code>tobrotlistring</code></td>
144-
<td>Compresses a string using Brotli.</td>
145-
</tr>
146-
<tr>
147-
<td><a href="docs/en-US/ConvertTo-DeflateString.md">ConvertTo-DeflateString</a></td>
148-
<td><code>todeflatestring</code></td>
149-
<td>Compresses a string using Deflate.</td>
150-
</tr>
151-
<tr>
152-
<td><a href="docs/en-US/ConvertTo-GzipString.md">ConvertTo-GzipString</a></td>
153-
<td><code>togzipstring</code></td>
154-
<td>Compresses a string using Gzip.</td>
155-
</tr>
156-
<tr>
157-
<td><a href="docs/en-US/ConvertTo-ZlibString.md">ConvertTo-ZlibString</a></td>
158-
<td><code>tozlibstring</code></td>
159-
<td>Compresses a string using Zlib.</td>
160-
</tr>
161-
</table>
39+
### Tar Archive
40+
41+
- [__`Compress-TarArchive`__](docs/en-US/Compress-TarArchive.md) — Compresses files and folders into a tar archive with optional compression (gz, bz2, zst, lz, none).
42+
- [__`Expand-TarArchive`__](docs/en-US/Expand-TarArchive.md) — Extracts a tar archive with support for gz, bz2, zst, lz, and uncompressed formats.
43+
- [__`Expand-TarEntry`__](docs/en-US/Expand-TarEntry.md) — Extracts individual tar entries to a destination directory.
44+
- [__`Get-TarEntry`__](docs/en-US/Get-TarEntry.md) — Lists tar archive entries from paths or streams.
45+
- [__`Get-TarEntryContent`__](docs/en-US/Get-TarEntryContent.md) — Retrieves the content of tar entries as text or bytes.
46+
47+
### String Compression
48+
49+
- [__`ConvertFrom-BrotliString`__](docs/en-US/ConvertFrom-BrotliString.md) — Decompresses a Brotli-compressed string.
50+
- [__`ConvertFrom-DeflateString`__](docs/en-US/ConvertFrom-DeflateString.md) — Decompresses a Deflate-compressed string.
51+
- [__`ConvertFrom-GzipString`__](docs/en-US/ConvertFrom-GzipString.md) — Decompresses a Gzip-compressed string.
52+
- [__`ConvertFrom-ZlibString`__](docs/en-US/ConvertFrom-ZlibString.md) — Decompresses a Zlib-compressed string.
53+
- [__`ConvertTo-BrotliString`__](docs/en-US/ConvertTo-BrotliString.md) — Compresses a string using Brotli.
54+
- [__`ConvertTo-DeflateString`__](docs/en-US/ConvertTo-DeflateString.md) — Compresses a string using Deflate.
55+
- [__`ConvertTo-GzipString`__](docs/en-US/ConvertTo-GzipString.md) — Compresses a string using Gzip.
56+
- [__`ConvertTo-ZlibString`__](docs/en-US/ConvertTo-ZlibString.md) — Compresses a string using Zlib.
16257

16358
> [!NOTE]
16459
> The `Compress-GzipArchive` and `Expand-GzipArchive` cmdlets have been removed, as their single-file gzip functionality is now handled by `Compress-TarArchive` and `Expand-TarArchive`. For a workaround to compress or decompress single files using gzip, see [Example 2 in `ConvertTo-GzipString`](./docs/en-US/ConvertTo-GzipString.md#example-2-create-a-gzip-compressed-file-from-a-string).

‎assets/helloworld.zip‎

224 Bytes
Binary file not shown.

‎docs/en-US/Compress-TarArchive.md‎

Lines changed: 13 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ schema: 2.0.0
99

1010
## SYNOPSIS
1111

12-
The `Compress-TarArchive` cmdlet creates a compressed tar archive file from one or more specified files or directories. It supports multiple compression algorithms and provides flexible file inclusion and exclusion options, similar to the `Compress-ZipArchive` cmdlet.
12+
The `Compress-TarArchive` cmdlet creates a compressed tar archive file from one or more specified files or directories. It supports multiple compression algorithms and provides flexible file inclusion and exclusion options, similar to the `Compress-ZipArchive` cmdlet in this module.
1313

1414
## SYNTAX
1515

@@ -43,7 +43,7 @@ Compress-TarArchive
4343

4444
## DESCRIPTION
4545

46-
The `Compress-TarArchive` cmdlet creates a tar archive, optionally compressed with algorithms like gzip, bzip2, zstd, or lz4, in a PowerShell-native environment. It simplifies file and directory archiving by integrating seamlessly with PowerShell’s object-oriented pipeline, allowing flexible file selection through cmdlets like `Get-ChildItem` or `Get-Item`. With support for selective inclusion via `-Exclude`, customizable compression levels, and the ability to overwrite existing archives, it provides a convenient alternative to traditional tar utilities for PowerShell users, while preserving directory structures and metadata.
46+
The `Compress-TarArchive` cmdlet creates a tar archive, optionally compressed with algorithms like gzip, bzip2, zstd, or lz4, in a PowerShell-native environment. It simplifies file and directory archiving by integrating seamlessly with PowerShell’s object-oriented pipeline, allowing flexible file selection through cmdlets like `Get-ChildItem` or `Get-Item`. With support for selective exclusion via `-Exclude`, customizable compression levels, and the ability to overwrite existing archives, it provides a convenient alternative to traditional tar utilities for PowerShell users, while preserving directory structures and metadata.
4747

4848
## EXAMPLES
4949

@@ -57,37 +57,35 @@ Get-ChildItem C:\Logs -Recurse -Filter *.log |
5757
This example demonstrates how to compress all `.log` files in the `C:\Logs` directory into a gzip-compressed tar archive named `logs.tar.gz` in the `C:\Archives` directory.
5858

5959
> [!NOTE]
60-
> If not specified, the cmdlet will use the gzip algorithm as default.
60+
> If not specified, the cmdlet uses the gzip algorithm as default.
6161
6262
### Example 2: Compress a folder using `Fastest` Compression Level
6363

6464
```powershell
65-
Compress-TarArchive -Path .\path -Destination myPath.tar.gz -CompressionLevel Fastest
65+
Compress-TarArchive -Path . -Destination myPath.tar.gz -CompressionLevel Fastest
6666
```
6767

68-
This example shows how to compress the entire path directory into a gzip-compressed tar archive named `myPath.tar.gz` using the `Fastest` compression level for quicker processing.
68+
This example shows how to compress the current directory (`.`) into a gzip-compressed tar archive named `myPath.tar.gz` using the `Fastest` compression level for quicker processing.
6969

70-
### Example 3: Replacing an existing Tar Archive
70+
### Example 3: Overwrite an existing tar archive
7171

7272
```powershell
73-
Compress-TarArchive -Path .\path -Destination dest.tar.gz -Force
73+
Compress-TarArchive -Path .\Path -Destination dest.tar.gz -Force
7474
```
7575

7676
This example illustrates how to create a new tar archive named `dest.tar.gz` from the path directory, overwriting any existing archive with the same name using the `-Force` parameter.
7777

7878
### Example 4: Exclude files and folders from source
7979

8080
```powershell
81-
Compress-TarArchive -Path .\path -Destination myPath.tar.gz -Exclude *.xyz, *\test\*
81+
Compress-TarArchive -Path .\Path -Destination myPath.tar.gz -Exclude *.xyz, *\test\*
8282
```
8383

84-
This example shows how to compress all items in `path` excluding all files having a `.xyz` extension and excluding
85-
a folder with name `test` and all its child items.
84+
This example shows how to compress all items in `path` excluding all files having a `.xyz` extension, any folder named `test` and all its child items.
8685

8786
> [!TIP]
8887
>
89-
> The `-Exclude` parameter supports [wildcard patterns](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_wildcards?view=powershell-7.4&viewFallbackFrom=powershell-7.3),
90-
exclusion patterns are tested against the items `.FullName` property.
88+
> The `-Exclude` parameter supports [wildcard patterns](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_wildcards). Exclusion patterns are tested against each item's `.FullName` property.
9189
9290
### Example 5: Compress a directory using bzip2 algorithm
9391

@@ -113,14 +111,14 @@ Aliases:
113111
Accepted values: gz, bz2, zst, lz, none
114112
Required: False
115113
Position: Named
116-
Default value: none
114+
Default value: gz
117115
Accept pipeline input: False
118116
Accept wildcard characters: False
119117
```
120118
121119
### -CompressionLevel
122120
123-
Specifies the compression level for the selected algorithm, balancing speed and file size. See [`CompressionLevel` Enum](https://learn.microsoft.com/en-us/dotnet/api/system.io.compression.compressionlevel) for details. The default is algorithm-dependent but typically `Optimal`.
121+
Specifies the compression level for the selected algorithm, balancing speed and file size. The default is algorithm-dependent but typically `Optimal`.
124122

125123
```yaml
126124
Type: CompressionLevel
@@ -156,9 +154,6 @@ Accept wildcard characters: False
156154

157155
Specifies an array of string patterns to exclude files or directories from the archive. Matching items are excluded based on their `.FullName` property. Wildcard characters are supported.
158156

159-
> [!NOTE]
160-
> Patterns are tested against the object's `.FullName` property.
161-
162157
```yaml
163158
Type: String[]
164159
Parameter Sets: (All)
@@ -263,7 +258,7 @@ This cmdlet is designed to provide a PowerShell-native way to create tar archive
263258

264259
## RELATED LINKS
265260

266-
[__Compress-ZipArchive__](https://github.com/santisq/PSCompression)
261+
[__`Compress-ZipArchive`__](https://github.com/santisq/PSCompression)
267262

268263
[__SharpZipLib__](https://github.com/icsharpcode/SharpZipLib)
269264

0 commit comments

Comments
 (0)