Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC for Microsoft.PowerShell.Archive v2.0.0 #117

Open
wants to merge 9 commits into
base: master
Choose a base branch
from
Open

RFC for Microsoft.PowerShell.Archive v2.0.0 #117

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
f4ca331
added rfc
Jul 6, 2022
b3faf00
Update rfc/RFCNNNN-Archive-Module-v2.md
ayousuf23 Jul 6, 2022
5cfe423
fixed typo in RFC
ayousuf23 Jul 14, 2022
1f3ee10
modified RFC, updated parameter sets, updated relative path structure…
Jul 20, 2022
cc4d45c
Merge branch 'rfc' of github.com:ayousuf23/Microsoft.PowerShell.Archi…
Jul 20, 2022
d21e4ae
minor formatting update
Jul 20, 2022
5290691
updated RFC description
Jul 25, 2022
5bd0b4d
updated section on relative path structure preservation
ayousuf23 Aug 11, 2022
dcf7716
updated parameter sets, section for filtering an archive
ayousuf23 Aug 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 19 additions & 18 deletions rfc/RFCNNNN-Archive-Module-v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ RFC:
Author: Abdullah Yousuf
Status: Draft
SupercededBy:
Version: 1.0
Version: 1.1
Area: Archive
Comments Due: 8/6/2022
Plan to implement: Yes
Expand Down Expand Up @@ -81,17 +81,9 @@ Relative path structure refers to the hierarchial structure of a path relative t
Parameter sets:

```powershell
Compress-Archive [-Path] <string[]> [-DestinationPath] <string> [-CompressionLevel {Optimal | NoCompression | Fastest | SmallestSize}] [-PassThru] [-Format {zip | tar | tgz}] [-Filter <string[]>] [-Flatten] [-WhatIf] [-Confirm] [<CommonParameters>]
Compress-Archive [-Path] <string[]> [-DestinationPath] <string> [-WriteMode {Create | Update | Overwrite}] [-CompressionLevel {Optimal | NoCompression | Fastest | SmallestSize}] [-PassThru] [-Format {zip | tar | tgz}] [-Filter <string[]>] [-Flatten] [-WhatIf] [-Confirm] [<CommonParameters>]

Compress-Archive [-Path] <string[]> [-DestinationPath] <string> -Overwrite [-CompressionLevel {Optimal | NoCompression | Fastest | SmallestSize}] [-PassThru] [-Format {zip | tar | tgz}] [-Filter <string[]>] [-Flatten] [-WhatIf] [-Confirm] [<CommonParameters>]

Compress-Archive [-Path] <string[]> [-DestinationPath] <string> -Update [-CompressionLevel {Optimal |NoCompression | Fastest | SmallestSize}] [-PassThru] [-Format {zip | tar | tgz}] [-Filter <string[]>] [-Flatten] [-WhatIf] [-Confirm] [<CommonParameters>]

Compress-Archive [-DestinationPath] <string> -LiteralPath <string[]> [-CompressionLevel {Optimal | NoCompression | Fastest | SmallestSize}] [-PassThru] [-Format {zip | tar | tgz}] [-Filter <string[]>] [-Flatten] [-WhatIf] [-Confirm] [<CommonParameters>]

Compress-Archive [-DestinationPath] <string> -LiteralPath <string[]> -Overwrite [-CompressionLevel {Optimal | NoCompression | Fastest | SmallestSize}] [-PassThru] [-Format {zip | tar | tgz}] [-Filter <string[]>] [-Flatten] [-WhatIf] [-Confirm] [<CommonParameters>]

Compress-Archive [-DestinationPath] <string> -LiteralPath <string[]> -Update [-CompressionLevel {Optimal | NoCompression | Fastest | SmallestSize}] [-PassThru] [-Format {zip | tar | tgz}] [-Filter <string[]>] [-Flatten] [-WhatIf] [-Confirm] [<CommonParameters>]
Compress-Archive -LiteralPath <string[]> [-DestinationPath] <string> [-WriteMode {Create | Update | Overwrite}] [-CompressionLevel {Optimal | NoCompression | Fastest | SmallestSize}] [-PassThru] [-Format {zip | tar | tgz}] [-Filter <string[]>] [-Flatten] [-WhatIf] [-Confirm] [<CommonParameters>]

```

Expand Down Expand Up @@ -218,7 +210,9 @@ Note that `.zip` is not appended to the archive name.

#### **Relative Path Structure Preservation**

When valid path(s) is supplied to the `-Path` or `-LiteralPath` parameter, the relative structure of the path is preserved as long as the path is not absolute, and does not contain ~ or .. (the path can contain other wildcard characters such as *, [, ], ?, and `).
When valid paths are supplied to the `-Path` or `-LiteralPath` parameter, the relative structures of the paths are preserved as long as the paths are not rooted, and do not contain ..
The paths must be relative to current working directory.
When `-Path` is used, globbing is still performed.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See above that preserving the path will be a breaking change for existing scripts
In a PATH parameter File[12] means File1 or File2 in a literal path [12] is allowed to mean the twelfth file of a a set. It is important that users can still use (e.g) "Log[0-9]*.txt" to include files with "log" a digit and anything else. but exclude "Logarithms.txt" - I think this probably understood, but it does not come through reading the text.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The -LiteralPath parameter behaves the same as before in regard to interpreting wildcard characters literally (i.e., not expanding wildcard characters).

Example: `Compress-Archive -Path Documents\MyFile.txt -DestinationPath destination.zip`
creates an archive with the structure:
Expand Down Expand Up @@ -256,7 +250,7 @@ Note that the `Documents` folder is not retained in the archive.

Example: `Compress-Archive -Path Documents -DestinationPath destination.zip -Flatten` creates an archive which only contains the files in or descended from `Documents` and these files are the top-level items.

The `-Flatten` parameter can be used with `-Update`.
The `-Flatten` parameter can be used with `-WriteMode Update`.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-Update is used in existing scripts, so is needed to avoid breaking them.

-Writemode is better , so the code needs to have an Update switch with the DontShow flag set, and if specified this will set the value Writemode.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea!

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The same goes with -Force to avoid a breaking change a hidden force parameter that sets WriteMode to Overwrite.

In such case, only the added items are flattened.

Example: Suppose we have `archive.zip` which has the following structure:
Expand All @@ -267,7 +261,7 @@ archive.zip
| |---file1.txt
```

After calling `Compress-Archive -Path Documents/file2.txt -DestinationPath archive.zip -Update`, `archive.zip` becomes as follows:
After calling `Compress-Archive -Path Documents/file2.txt -DestinationPath archive.zip -WriteMode Update`, `archive.zip` becomes as follows:

```
archive.zip
Expand Down Expand Up @@ -381,14 +375,21 @@ When files and/or folders with different paths resolve to the same entry name in

Example: `Compress-Archive -Path ~/Documents/Folder1/file.txt,~/Documents/Folder2/file.txt -DestinationPath destination.zip -Flatten` creates an archive that contains `file.txt` from `~/Documents/Folder2/file.txt` because it overwrites the file from `~/Documents/Folder1/file.txt`.

If the destination path already exists when `Compress-Archive` is called and `-Update` is not specified, a terminating error is thrown.
`-Overwrite` can be specified to overwrite the file at the destination path (as long as it is a file and not a folder).
If the destination path already exists when `Compress-Archive` is called and `-WriteMode Update` is not specified, a terminating error is thrown.
`-WriteMode Overwrite` can be specified to overwrite the file at the destination path (as long as it is a file and not a folder).

Example: Suppose `archive.tar` already exists. `Compress-Archive -Path file.txt -DestinationPath archive.tar` results in a terminating error.

Example: Suppose `archive.tar` already exists and is a file. `Compress-Archive -Path file.txt -DestinationPath archive.tar -Overwrite` creates a new archive overwriting `archive.tar`.
Example: Suppose `archive.tar` already exists and is a file. `Compress-Archive -Path file.txt -DestinationPath archive.tar -WriteMode Overwrite` creates a new archive overwriting `archive.tar`.

Example: Suppose `archive.tar` already exists and is a folder. `Compress-Archive -Path file.txt -DestinationPath archive.tar -WriteMode Overwrite` results in a terminating error.

### `-WriteMode` parameter
The `-WriteMode` parameter is an enum that accepts three possible choices: `Create`, `Update` or `Overwrite`.

Example: Suppose `archive.tar` already exists and is a folder. `Compress-Archive -Path file.txt -DestinationPath archive.tar -Overwrite` results in a terminating error.
`-WriteMode Create` creates an archive normally.
`-WriteMode Update` updates an archive.
`-WriteMode Overwrite` overwrites an archive with a new archive.

### Expand-Archive

Expand Down